3.2 Prerequisites for Establishing an OAuth 2.0 Connection with a Client Application

3.2.1 Registering Client Applications

Registering a client application includes the following activities:

Getting Client ID And Secret

To get an access token or an ID token, the application needs to send Client Credentials. Client Credentials are unique credentials assigned per client application. Developers need to register their applications to Access Manager with necessary details to use any of the APIs. The details of how to register their applications are specified in Registering a Client Application. After registering the application, Access Manager provides client id and client secret. Note these values.

Registering Redirect URI

A valid redirection URI must be registered with Access Manager along with each client application. Access Manager redirects only to registered URIs for issuing tokens in authorization code grant flow and implicit grant flow. One of the registered URIs must be sent along with requests in these flows.

Registering Authorization Grants

A client application must specify the OAuth2.0 authorization grant flows the application will use. Access Manager issues tokens only in the specified flows. Any request with non-registered flows during client registration is not supported. You can modify this setting after a client is registered.

An administrator can disable few OAuth 2.0 authorization grant flows to minimize the security risk. For example, an administration can disable the use of resource owner credential grant if none of the OAuth 2.0 applications in the organization uses this flow. It is not recommended unless it is required.

Registering OpenID Connect Configuration

Access Manager supports both OAuth 2.0 and OpenID Connect specifications by default. Typically, OAuth2.0 is used for authorization of applications and OpenID Connect is used for authentication. OAuth 2.0 flow issues a security token called access token and OpenID Connect issues ID token and optionally access token.

Access tokens and ID tokens are JSON Web Tokens (JWT) signed by Identity Server and ID tokens are optionally encrypted by the client application's public certificate. The relying party can verify the signature of the ID token and trust that token is issued by trusted Identity Server.

You can register signing algorithm to be used for a JWT token. If your application needs confidentiality of the ID token, provide a publicly accessible URL of public certificate and algorithm in the JWKS format. You need to configure this during the client application registration process.

3.2.2 Managing Client Applications

You can programmatically register, view, modify, and delete a client application in Access Manager.

Before performing any of these actions, you must define your role as NAM_OAUTH2_DEVELOPER or NAM_OAUTH2_ADMIN in the IDP Role policy.

You can register an application in any of the following two ways:

  • Using username and password.

  • Using Access token. To register a client application by using an access token, you must have your role defined as NAM_OAUTH2_DEVELOPER in the IDP Role policy.

Use the resource owner flow to get an access token. The endpoint of the resource owner flow is https://<Identity Server URL: Port Number>/nidp/oauth/nam/token.

This endpoint requires the followings parameters to provide an access token:

Parameter

Value

grant_type

Password

username

Application developer's user name

password

Application developer's password

scope

urn:netiq.com:nam:scope:oauth:registration:full (This scope allows you to register, view, modify, and delete client applications.) urn:netiq.com:nam:scope:oauth:registration:read (This scope provides read-only access)

token endpoint

Identity Server URL: Port Number>/ nidp/oauth/nam/token

Registering a Client Application

To register a client application, the HTTP method value must be POST. Identity Server uses the following endpoint for registering a client application:

https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients

The endpoint requires the following OAuth parameters for client registration:

Parameter

Required/Optional

Description

client_name

Required

Name of the client application.

application_type

Optional

web or native.

enableNativeSSO

Optional

Specify true as a value to enable single sign on for a user who uses the client applications on a desktop or a mobile.

For example, A user accesses client A using the credentials and is authenticated. Client A receives a refresh token and an access token. The user accesses client B immediately or after a few days. If this option is enabled for client B, the client uses the persistent cookie to retrieve the token and authenticate the user. Hence, client B is authenticated automatically.

If this option is not enabled for the client B configuration, then to retrieve refresh token and access tokens, the user is required to provide credentials even though the user has already authenticated for client A.

redirect_uris

Required

Redirection URI values used by the client application.

grant_types

Optional

The following are supported grant types:

  • authorization_code

  • implicit

  • refresh_token

  • resource_owner_credentials

  • client_credentials

  • saml2_assertion

If you do not specify a grant type, the default grant type authorization_code is used.

response_types

Optional

The following list includes supported response types:

  • code

  • code token

  • code id_token token

  • id_token

  • id_token token

  • access_token

  • refresh_token

alwaysIssueNewRefreshToken

Optional

Specify true to issue a new refresh token for each refresh token request.

authzCodeTTL

Optional

Specify the duration in minute after that the authorization code becomes invalid.

accessTokenTTL

Optional

Specify the validity duration access token and ID token in minutes.

refreshTokenTTL

Optional

Specify the validity duration for the refresh token in minutes.

corsdomains

Optional

To allow access to requests from only selected domains, specify the domains as a JSON array.

For example, ["beem://www.test.com", "fb://app.local.url", "https://namapp.com"]

logo_uri

Optional

Specify the URL of the logo that to be included in the consent page.

For example, https://client.example.org/logo.png

policy_uri

Optional

Specify the URL of the relying party client's privacy policy.

For example, https://client.example.org/privacypolicy

tos_uri

Optional

Specify the URL of the relying party's terms of service.

For example, https://client.example.org/terms

contacts

Optional

Specify the email addresses of people related to this client application.

jwks_uri

Optional

Specify the URI of the JSON file containing the json web keys.

This key set contains signing keys that the relying party uses to validate signatures from the OpenID provider.

For example, https://client.example.org/my_public_keys.jwks

id_token_signed_response_alg

Optional

Specify the ID Token Signed Response Algorithm. This algorithm is required for signing the ID token issued to a client.

id_token_encrypted_response_alg

Optional

Specify the algorithm used to encrypt the key.

id_token_encrypted_response_enc

Optional

Specify the algorithm used to encrypt the content.

Modifying a Client Application

Perform the following steps:

  1. Retrieve client details from the https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients/<client ID> endpoint. In the request for retrieving client details, use GET as the HTTP method value.

  2. Send the update request. In the request, use POST as the HTTP method value. Identity Server uses the following endpoint for modifying a registered client application:

    https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients/

    For the list of parameters this endpoint requires for a client application modification, see the table under Registering a Client Application.

NOTE:For updating a client application, you must send the XML with all parameters in the update request. If you do not include a parameter in the XML, the server does not initialize this parameter. For example, to update the response_types parameter, send the updated value for this parameter and existing values for other parameters in the request.

Viewing a Client Application

To view a client application, use GET as the HTTP method value.

  • https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients/: To view all clients applications registered by a developer

  • https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients/<client ID>:To view a specific client application registered by a developer

Deleting a Client Application

To delete a client application, the HTTP method value must be DELETE. Identity Server uses the following endpoint for deleting a registered client application:

https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients/<client ID>

3.2.3 Registering a Resource Server

By default, access tokens are signed by JSON Web Tokens (JWT) and encrypted by Identity Server. Registering a resource server provides more features such as options to encrypt an access token by using the resource server encrypted keys or Identity Server encrypted keys. It also provides an option to not encrypt an access token. This is not recommended as it might cause security issues.

After resource server registration, specify the registered resource server name in the token request for encrypting the access token using the resource server encrypted keys. In this way, no need to contact Identity Server's TokenInfo/UserInfo endpoint for token validation or for claims. Only an Access Manager administrator can register a resource server.

You can register, view, modify, and delete a resource server by using REST API. You must have your role defined as NAM_OAUTH2_ADMIN in the IDP Role policy. You can access this endpoint either by login or using an access token. For more information, see Managing Client Applications.

Send an HTTPS POST request with the appropriate URI parameters to resource server endpoint URI.

Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers

HTTP Method: POST

Request Parameters:

Parameter

Required/Optional

Description

name

Required

The name of the resource server.

disableJWTAccessTokenEncryption

Optional

Specify the value as true for not encrypting the access token.

The value as false to encrypt the access token by using Access Manager key or resource server key.

cryptoKeys

Optional

Specify the resource server's JWKS key details to encrypt the access token using this key.

The parameter value as a sample JSON format is as follows:

{"jwksUri": "https://www.resourcer.server.com/crypto/jwks", "jwtaccessTokenEncryptionAlgo": { "encryptionAlg": "RSA1_225", "encryptionEnc":"A128CBC-HS2563"}

Sample Request and Response

A sample request and response for registering resource server crypto keys in Access Manager, with line breaks for better readability and payload in JSON.

HTTP/1.1 POST /nidp/oauth/nam/token
User-Agent: Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/41.0.2228.0 Safari/537.36

Host: www.idp.com:8443
'{"name":"namResourceServer",

"cryptokeys":{"jwksUri": "https://www.resourcer.server.com/crypto/jwks",
"jwtaccessTokenEncryptionAlgo": { "encryptionAlg": "RSA1_225",
"encryptionEnc":"A128CBC-HS2563"}
}
}'

A successful Response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, no-transform

Deleting a Resource Server

To delete a resource server by using REST API, you must have your role defined as NAM_OAUTH2_ADMIN in the IDP Role policy. To access this endpoint, log in or use an access token. If you use the access token, it should contain the following scope:

Scope:urn:netiq.com:nam:scope:oauth:registration:full

HTTP Method: DELETE

Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers/<resourceServerName>

Viewing Registered Resource Servers

To view all registered resource servers by using REST API, you must have your role defined as NAM_OAUTH2_ADMIN or NAM_OAUTH2_DEVELOPER in the IDP Role policy. To access this endpoint, log in or use an access token. If you use the access token, it should contain the following scope:

Scope: urn:netiq.com:nam:scope:oauth:registration:full

HTTP method: Get

Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers

Creating Scopes

To create a scope by using REST API, you must have your role defined as NAM_OAUTH2_ADMIN in the IDP Role policy. To access this endpoint, you need to log in or use an access token. If you use the access token, it should contain the following scope:

Scope: urn:netiq.com:nam:scope:oauth:registration:full

Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers/<resourceServerName>/scopes

HTTP Method: Post

Request URI Parameters:

Parameter

Required/Optional

Description

scope

Required

The name of the scope.

scope_description

Required

Description of the scope. The consent page displays this text while obtaining authorization from the user.

claims

claims or attribute_set is required

The list of claims.

attribute_set

claims or attribute_set is required

Attribute name and attribute dn.

Sample: { "name" : "jpeg_photo", "dn" : "cn=jpeg_photo,o=novell"}

userPermissionRequired

Optional

Boolean value. The default value is true.

adminApprovalRequired

Required

Boolean value. The default value is true. Set it to false always.

isGroupOfUserAttributes

Optional

Boolean value. The default value is false.

allowModifyInConsent

Optional

Boolean value. The default value is false.

includeAllClaimsInIDToken

Optional

Boolean value. The default value is false.

If the value is true, all claims or attributes in this scope are included in IDToken.

includedClaimsInIDToken

Optional

Attribute or claim name(s). You can use comma(,) as a delimiter to specify names of more than one attribute or claim.

The specified claim or attribute is included in IDToken.

For example, givenName, mail

includeAllClaimsInJWT

Optional

Boolean value. The default value is false.

If the value is true, all the claims or the attributes in this scope will be included the access token.

includedClaimsInJWT

Optional

Attribute or claims names. Use comma (,) as a delimiter to specify names of more than one attribute or claim.

The specified claims or attributes will be included in the access token.

For example, givenName, mail

Modifying a Scope

To modify a scope by using REST API, you must have your role defined as NAM_OAUTH2_ADMIN in the IDP Role policy. To access this endpoint, you need to log in or use an access token. If you use the access token, it should contain the following scope:

Scope: urn:netiq.com:nam:scope:oauth:registration:full

The request includes the following details:

Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers/<resourceServerName>/scopes/<scopename>

HTTP Method: POST

Send only those parameters that you want to modify.

Deleting a Scope

To delete a scope by using REST API, you must have your role defined as NAM_OAUTH2_ADMIN in the IDP Role policy. To access this endpoint, login or use an access token. If you use the access token, it should contain the following scope:

Scope: urn:netiq.com:nam:scope:oauth:registration:full

The request includes the following details:

Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers/<resourceServerName>/scopes/<scopename>

HTTP Method: DELETE

Viewing Configured Scopes

You can view details of all scopes together or of a specific scope. To view a scope by using REST API, you must have your role defined as NAM_OAUTH2_DEVELOPER or NAM_OAUTH2_ADMIN in the IDP Role policy. To access this endpoint, you need to log in or use an access token. If you use the access token, it should contain the following scope:

Scope: urn:netiq.com:nam:scope:oauth:registration:full

Viewing Details of a Specific Scope

The request includes the following details:

Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers/<resourceServerName>/scopes/<scopename>

HTTP Method: GET

Viewing Details of All Configured Scopes

The request includes the following details:

Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers/<resourceServerName>/scopes

HTTP Method: GET

3.2.4 OAuth 2.0 Endpoints

To get an access token and identity token, the client invokes requests to corresponding endpoints exposed by Identity Server. Identity Server exposes the following endpoints:

  • Authorization Endpoint:This is always contacted via a browser. This endpoint requires that the user has existing browser session with Identity Server. If no session exists at the time of request, the Authorization Endpoint redirects the user to login. This endpoint is used when a client uses the authorization code flow or implicit flow.

  • Token Endpoint:This is used directly by a client without involving the browser. Therefore, it is possible to get an access token offline when a user is not connected via a browser. This endpoint can issue an access token when the client provides a valid authorization code, SAML2 bearer profile for authorization grant flow, resource owner credentials, or client credentials.

  • TokenInfo Endpoint: This is used for validating a refresh token and access tokens issued in OAuth 2.0 authorization flows. Clients can send the access token via authorization header. This endpoint returns a JSON response stating whether the token is valid.

  • UserInfo Endpoint:This is used for getting resource owner's claims. A client can send a request to this endpoint with a valid access token and get the claims that are authorized by the resource owner to share. This endpoint checks whether provided access token has valid scopes to issue the claims.

  • Revocation Endpoint: This is used for revoking refresh tokens and its corresponding access token.

3.2.5 Other Endpoints

In addition to the basic endpoints mentioned in Section 3.2.4, OAuth 2.0 Endpoints, Identity Server exposes the following endpoints:

Metadata Endpoint: This exposes basic services and options available at Identity Server for OAuth 2.0 and OpenID Connect. This also contains URLs for basic endpoints. This endpoint is typically in this format: https://www.idp.com:8443/nidp/oauth/nam/.well-known/OpenID-configuration. Invoking this URL responds with a JSON document containing the following information:

  • OAuth 2.0 Endpoints

  • ID token supported algorithms

  • JWKS keys that can be used for verifying access token and ID token

Client Registration Endpoint: Developers use this to register OAuth2.0 clients through REST API. This endpoint is protected by OAuth 2.0, therefore the clients invoking this endpoint to register clients should obtain access tokens from the authorization endpoint by providing the developer's username and password. For registering new clients, a developer must have the NAM_OAUTH2_DEVELOPER role defined in Identity Server.

Scope and Resource Server registration Endpoint: This is used to register, modify, and delete a scope. Users who invoke this endpoint must have the NAM_OAUTH2_ADMIN role defined in Identity Server to be able to register and modify the scope values.

JSON Web Key Set Endpoint: Provides the information about the signing certificate that is used by Access Manager, which can be used for verifying an access token.