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 authorization code grant flow and implicit grant flow. One of the registered URIs must be sent along with requests in these flows.
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.
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. 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:
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 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. |
Perform the following steps:
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.
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.
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
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 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"} |
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, 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>
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
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 |
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.
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
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
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:
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
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 must 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.
To register, modify, and delete a scope. Users must have the NAM_OAUTH2_ADMIN role defined in Identity Server to be able to register and modify the scope values using this endpoint.
Provides the information about the signing certificate that is used by Access Manager, which can be used for verifying an access token.
The scopes requested by the client application must be authorized by the user if the user is not already authorized. There is no separate endpoint available for this. The authorization endpoint is used for and requires a valid user session. Along with the authorization code/token request, the following parameters has to be added:
Grant Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/authz
HTTP Method: POST
Content-Type: application/x-www-form-urlencoded
Request URI Parameters:
|
Parameter |
Required |
Description |
|---|---|---|
|
given_scopes |
yes |
The list of scope user authorized in JSON format of URL encoded and Base64 encoded value. Sample Value: JTVCJTdCJTIyc2NvcGUlMjIlM0ElMjJlbWFpbCUyMiUyQyUyMmF0dHJpYnV0ZXMlMjIlM0ElNUIlMjJlbWFpbF92ZXJpZmllZCUyMiUyQyUyMiUyMGVtYWlsJTIyJTVEJTdEJTJDJTdCJTIyc2NvcGUlMjIlM0ElMjJwaG9uZSUyMiUyQyUyMmF0dHJpYnV0ZXMlMjIlM0ElNUIlMjJwaG9uZV9udW1iZXJfdmVyaWZpZWQlMjIlMkMlMjIlMjBwaG9uZV9udW1iZXIlMjIlNUQlN0QlNUQ%3D This sample is in the JSON format. [{"scope":"email","attributes":["email_verified"," email"]},{"scope":"phone","attributes":["phone_number_verified"," phone_number"]}] |
|
accept |
yes |
The value must be Accept. |
|
Other authorization endpoint parameters must be presented. See Authorization Endpoint for more details. |
||
Sample Request:
URL: https://<Identity Server URL: Port Number>/nidp/oauth/nam/authz
Request Parameters:
given_scopes=JTVCJTdCJTIyc2NvcGUlMjIlM0ElMjJlbWFpbCUyMiUyQyUyMmF0dHJpYnV0ZXMlMjIlM0ElNUIlMjJlbWFpbF92ZXJpZmllZCUyMiUyQyUyMiUyMGVtYWlsJTIyJTVEJTdEJTJDJTdCJTIyc2NvcGUlMjIlM0ElMjJwaG9uZSUyMiUyQyUyMmF0dHJpYnV0ZXMlMjIlM0ElNUIlMjJwaG9uZV9udW1iZXJfdmVyaWZpZWQlMjIlMkMlMjIlMjBwaG9uZV9udW1iZXIlMjIlNUQlN0QlNUQ%3D&accept=Accept&response_type=code&client_id=8f4e2d28-4fa9-47e4-a91e-eece5a2f84d6&client_secret=CEpsAebEu5dYF4oU2m73xBYd2l_MHhzhYY_JHbb5iUYRU8BEVUL5XrxACuXeTseq3Q&redirect_uri=https://client.example.org/callback&scope=email+phone
Sample Response:HTTP 302
https://client.example.org/callback?code=eyJhbGciOiJiJBMTI4R0NNIiwid5IjoiSldUIiwiemlwIjoiREVJ9.hLzNTPnB6GUO3-yNJAeZR7M1Vmy_fz0r.MANr8ak7dwjvWEbo.XG9hFDQbB8zSTdpyu_2J18V.......
This endpoint returns all client applications and scopes that user had approved so far. To access this endpoint requires either user login or access token. The endpoint details are as follows:
Grant Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/account/authzClients/
HTTP Method:GET
Sample Request using Access Token
URL:https://<Identity Server URL: Port Number>/nidp/oauth/nam/account/authzClients
Authorization Header: Bearer
eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiwidHlwIjoiSldUIiwiY3R5IjoiSldUIiwiemlwIjoiREVGIiwia2lkIjoiMiJ9.hLzNTPnB6GUO3-yNJAeZR7M1Vmy_fz0r.MANr8ak7dwjvWEbo.XG9hFDQbB8zSTdpyu_2J18V.......
Sample Response: HTTP Status 200
{"grants": [{"clientId": "8f4e2d28-4fa9-47e4-a91e-eece5a2f84d6","clientName": "nam-oauth-play ground","scopes": [Unknown macro: { "name"},Unknown macro: { "name"}]},{"clientId": "a8df6bf4-f91f-4369-b15e-95bc2be6bb9a","clientName": "OAuthclientApp","scopes": [Unknown macro: { "name"},Unknown macro: { "name"}]}]}
Sample Error Response: HTTP Status 401
Unknown macro: {"error"}
The scopes approved for a client by the user can be revoked using this endpoint. To access this endpoint requires either user login or access token. The endpoint details are as follows:
Grant Endpoint: https://<Identity Server URL: Port Number>/nidp/oauth/nam/account/authzClients/{clientId} - where {clientId} is the OAuth client application ID.
HTTP Method: DELETE
Sample Request using Access Token:
URL: https://<Identity Server URL: Port Number>/nidp/oauth/nam/account/authzClients/8f4e2d28-4fa9-47e4-a91e-eece5a2f84d6
Authorization Header: Bearer
eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4R0NNIiwidHlwIjoiSldUIiwiY3R5IjoiSldUIiwiemlwIjoiREVGIiwia2lkIjoiMiJ9.hLzNTPnB6GUO3-yNJAeZR7M1Vmy_fz0r.MANr8ak7dwjvWEbo.XG9hFDQbB8zSTdpyu_2J18V.......
Sample Response: HTTP 200
{"status": "success","msg": "successfully revoked grants to clients"}