Configuring dynamic client registration settings

Dynamic client registration allows developers to register OAuth clients through an API based on open standards.

PingFederate supports various client metadata as described in Supported client metadata. If specific use cases require additional metadata, add them as extended properties in System > Server > Extended Properties.

Because dynamic client registration can expose your server to unwanted client registrations, you should protect PingFederate by requiring an initial access token, configuring one or more client registration policies, and protecting access to the dynamic client registration endpoint.

Dynamic client registration requires OAuth client storage in an external datastore, such as a database or LDAP directory. If you haven’t switched from the default on-disk client storage to an external datastore, refer to OAuth client datastores. You can continue with the rest of the configuration, but dynamic client registration remains inactive until an external client storage is defined.

Steps

In the PingFederate admin console, go to System > OAuth Settings > Client Settings and click Dynamic Client Registration.

Select the checkboxes for the options that you want to use.

The following table describes each option:

Option Description

Enable Dynamic Client Registration

Select this option to enable dynamic client registration. This option is disabled by default.

Require Initial Access Token

Select this option to require an initial access token. If selected, you must also select the required scope or scope group from the list.

Developers must be set up to obtain access tokens with the required scope or scope group from your PingFederate authorization server. For example, you can create a new OAuth client for a group of developers, assign this client a specific scope for the purpose of creating other clients using the OAuth 2.0 Dynamic Client Registration protocol, and let the developers obtain their access tokens directly by completing one of the supported OAuth flows. You can also write a custom web application that uses the OAuth flow to obtain access tokens on behalf of the developers as they make their requests.

This option is enabled by default.

Enable Dynamic Client Registration Management

Select this option to enable dynamic client registration management and make the following three client management and maintenance options visible.

Rotate Client Secret: Select this option to automatically generate a new client secret whenever the client configuration is retrieved or updated. The response includes the new secret. This option is enabled by default.
Rotate Registration Access Token: Select this option to rotate the registration access token when a client updates or retrieves its configuration. This option is enabled by default.
Allow Client Delete: Select this option to allow clients to deprovision themselves on the authorization server. This option is enabled by default.
Retain Client Secret: Select this option to allow the current client secret to remain valid for a limited time after rotation. This option is not enabled by default. The specific retention period is defined in Client Configuration Defaults.

Dynamic client registration management allows a client to retrieve its configuration through GET requests, to update its configuration through PUT requests to the provided registration client URI, and to deprovision itself through a DELETE.

Learn more in the OAuth 2.0 Dynamic Client Registration Management Protocol.

This option is disabled by default.

Result

When Dynamic Client Registration is active, developers can send client registrations to the /as/clients.oauth2 endpoint to create OAuth clients dynamically.

When Dynamic Client Management is enabled, developers can perform maintenance through the registration_client_uri provided in the initial registration response. This endpoint follows the standard format: /as/clients.oauth2/<clientId>.

Example: Dynamic client registration with client management enabled

In this example, Dynamic Client Management, Rotate Client Secret, and Rotate Registration Access Token are all enabled. The registration response includes a registration_access_token and registration_client_uri that the client uses for subsequent management requests.

Registration request response

HTTP/1.1 201 Created
Date: Fri, 13 Oct 2017 12:34:56 GMT
Referrer-Policy: origin
Content-Type: application/json
Transfer-Encoding: chunked

{
  "client_id": "dc-F3JxcBlNCtjk36J3Yi4yQK",
  "client_name": "Example Org Sample One",
  "redirect_uris": [
    "https://example.org/app1",
    "https://example.org/appM"
  ],
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": [
    "authorization_code"
  ],
  "client_secret": "fYhGUjnkjGp0UPQGaAfdcS",
  "client_secret_expires_at": 0,
  "scope": "phone email",
  "validate_using_all_eligible_atms": false,
  "refresh_token_rolling_policy": "server_default",
  "persistent_grant_expiration_type": "server_default",
  "grant_access_session_revocation_api": false,
  "grant_access_session_management_api": false,
  "registration_access_token": "zzeFGGmCB80THfWTl6cxOayfYwVv",
  "registration_client_uri": "https://www.example.com/as/clients.oauth2/dc-F3JxcBlNCtjk36J3Yi4yQK"
}

The client can use the registration_access_token as a bearer token to retrieve or update its configuration at the registration_client_uri.

Retrieve client details request

GET /as/clients.oauth2/dc-F3JxcBlNCtjk36J3Yi4yQK HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer zzeFGGmCB80THfWTl6cxOayfYwVv
Host: www.example.com

Response

HTTP/1.1 200 OK
Date: Fri, 13 Oct 2017 15:30:00 GMT
Referrer-Policy: origin
Content-Type: application/json
Transfer-Encoding: chunked

{
  "client_id": "dc-F3JxcBlNCtjk36J3Yi4yQK",
  "client_name": "Example Org Sample One",
  "redirect_uris": [
    "https://example.org/app1",
    "https://example.org/appM"
  ],
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": [
    "authorization_code"
  ],
  "client_secret": "p7MD0Ul1DNI9xRDc5kcOxs",
  "client_secret_expires_at": 0,
  "scope": "phone email",
  "validate_using_all_eligible_atms": false,
  "refresh_token_rolling_policy": "server_default",
  "persistent_grant_expiration_type": "server_default",
  "grant_access_session_revocation_api": false,
  "grant_access_session_management_api": false,
  "registration_access_token": "7fnyvAsfEOEF2nw7ZNOtSu8tgSAh",
  "registration_client_uri": "https://www.example.com/as/clients.oauth2/dc-F3JxcBlNCtjk36J3Yi4yQK"
}

Because Rotate Client Secret and Rotate Registration Access Token are enabled, the response includes a new client_secret and registration_access_token.

Update client details request

PUT /as/clients.oauth2/dc-F3JxcBlNCtjk36J3Yi4yQK HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer 7fnyvAsfEOEF2nw7ZNOtSu8tgSAh
Host: www.example.com

{
  "client_name": "Example Org Sample New Name",
  "redirect_uris": [
    "https://example.org/app2"
  ],
  "scope": "profile",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ]
}

Response

HTTP/1.1 200 OK
Date: Fri, 13 Oct 2017 15:30:00 GMT
Referrer-Policy: origin
Content-Type: application/json
Transfer-Encoding: chunked

{
  "client_id": "dc-F3JxcBlNCtjk36J3Yi4yQK",
  "client_name": "Example Org Sample New Name",
  "redirect_uris": [
    "https://example.org/app2"
  ],
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "client_secret": "MaRvd8OjidqtW9THaRq11I",
  "client_secret_expires_at": 0,
  "scope": "profile",
  "validate_using_all_eligible_atms": false,
  "refresh_token_rolling_policy": "server_default",
  "persistent_grant_expiration_type": "server_default",
  "grant_access_session_revocation_api": false,
  "grant_access_session_management_api": false,
  "registration_access_token": "14YCzuBoOo6C9zgbekhJoV9G5KBx",
  "registration_client_uri": "https://www.example.com/as/clients.oauth2/dc-F3JxcBlNCtjk36J3Yi4yQK"
}

PingFederate returns 200 OK with the updated client configuration. The response reflects all fields sent in the PUT request.

PingFederate Server

Configuring dynamic client registration settings

Steps

Result

Example: Dynamic client registration with client management enabled

Related links