4.1 Registration Endpoint

4.1.1 Registering a Client Application

To register a client application, the HTTP method value must be POST.

The client registration endpoint is protected by OAuth 2.0. Therefore, invoking this endpoint must include an access token as a bearer token or if you are using curl, log in using the username and password. Also, the user account must have the NAM_OAUTH2_DEVELOPER role. Contact the Access Manager administrator to get an OAuth 2 developer account. If you are registering a client using an access token, get client application details from the Access Manager administrator.

To obtain an access token for registering a client, you can use any one of the OAuth flows (resource owner, authorization code, or implicit flow). 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 for registering a client application:

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

Identity Server uses the following endpoint for registering a client application:

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

Headers:

Authorization bearer eyJhbGciOiJBMTI4S1ciL... (Login or access token in the authorization header is required.)
Content-Type application/json

This endpoint requires the followings OAuth parameters for registering or modifying a client application:

Parameter	Required	Description
client_name	Required	The name of the client application.
redirect_uris	Required	The redirection URI values used by the client application
enabled	Optional	The boolean value true or false. The default value of this parameter is true. This parameter is optional, when the value is not specified, the default value would be considered.
application_type	Optional	Web or native
response_types	Optional	JSON string array of any of the following values are the supported response types: code code token id_token Sample supported values: ["code","id_token","token"] or ["code","id_token"] or ["code"]
tokenFormat	Optional	By default, the token format is set to default. NOTE:When an administrator changes the format, the changed format will be seen only for the newly issued tokens. The following are the supported token formats: default: The default format is controlled by an administrator. The administrator can set the default format globally for a specific Identity Server (Authorization server). If the administrator has not set the format, then JWT is the default format. Whenever the Access Manager administrator changes the token format globally for a specific Identity Server, the default format also changes to the same for the registered client applications. binary: The Binary option is recommended only if you have an existing client application that cannot use the jwt format because of the browser restrictions for the length of the parameter values. This value will not change when the Access Manager administrator changes the token format globally for a specific Identity Server. jwt: This is the recommended option. The token format will always be jwt even when the administrator changes the format in the global settings of Identity Server (authorization server).
grant_types If you do not specify a grant type, the default grant type is used. The default value is authorization_code.	Optional	The following are the supported values for grant_types: authorization_code implicit refresh_token password (resource owner credentials) client_credentials saml2-bearer
alwaysIssueNewRefreshToken	Optional	Specify true as a value to issue a new refresh token on every refresh token request.
authzCodeTTL	Optional	Specify the duration in minutes after how long the authorization code becomes invalid.
accessTokenTTL	Optional	Specify the duration in minutes after how long the Access token and ID token become invalid.
refreshTokenTTL	Optional	Specify the duration in minutes after how long the Refresh token becomes invalid.
corsdomains	Optional	If you want to allow access for requests from only selected domains. Specify the domain(s) as JSON array. For example, [“beem://www.test.com”, “fb://app.local.url”, “https://namapp.com”]
logo_uri	Optional	Specify the URL of the logo to include in the consent page. For example, https://client.example.org/logo.png
policy_uri	Optional	URL of the Relying Party Client’s privacy policy. For example, https://client.example.org/privacypolicy
tos_uri	Optional	URL of the Relying Party's terms of service. For example, https://client.example.org/terms
contacts	Optional	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 as a string. This algorithm is required for signing the ID token issued to the client. The following are supported values: none RS256 RS384 RS512
id_token_encrypted_response_alg	Optional	Specify the algorithm used to encrypt the key as a string. The following are supported values: RSA1_5 A128KW
id_token_encrypted_response_enc	Optional	Specify the algorithm used to encrypt the content as a string. The supported value is A128CBC-HS256.
frontchannel_logout_uri	Optional	Specify the client application's logout URL that will cause the client application to log itself out when rendered in an iframe by Identity Server (Authorization server).
frontchannel_logout_session_required	Optional	The boolean value. Specify true if the client application requires that a sid (Session ID) query parameter be included to identify the session with Identity Server (Authorization Server) when the frontchannel_logout_uri is used. If omitted, the default value is false. For example, register the frontchannel_logout_uri value as https://client.example.org/fc_logout and frontchannel_logout_session_required are false, then Identity Server causes the front-channel logout to occur by rendering the https://client.example.org/fc_logout URL in an iframe. Similarly, when frontchannel_logout_session_required is true, Issuer and Session ID values are included as query parameters: https://client.example.org/fc_logout?iss=https://idp.server.com&sid=LDtAIRsTGdW6Fyhdi
post_logout_redirect_uris	Optional	Specify an array of URLs supported by the client application to which the end user's browser will be redirected after a successful logout at Identity Server (Authorization Server). For example, ["https://client.example.org/callback","https://client.example.org/callback2"] NOTE:Identity Server redirects the end-user to the registered logout redirect URI only when the client application sends the front-channel logout request with an id_token_hint parameter. If id_token_hint is omitted in the logout request, an error response is returned.
contracts	Optional	Specify an array of contract URIs assigned to a client application. For example, ["name/password/uri","basic/name/password/uri"] NOTE:When you configure authentication contracts for a client application, the ACR value in the request is ignored and the first contract in the list will be used for authentication with the Authorization endpoint. In the case of Resource Owner Credentials flow, it will consider the first Resource Owner flow supported contract to authenticate by traversing the list of contracts.
scope	Optional	Specify an array of scope assigned to a client application. For example, ["profile","email"] NOTE:When you configure scopes for a client application, only those scope value in the authorization/token endpoint request would be accepted if they are configured for requested client application. To know the list of scopes supported by the NAM, the openid connect metadata endpoint (https://<IDPhost:port>/nidp/oauth/nam/.well-known/OpenID-configuration) can be used.

Sample Request and Response

Sample Request

POST /nidp/oauth/nam/clients HTTP/1.1
Host: www.idp.com:8443
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJBMTI4S1ciL.....ihoypluZPQwvE0VcehrubnTh_NjCCcJuqNh2OQ.n1FHCm7WFkTrOI6oMsLqnQ
Cookie: JSESSIONID=AA47446E669A51A686F01A5D44F662A9
Content-Length: 1804

{
  "application_type": "web",
  "logo_uri": "https://client.example.org/logo.png",
  "registration_client_uri": "https://www.idp.com:8443/nidp/oauth/nam/clients/abc7893f-2d6d-4db7-ad4a-4612c033f8aa",
  "enabled": true,
  "token_endpoint_auth_method": "client_secret_basic",
  "client_id": "abc7893f-2d6d-4db7-ad4a-4612c033f8aa",
  "corsdomains": [
    "insurance.novell.com",
    "client.example.org"
  ],
  "Version": "5.0",
  "token_format": "jwt",
  "authzCodeTTL": 3,
  "accessTokenTTL": 10,
  "client_secret": "6VzPz9beQiswUHTs22TgRbEhSg89Pjgk2p6LJEKYvyTFT4LuuchbkkaKbnNInFrSRGXbivorXqvcQzZkqZIjtw",
  "client_id_issued_at": 1625571581465,
  "client_name": "InsuranceMobileApp",
  "policy_uri": "https://client.example.org/privacypolicy",
  "id_token_signed_response_alg": "RS256",
  "post_logout_redirect_uris": [
    "https://insuranceapp.novell.com/"
  ],
  "subject_type": "pairwise",
  "grant_types": [
    "authorization_code"
  ],
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "frontchannel_logout_session_required": true,
  "frontchannel_logout_uri": "https://insuranceapp.novell.com/logout",
  "id_token_encrypted_response_alg": "RSA1_5",
  "refreshTokenTTL": 1440,
  "id_token_encrypted_response_enc": "A128CBC-HS256",
  "client_secret_expires_at": 1625657981465,
  "jwks_uri": "https://client.example.org/my_public_keys.jwks",
  "tos_uri": "https://client.example.org/terms",
  "contacts": [
    "ve7jtb@example.org",
    "mary@example.org"
  ],
  "response_types": [
    "code",
    "id_token",
    "token"
  ]
}

Sample Response

HTTP/1.1 201
Content-Type: application/json
Status Code: 201 201

{
  "application_type": "web",
  "logo_uri": "https://client.example.org/logo.png",
  "registration_client_uri": "https://sangeetha1.blr.novell.com/nidp/oauth/nam/clients/3c0beb03-f370-4b07-9ae2-31282b75948e",
  "enabled": true,
  "token_endpoint_auth_method": "client_secret_basic",
  "client_id": "3c0beb03-f370-4b07-9ae2-31282b75948e",
  "corsdomains": [
    "insurance.novell.com",
    "client.example.org"
  ],
  "Version": "5.0",
  "token_format": "jwt",
  "authzCodeTTL": 3,
  "accessTokenTTL": 10,
  "client_secret": "I5GZ5n9rRxMDHJ3VKHFEFl8uBC0Q8RXvHZqhjvRP287t5PY1KovC0e2Si2KrNmCY1uZ2mIM3o4kTz3TIEaT6fQ",
  "client_id_issued_at": 1625572906389,
  "client_name": "InsuranceMobileApp",
  "policy_uri": "https://client.example.org/privacypolicy",
  "id_token_signed_response_alg": "RS256",
  "developerDn": "admin",
  "post_logout_redirect_uris": [
    "https://insuranceapp.novell.com/"
  ],
  "subject_type": "pairwise",
  "grant_types": [
    "authorization_code"
  ],
  "redirect_uris": [
    "https://client.example.org/callback",
    "https://client.example.org/callback2"
  ],
  "frontchannel_logout_session_required": true,
  "frontchannel_logout_uri": "https://insuranceapp.novell.com/logout",
  "id_token_encrypted_response_alg": "RSA1_5",
  "refreshTokenTTL": 1440,
  "id_token_encrypted_response_enc": "A128CBC-HS256",
  "client_secret_expires_at": 1625659306389,
  "jwks_uri": "https://client.example.org/my_public_keys.jwks",
  "tos_uri": "https://client.example.org/terms",
  "contacts": [
    "ve7jtb@example.org",
    "mary@example.org"
  ],
  "response_types": [
    "code",
    "id_token",
    "token"
  ]
}

NOTE:The response will contain client_id and client_secret. Make a note of these values to use in the token request.

Error Response

When a client name is already registered with Identity Server, trying to register it again throws the HTTP 400 error with the following response:

{"error_description":"The client already exists. Please contact administrator","error":"invalid_client"}
When the request does not to include a mandatory parameter, redirect_uri throws the HTTP 400 error with the following response:

{"error_description":"Could not find client metadata field redirect_uris","error":"invalid_client_metadata"}
When an unsupported ID token signing algorithm is sent in the request, it throws the HTTP 400 error with the following response:

{"error_description":"Unsupported ID token signing algorithm. Supported algorithms are {none / RS256 / RS384 / RS512}","error":"unsupported_idtoken_signing_algo"}

4.1.2 Modifying a Client Application

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

Headers:

Authorization bearer eyJhbGciOiJBMTI4S1ciL... (A login or access token in authorization header is required.)
Content-Type application/json

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/<client ID>

For the list of parameters that this endpoint requires for a client application modification, see the table in 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.

4.1.3 Viewing a Client Application

To view a client application, use GET as the HTTP method value. A login or access token in the authorization header is required to view a client application.

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.

4.1.4 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:

Endpoint URL: https://<Identity Server URL: Port Number>/nidp/oauth/nam/clients/<client ID>Headers:Authorization bearer eyJhbGciOiJBMTI4S1ciL... (A login or access token in the authorization header is required.)