PingFederate Server

Configuring dynamic client registration settings

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

About this task

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.

As dynamic client registration can expose your server to unwanted client registrations, we recommend protecting 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 have not yet switched from the default on-disk client storage to an external datastore, see OAuth client datastores. You can continue with the rest of the configuration; however, dynamic client registration remains inactive until an external client storage is defined.

Steps

  1. Go to System → OAuth Settings → Client Settings and click Dynamic Client Registration.

  2. Select the check boxes 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.

    Although optional, selecting this option can prevent unwanted client registrations.

    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 to make the following three client management/maintenance options visible.

    • Rotate Client Secret - Select this option to rotate the client secret when a client updates or retrieves its configuration. 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 authorizations server. This option is enabled by default.

    • Retain Client Secret - Select this option to allow the client secret to be temporarily retained after a change. This option is not enabled by default.

    When enabled, Client Secret Retention period can be configured on the Client Configuration Defaults page.

    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.

    For more information, see 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.

Other maintenance calls can be made to the registration_client_uri returned in the original registration response. This endpoint has the format /as/clients.oauth2/<clientId>.