How-tos

Configuring and Using Dynamic Client Registration in Cloudentity

Instructions on how to configure and use Dynamic Client Registration in Cloudentity

Note

DCR allows developers to dynamically register third-party applications with authorization servers under your tenant.

Prerequisites

  • You have login credentials to Cloudentity.
  • You have a workspace in Cloudentity.

Enable DCR

  1. In the workspace, go to Auth Settings > OAuth > Client registration from the sidebar.

  2. In the DCR tab, select checkbox Enable dynamic client registration, and click Save changes to complete.

    DCR settings

    There are multiple ways to protect the registration endpoint. If you don’t setup any method, the registration endpoint is anonymously available.

    • Define Dynamic client registration policy.

    You can define a policy to be evaluated when a token registration endpoint is called.

    • Enable Protect by access token.

    With Protect by access token enabled, the registration endpoint requires an access token with the dcr_register scope granted. To issue the access token, you need a separate client with the client credentials grant type. Upon successful registration, the access token is terminated.

    • Enable Protected by software statement.

    With Protected by software statement enabled, the registration endpoint requires the software_statement attribute in the body. The software statement is a signed JWT containing an additional information on your client. You need to configure public keys (via JSON Web Key Set or URI), which are to be used for verifying a provided software statement.

    • Enable Signed request body.

    With Signed request body enabled, the registration endpoint requires a signed request body. You need to configure public keys (via JSON Web Key Set or URI), which are to be used for verifying singed registration requests.

    Result

    You’ve successfully enabled DCR in your workspace.

Register Client

To create a DCR application, you need to acquire a registration endpoint and call this endpoint to register your application.

  1. In your terminal, call .well-known, for example, by executing

    curl <https://authorization.cloudentity.com:8443/default/default/.well-known/openid-configuration>
    

    Result

    You are returned a JSON file including your registration endpoint, for example

    "registration_endpoint": "https://authorization.cloudentity.com:8443/default/default/oauth2/register"
    
  2. In the terminal, execute a curl command including the returned registration endpoint data, for example:

    curl -v -k -X POST https://authorization.cloudentity.com:8443/default/default/oauth2/register -H "content-type: application/json" -d '
    {
      "client_name": "Sample web client"
      "grant_types": [
        "authorization_code"
      ],
      "response_types": [
        "code"
      ],
      "redirect_url": [
        "https://example.com/callback"
      ]
    }'
    

    Note

    Depending on DCR settings, the software_statement body attribute or the Authorization Bearer header may be required to call the registration endpoint.

    Sample Response

    {
        "client_id": "buvn05busbftqfiocc4",
         "client_secret": "h7lhK-ALR1BKEdnbOyYT08ZUunlMmvSE2IxLrAi7AEw",
        "scopes": [
          "email",
          "openid",
          "profile"
        ],
        "registration_access_token": "q-Xl15r0bolJZ0Av30GqdgKrWI7kwZ09o5DXtphhJyU.bHzjkljpF80sxm5lAKNJZ_bGvHnsc6CSkRdtz5ECV",
        "registration_access_token_expires_in": "160898890"
    }
    

    Note

    The registration API returns registration_access_token with its expiration specified with registration_access_token_expires_in. By default, this token is valid for 30 days and can be used to manage the created client.

    Result

    Your DCR application has been created and is ready to be used. For Cloudentity administrators, the new application is visible in the Applications view of the Cloudentity portal with label DCR.

Manage Client

To get, modify, or delete a registered client, you need to

  • Call an appropriate endpoint with client_id in the path
  • Provide registration_access_token returned from the registration endpoint as the Authorization Bearer header.

Sample GET Request

curl -v -k -X GET https://authorization.cloudentity.com:8443/default/default/oauth2/register/buvn05busbftqfiocc4 -H "Authorization: Bearer q-Xl15r0bolJZ0Av30GqdgKrWI7kwZ09o5DXtphhJyU.bHzjkljpF80sxm5lAKNJZ_bGvHnsc6CSkRdtz5ECV"

Sample Response

{
    "client_id": "buvn05busbftqfiocc4",
    "client_secret": "h7lhK-ALR1BKEdnbOyYT08ZUunlMmvSE2IxLrAi7AEw",
    "scopes": [
      "email",
      "openid",
      "profile"
    ],
    "registration_access_token": "oe_YlidF0DWhQRoWQPDXRwOy_iOdI5ABls-pZKskkzU.2K5nIJ_XDSs9Ow63mGzhCpXxkQqLsrtpVhoEIQIEu4",
    "registration_access_token_expires_in": "160898890"
}

Note

When you fetch or update the client, registration_access_token is rotated. Always use the latest returned token (the previous ones are terminated).