Registering a client application includes the following activities:
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.
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 the authorization code grant flow and implicit grant flow. One of the registered URIs should be passed along with requests in these flows.
The client application has to specify which OAuth2.0 authorization grant flows the application will use. Access Manager issues tokens only in the specified flows. Any requests with flows those are not registered during client registration are not supported. You can also modify this information after a client is registered.
An administrator of your organization can disable some of the 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.
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.
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 |
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. Now, the user accesses client B immediately or after few days. If this option is enabled for client B, then the client uses the persistent cookie to retrieve the token and authenticate the user. Hence, client B will be authenticated automatically. If this option is not enabled for client B configuration, then to retrieve refresh token and access token user has 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:
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:
|
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 duration in minute after that an access token and an ID token become invalid. |
refreshTokenTTL |
Optional |
Specify the duration in minute after that a refresh token becomes invalid. |
corsdomains |
Optional |
If you want 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 you want to include 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. |
Perform the following steps:
Retrieve the 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.
Send the update request. In the update 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 complete xml with all parameters during the update request. If you do not include a parameter in the update xml, the server does not initialize this parameter. For example, if you want to update the response_types parameter, send the updated value for this parameter and existing values for other parameters in the request.
To view a client application, use GET as the HTTP method value.
You can view a registered client application by using the following two endpoints:
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
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>
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, option to encrypt the access token by using either the resource server encrypted keys or the Identity Server encrypted keys.
It also provides an option to not encrypt an access token. This is not recommended because it may 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 programmatically 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"} |
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
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, you need to 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
HTTP Method: DELETE
Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers/<resourceServerName>
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, you need to 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
HTTP method: Get
Resource Server Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/resourceservers
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 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
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 description 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. |
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 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: POST
Send only those parameters that you want to modify.
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, you need to 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
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 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
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
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.
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.