Skip to main content

Configure and use dynamic client registration

SecureAuth Connect supports Dynamic Client Registration (DCR), the OAuth 2.0 standard (RFC 7591) that lets a client application register itself with an authorization server through an API call. Instead of an administrator creating every client by hand in the admin portal, a developer sends a registration request to an endpoint and receives back a client_id, credentials for confidential clients, and a token to manage the client afterward.

This topic is for two audiences: administrators who enable and protect DCR on a workspace, and developers who register and manage client applications against it.

What DCR solves​

Without DCR, every OAuth client has to be provisioned manually before it can authenticate. That works when you control a handful of applications, but it does not scale when many external or partner applications need to onboard themselves, often without any direct contact with your administrators.

DCR moves client provisioning from a manual, admin-driven task to a self-service API. Because it follows the OAuth standard, any client that speaks DCR can register without custom integration work on either side.

When to use DCR​

Use DCR when applications need to register on their own, at scale, rather than being set up individually. Common cases include:

  • Open ecosystems. Open banking, FDX, Open Finance, and Consumer Data Right (CDR) require third parties to register through DCR as part of the standard.
  • Partner and third-party onboarding. Partners register their own applications without waiting on your team to create each client.
  • Automated provisioning. Deployment pipelines or multi-tenant platforms create clients programmatically as new environments or customers come online.

For interactive applications that you build and control yourself, creating the client in the admin portal is usually simpler than DCR.

Before you begin​

  • You need administrator access to the workspace to enable DCR and configure how the registration endpoint is protected.
  • Decide how you will protect the endpoint before you enable it. If you enable DCR without a protection method, the registration endpoint is available anonymously to anyone who can reach it. See Enable and configure DCR.

Enable and configure DCR​

Enabling DCR is an administrator task. Turn it on for the workspace whose authorization server will accept registration requests, then configure how the endpoint is protected and how registered clients behave.

  1. In the workspace, go to OAuth > Authorization Server in the sidebar, then select the Client Registration tab.

  2. Select the Enable Dynamic client registration checkbox. The remaining settings appear.

    Client Registration tab with Dynamic client registration enabled, showing the DCR settings

  3. Configure the settings for your use case. Every setting other than the checkbox is optional.

    Registration rules

    • Dynamic client registration policy – Select a policy to evaluate on each registration request, so you can allow or reject requests based on your own rules. The default, Unrestricted (No Policy), applies no policy.
    • Default scopes – Scopes that are always included in every registration, merged with the scopes each client requests. Leave this empty to apply the workspace default scopes.

    Registration access token

    Registering a client returns a registration access token that manages the client afterward. These settings control how that token behaves.

    • Disable registration token management – Prevent clients from being managed with the registration access token. Clients instead manage themselves using an access token from the client credentials flow.
    • Disable registration token rotation – Keep the registration access token stable instead of rotating it on each fetch or update.
    • Disable registration token expiration – Issue registration access tokens that never expire.
    • Registration token TTL – Set how long the registration access token can be used to manage the client. The default is 720 hours (30 days) and the minimum is 24 hours.
    • Certificate bound registration tokens – Bind the registration access token to the client certificate used to register the client, so only that certificate can use it.

    Endpoint protection

    Protecting the registration endpoint prevents unauthorized parties from registering clients. You can combine methods.

    • Protect by access token – Require an access token with the dcr_register scope on the registration request. Issue the token from a separate client that uses the client credentials grant. The token is terminated after a successful registration.
    • Protected by software statement – Require a software_statement in the request body. The software statement is a signed JWT that carries additional information about the client. Configure public keys (through a JSON Web Key Set or a URI) so the authorization server can verify it.
    • Signed request body – Require the registration request body to be signed. Configure public keys (through a JSON Web Key Set or a URI) so the authorization server can verify the signed request.

  4. Save your changes.

    Result: DCR is enabled on the workspace, and clients can register through the registration endpoint.

Register a client​

Registering a client is a developer task. First find the registration endpoint, then post the client's details to it.

The examples use my-tenant.us.connect.secureauth.com with the tenant my-tenant and workspace my-workspace. Replace these with your own tenant domain, region, and workspace.

  1. Request the workspace's OpenID Connect metadata to find the registration endpoint.

    curl https://my-tenant.us.connect.secureauth.com/my-tenant/my-workspace/.well-known/openid-configuration

    The response includes the registration_endpoint.

    {
      "registration_endpoint": "https://my-tenant.us.connect.secureauth.com/my-tenant/my-workspace/oauth2/register"
    }

  2. Send a registration request to the endpoint with the client's metadata.

    curl -X POST https://my-tenant.us.connect.secureauth.com/my-tenant/my-workspace/oauth2/register \
      -H "Content-Type: application/json" \
      -d '{
        "client_name": "Sample server-side web app",
        "grant_types": ["authorization_code"],
        "response_types": ["code"],
        "redirect_uris": ["https://example.com/callback"]
      }'
    note

    Depending on your DCR settings, the request may also need a software_statement in the body or an Authorization: Bearer header.

    The response returns the registered client. Confidential clients, such as this server-side web app, receive a client_secret. Public clients, such as single-page or native apps that use PKCE, do not.

    {
      "client_id": "buvn05busbftqfiocc4",
      "client_secret": "h7lhK-ALR1BKEdnbOyYT08ZUunlMmvSE2IxLrAi7AEw",
      "scopes": ["openid", "profile", "email"],
      "registration_access_token": "q-Xl15r0bolJZ0Av30GqdgKrWI7kwZ09o5DXtphhJyU.bHzjkljpF80sxm5lAKNJZ_bGvHnsc6CSkRdtz5ECV",
      "registration_access_token_expires_in": "2592000"
    }
    • The scopes array reflects the scopes granted to the client. It includes any default scopes configured for the workspace, merged with the scopes the client requests.
    • The registration_access_token manages the client after registration. Its lifetime is set by registration_access_token_expires_in, in seconds, and defaults to 30 days.

    Result: The client is registered and ready to use. In the admin portal, it appears in the Applications view with a DCR label.

    Applications view in SecureAuth Connect showing a registered client with the DCR label

Manage a client​

Use the registration_access_token from the registration response to get, update, or delete the client. Each request goes to the registration endpoint with the client_id in the path and the token in the Authorization: Bearer header.

The following request retrieves the current client configuration.

curl -X GET https://my-tenant.us.connect.secureauth.com/my-tenant/my-workspace/oauth2/register/buvn05busbftqfiocc4 \
  -H "Authorization: Bearer q-Xl15r0bolJZ0Av30GqdgKrWI7kwZ09o5DXtphhJyU.bHzjkljpF80sxm5lAKNJZ_bGvHnsc6CSkRdtz5ECV"
{
  "client_id": "buvn05busbftqfiocc4",
  "client_secret": "h7lhK-ALR1BKEdnbOyYT08ZUunlMmvSE2IxLrAi7AEw",
  "scopes": ["openid", "profile", "email"],
  "registration_access_token": "oe_YlidF0DWhQRoWQPDXRwOy_iOdI5ABls-pZKskkzU.2K5nIJ_XDSs9Ow63mGzhCpXxkQqLsrtpVhoEIQIEu4",
  "registration_access_token_expires_in": "2592000"
}

To update the client, send a PUT request with the changed metadata to the same URL. To remove it, send a DELETE request.

note

The registration_access_token rotates every time you fetch or update the client. Always use the token from the most recent response, because earlier tokens are terminated.

See also​