Guides

Dynamic Client Registration (DCR)

Suggest Edits

Learn more about Dynamic Client Registration.

Prerequisites

  • Set up ISVAOP
  • Set up an application or relying party that supports dynamic client registration.

Configuring ISVAOP

By default, ISVAOP is configured to support dynamic client registration. The requests can be configured to be authorized by software statement assertions or bearer tokens or can be public.

Default Dynamic Client Registration configuration

Dynamic Client Registration configuration resides in the provider.yml under dynamic_registration stanza.

By default, it is processed as below, when missing:

dynamic_registration:
  mappingrule_id: ""
  registration_endpoint_authentication:
    require_mtls: false
    require_bearer_token: false
    require_software_statement: false
    allow_custom_client_creds: false
  management_endpoint_authentication:
    require_mtls: false
    require_bearer_token: false
    require_software_statement: false
  registration_access_token:
    generate: false
    lifetime: 0

This can be copied to provider.yml and achieve the same behavior. With these settings, the /oauth2/register endpoint is publicly accessible and requires no additional authorization.

Using Dynamic Client Registration with Software Statement

Software statement assertions may be used to authorize dynamic client creation and update operations.

dynamic_registration:
  software_statement_validation:
    jwks_uri: https://openbanking.com/jwks # Modify this accordingly
    signing_algs:
      - ES256                              # Optional to restrict the signing algorithm
  registration_endpoint_authentication:
    require_software_statement: true
  management_endpoint_authentication:
    require_software_statement: true

The public key to validate software statement must be published in the jwks_uri.

Using Bearer Token to protect Dynamic Client Registration endpoint

To protect Dynamic Client Registration using bearer token, here is an example:

dynamic_registration:
  registration_endpoint_authentication:
    require_bearer_token: true
  management_endpoint_authentication:
    require_bearer_token: true
  registration_access_token:
    generate: true
    lifetime: 86400 # 24 hours
    scopes:
      - cdr:registration

For the configuration above, the create (POST) operation also requires a bearer token. Typically, this bearer token is acquired using
a different client using client_credentials grant flow. Notice that dynamic_registration/registration_access_token/scopes is set to cdr:registration. This scope must be granted to the bearer token used.

The client used to generate the access token becomes the owner of the newly created dynamic client. Only bearer tokens belonging to the owner (if any) or the dynamic client itself are allowed to perform management operations.

Dynamic clients are also issued the registration_access_token, which may be used for subsequent management operations. This token's lifetime is determined based on the dynamic_registration/registration_access_token/lifetime setting.

Adding customization to Dynamic Client Registration flow

There may be a need to set defaults or override specific client metadata values and this can be achieved using a mapping rule.

  • Create a mapping rule named dcr.js and copy it into the {config}/javascript/mappingrule directory.

  • Modify the provider.yml with the snippet as below.

dynamic_registration:
  mappingrule_id: dcr

Security Profiles

IBM Security Verify Access OIDC Provider allows the users to specify a security profile in the Dynamic Client Profile. This security profile is used to perform certain validations when DCR flows are initiated.

The security profile allowed to be configured are:

  1. Default - This is equivalent to no security profile specified.
  2. FAPI_DEFAULT - The default Open Banking security profile.
  3. FAPI_UK-OB - The security profile to enforce UK Open Banking standard.
  4. FAPI_AU-CDR - The security profile to enforce Australia's Consumer Data Rights specification.

FAPI_DEFAULT

This follows the default Dynamic Client Registration specification (https://www.rfc-editor.org/rfc/rfc7591). Presently, the validations enforced by this security profile is the same as Default or when no security profile is specified.

The following are validated for this security profile for DCR flows:

  • The aud value, if present in the DCR JWT, is equal to the register endpoint (https://<hostname>/oauth2/register)
  • If software statement is specified, validate that iss is present.

Additional validation can be added by configuring and modifying the dcr mapping rule. In the following mapping rule sample, the iss of the software statement is being validated to match http://openbankingdirectory.com.

    /**
     * Example of validating metadata claim
     */
    var ss = stsuu.getContextAttributes().getAttributeValueByName("software_statement");
    if (ss != null) { // Software statement exists
        /**
         * Software statement claim having attribute type 'urn:ibm:names:ITFIM:oauth:ss:param'
         */
        var iss = stsuu.getContextAttributes().getAttributeValueByNameAndType("iss", "urn:ibm:names:ITFIM:oauth:ss:param");
        if (iss != "http://openbankingdirectory.com") {
            OAuthMappingExtUtils.throwSTSCustomUserMessageException("Unexpected software statement issuer.", 400, "invalid_client_metadata");
        }
    }

FAPI_UK-OB

This follows the UK Open Banking specification (https://openbankinguk.github.io/dcr-docs-pub/v3.3/dynamic-client-registration.html)

The following are validated for DCR flows:

  • The software statement needs to be specified.
  • If sending DCR JWT, validate that iss, iat, exp, aud, jti are all specified.
  • If the redirect_uris metadata element is omitted from the request, the entire contents of the software_redirect_uris element in the SSA are considered to be requested.
  • The software_id, if specified in the request, must match the software_id in the software statement.
  • If response_types is not specified, it should default to code id_token.
  • The following properties can be used interchangeably in the software statement:
    • The client_id can be passed as software_client_id
    • The client_name can be passed as software_client_name
    • The jwks_uri can be passed as software_jwks_endpoint

FAPI_AU-CDR

This follows the Australian Consumer Data Rights specification (https://consumerdatastandardsaustralia.github.io/standards/#client-registration)

The following are validated for DCR flows:

  • If the request is passed in as a JWT, it should contain iss, iat, exp, aud, jti, token_endpoint_auth_method, token_endpoint_auth_signing_alg, grant_types, response_types, id_token_signed_response_alg, id_token_encrypted_response_alg, id_token_encrypted_response_enc, software_statement.
  • If the software statement is present, it should contain iss, iat, exp, jti, jwks_uri, revocation_uri, recipient_base_uri, software_id, software_roles, scope, org_id, org_name, client_name, client_description, client_uri, redirect_uris, logo_uri.
dynamic_registration:
  recipe: FAPI_UK-OB                                        # The security profile to use, Options - Default, FAPI_DEFAULT, FAPI_UK-OB, FAPI_AU-CDR

Updated about 2 years ago