How to use the OAuth Dynamic Client Registration

Using Dynamic Client Registration

On this page

Dynamic Client Registration allows new clients to be registered using a standard API. For more details about the architectural structure of DCR see DCR Explained

The Curity Solution

Curity provides the full benefits of OAuth and OpenID Connect standards, but also offers additional functionality to combat the risk for scope explosion.

There is also special handling of claims and scopes, such as mapping claims to specific clients and custom groupings that allow for greater flexibility and a more manageable architecture.

More information

For more information, see the mentioned articles above, or the Curity Developer Portal

Initial Access Token

In order to be able to register a new client in the Curity Identity Server, an Initial Access Token is needed. This is a token with the dcr scope. This token can only be used once. There are multiple ways to obtain an initial access token. Either using the client credentials flow or a user interactive flow such as the code flow, implicit flow or the assisted token flow. It can also be provided to the application out of band using any appropriate mechanism.

This overview will not explain in detail how to obtain the token, but will focus on how to register the client once the token is obtained.

Warning 'DCR Scope'

If the application does not ask for the dcr scope, the resulting token will not include it and the app will not be able to register itself.

Client Registration

With an initial access token in hand, the client can register itself. To do so, it will make an API call to Curity's Dynamic Client Registration endpoint. This endpoint is protected and requires an OAuth access token to be presented in the Authorization request header using the bearer authentication scheme (per RFC 6750). What is included in the request body depends on how dynamic clients are registered:

  1. As instances of existing clients where the existing one functions as a sort of template for the dynamically registered one
  2. As entirely new clients

These often correspond to the first two primary use cases described above but they need not.

Registration using Template Client

Dynamic clients can be based on an existing client that is configured to be a template. Registration of a new client that is to be based on another is also very easy; there is only one request parameter: software_id. This ID (as defined in RFC 7591) is the client ID of the template client. No other settings need to be included in the request, and, if there are any, Curity will ignore them. The settings are always taken from the template.

The values in the response are taken from template identified by the software_id input parameter. The client ID used for the software_id is only acceptable if that client is a template.

DCR Endpoint - Templatized Request

  • Method: POST
  • Agent: Backend
  • Content Type: application/json
  • Response Type: application/json

Request Parameters

software_idA Client IDyesThe Client ID of the template client to instantiate a new client from

A sample request is shown in the following listing:

POST /dcr HTTP/1.1
Host: localhost:8443
Authorization: Bearer 9e565e0b-a487-4092-a4af-461add3155f2
Content-Type: application/javascript
{ "software_id": "client-one" }

Registration using Non-templatized Client

Clients can also be registered without having to be based on an existing one. To register a client in this way, all metadata for that client must be included in the request.

DCR Endpoint - Non-Templatized Request

  • Method: POST
  • Agent: Backend
  • Content Type: application/json
  • Response Type: application/json

Request Parameters

Primary parameters

scopeSpace separated listnoThe list of scopes the client is requesting
grant_typesArraynoA list of grant types to be used against the token endpoint. If not provided the authorization_code grant type is assumed.
redirect_urisArrayyes*The callback urls. *Required if the client registers for a flow that uses redirects, such as the code flow.
response_typesSpace separated listnoA list of response types. Only used for browser based flows against the authorize endpoint. If empty the code response type is used.

Additional parameters

access_token_ttlintegernoThe TTL in seconds for the access token. Defaults to the configured default in Curity.
allowed_originsArray of URIsnoList of origins that should be allowed to frame the application
application_urlurlnoA link to redirect the user to if session times out.
authenticator_filtersArray of stringsnoA list of id's for the authenticator filters to apply to the authenticator selection
client_nameStringnoA human readable name of the client
client_uriurlnoURL of the home page of the Client
default_acr_valuesArray of acrsnoA list of ACRs to use when authenticating the user.
disallowed_proof_keyArray of StringsnoList of proof key algorithms to disallow.
id_token_ttlintegernoThe TTL in seconds for the ID token. Default to the configured default in Curity.
logo_uriurlnoA link to the logo representing the client
requires_consentbooleannoIf the user should be prompted with consent screens. Default false
require_proof_keybooleannoIf PKCE should be required. Defaults to false.
refresh_token_ttlintegernoThe TTL in seconds for the Refresh token. Defaults to the configured default in Curity.
sector_identifier_uriurinoThe PPID sector to use when creating pairwise pseudonyms
subject_typeparwise or publicnoIf the subject should be hidden or public.
tos_uriurlnoA link to the terms of service for the client
policy_uriurlnoA link to the policy for profile data for the client

Supported grant_types

The grant types supported depends on the configuration in the Curity Identity Server, but the possible values are:

Grant TypeDescription
authorization_codeThe authorization code flow
passwordThe resource owner password flow
client_credentialsThe client credentials flow
urn:ietf:params:oauth:grant-type:device_codeThe device authorization flow

Supported response_types

Response TypeDescription
codeThe authorization code flow
tokenThe implicit flow
id_tokenThe implicit openid flow or the hybrid flow (together with code and token)

A sample request is shown in the following listing:

POST /dcr HTTP/1.1
Host: localhost:8443
Authorization: Bearer 9e565e0b-a487-4092-a4af-461add3155f2
Content-Type: application/javascript
"scope": "openid read foo test_scope_1",
"redirect_uris": [ "https://localhost:9000/cb" ],
"grant_types": [ "authorization_code" ],
"response_types": "code",
"client_name": "monkey",
"client_uri": "https://localhost:9000/",
"tos_uri": "https://localhost:9000/tos",
"default_max_age": 44

Response from the DCR Endpoint


The response is a json document with the accepted values reflected back. If using templatized clients the response will contain the template's values.


"grant_types": [
"subject_type": "public",
"redirect_uris": [
"client_id": "5bc6f48b-b3c4-413d-a374-20a77ffd1d59",
"token_endpoint_auth_method": "client_secret_basic",
"software_id": "client-one",
"client_secret_expires_at": 0,
"scope": "openid",
"client_secret": "E4wYA0LOU7hQd-DDh6W2rrqP-OnSsj3pAk243a-j-oE",
"client_id_issued_at": 1503067741,
"client_name": "client-one",
"response_types": [
"refresh_token_ttl": 3600,
"id_token_signed_response_alg": "RS256"

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial