OpenID Connect Dynamic Client Registration

Dynamic Client Registration allows the OpenID Connect (OIDC) Relying Party (RP) to register itself with the OpenID Connect Provider (OP).

Before you begin

New OIDC applications are created by a tenant administrator or a user with administrative access to the tenant. Now, an API client with the right entitlement can also create an OIDC application through a dynamic client registration endpoint.

Dynamic client registration endpoint is located here: https://{{tenant}}/v1.0/endpoint/default/client_registration.

About this task

To dynamically register a client, acquire an initial access token and then register the new OIDC application by using the registration API.

Acquire Initial Access Token

To access a dynamic client registration endpoint, use an access token with the Manage OIDC client registration dynamically entitlement.

Create an API Client with the Manage OIDC client registration dynamically entitlement. To create the API Client, see Managing API clients.

After the API Client is created, use the client_credentials flow to get the access token. Here is the example:

curl -ki -v https://{{tenant}}/v1.0/endpoint/default/token -d "grant_type=client_credentials&client_id=<clientId>&client_secret=<clientSecret>"

Register New Application using Registration API

Using the access token produced above, you can create a new OIDC Application.

The following table shows the list of client metadata that are currently supported.

Metadata Name Metadata Description Optional Valid Values
client_name Application Name true string
redirect_uris List of redirect URIs. false list of string URI
grant_types Array of grant types that the application can use. true ‘authorization_code’, ‘implicit’, ‘password’, ‘refresh_token’ and ‘urn:ietf:params:oauth:grant-type:device_code’
id_token_signed_response_alg Token signing algorithm. true ‘RS256’, ‘RS384’, ‘RS512’, ‘HS256’, ‘HS384’, ‘HS512’
all_users_entitled Set to true if all users are entitled to use this application. true true or false
jwks_uri URL of the Client's JSON Web Key Set document. true URL
consent_action Request for user consent. true ‘never_prompt’ or ‘always_prompt’
enforce_pkce Enforce the usage of PKCE. true true or false
id_token_claims List of claims for id_token and user information. true list of string
token_claims List of claims for introspect and jwt access token. true list of string

For optional metadata, if not specified, the system assigns the appropriate value for it. The following table shows the defaults that are assigned.

Metadata Name Metadata Description Default Value Valid Values
grant_types Array of grant types that the application can use. authorization_code all grant types supported by OIDC application
id_token_signed_response_alg Token signing algorithm. RS256 ‘RS256’, ‘RS384’, ‘RS512’, ‘HS256’, ‘HS384’, ‘HS512’
all_users_entitled Whether all users are entitled to use this application. false true or false
access_token_type Access token type. default ‘default’ (opaque) or ‘jwt’
consent_action Request for user consent. always_prompt ‘never_prompt’ or ‘always_prompt’
access_token_lifetime Lifetime of access token generated. 7200 positive integer value
refresh_token_lifetime Lifetime of refresh token generated. 68400 positive integer value
enforce_pkce Enforce the usage of PKCE. true true or false
allow_custom_client_creds Whether specifying custom client_id and client_secret during creation is allowed. false true or false
id_token_claims List of claims for id_token and user information. empty list list of string
token_claims List of claims for introspect and JWT access token. empty list list of string
Note:

Tenant administrators can modify these defaults through the API endpoint `/v1.0/dynamic-client-profile`, with `manageFederations` API entitlements.

Example to register a new application:

curl -ki -H "Authorization: bearer <access-token>" -H "Content-Type:application/json" -X POST https://{{tenant}}/v1.0/endpoint/default/client_registration --data-binary '{"redirect_uris":["https://www.redirect.com"],"client_name":"MyApplication"}'

The response:

{"grant_types":["authorization_code"],"client_secret_expires_at":"0","registration_client_uri":"https://{{tenant}}/v1.0/endpoint/default/client_registration/<clientId>","client_secret":"<client_secret>","redirect_uris":["https://www.redirect.com"],"client_id_issued_at":"1586933118","client_name":"MyApplication","registration_access_token":"<access_token>","client_id":"<clientId>","id_token_signed_response_alg":"RS256"}

Further Configuration of Application

After the application is created, there are more options that you can configure for the application, for example, attribute mapping, access policy, identity sources, entitled users, etc. To configure these options, see Configuring single sign-on in the OpenID Connect provider.

The option to update by using the registration API is not supported.

Read OIDC Application by using Registration API

The registration API also provides a way to read the OIDC application again.

curl -ki -H "Authorization: bearer <registration-access-token>" https://{{tenant}}/v1.0/endpoint/default/client_registration/<clientId>

Delete OIDC Application using Registration API

The registration API also provides a way to delete the OIDC application.

curl -ki -H "Authorization: bearer <registration-access-token>" -X DELETE https://{{tenant}}/v1.0/endpoint/default/client_registration/<clientId>

Registration access token expired

If the registration access token expires, acquire a new access token. See Acquire Initial Access Token.