This runtime endpoint allows developers to register OAuth clients on PingFederate authorization server dynamically based the OAuth 2.0 Dynamic Client Registration Protocol specification (tools.ietf.org/html/rfc7591). In essence, developers can send client registrations with the desired properties (client metadata) to this endpoint. PingFederate evaluates the requests and returns a response with a client ID and the registered client metadata values if the requests are valid.

This runtime endpoint is only active when dynamic registration client is enabled and configured.

Important:

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

.

You can configure access token requirement and client registration policies using the OAuth Server > Client Settings configuration wizard. To further protect against unauthorized access to the dynamic client registration endpoint, consider using PingAccess® or your choice of web access management solution to do so.

Note:

Per specification, this endpoint accepts only the HTTP POST method.

Endpoint: /as/clients.oauth2

Both the request and the response follow the specification.
Example 1
A developer wants to register a client that supports the authorization code flow, a couple redirection URIs, two scopes, and HTTP Basic as the client authentication method. In this example, PingFederate is not configured to require an initial access token.
Request
POST /as/clients.oauth2 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: sso.example.com

{
  "client_name":"Example Org Sample One",
  "redirect_uris":[
    "https://example.org/app1",
    "https://example.org/appM"
  ],
  "scope":"email phone",
  "grant_types":[
    "authorization_code"
  ]
}
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
}

Note that PingFederate returns 201 Created, the client ID, and other registered client metadata after creating the new client.

In addition, when a registration request does not specify a client authentication method (token_endpoint_auth_method), PingFederate defaults to client_secret_basic per RFC7591.

Example 2
A developer wants to register a client that supports the authorization code flow, refresh tokens, one redirection URI, one scope (profile), and HTTP Basic as the client authentication method. In this example, PingFederate is not configured to require an initial access token. However, the profile scope is restricted. As a result, the registration request should fail.
Request
POST /as/clients.oauth2 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: www.example.com

{
  "client_name":"Example Org Sample Two",
  "redirect_uris":[
    "https://example.org/app2"
  ],
  "scope":"profile",
  "grant_types":[
    "authorization_code",
    "refresh_token"
  ]
}
Response
HTTP/1.1 400 Bad Request
Date: Fri, 13 Oct 2017 13:00:00 GMT
Referrer-Policy: origin
Content-Type: application/json
Transfer-Encoding: chunked
{
  "error": "invalid_client_metadata",
  "error_description": "The requested scope is invalid."
}

Note that PingFederate returns 400 Bad Request and the relevant error message when a client registration fails.

Example 3
A developer wants to register a client that supports the authorization code flow, a couple redirection URIs, two scopes, and HTTP Basic as the client authentication method. In this example, PingFederate is configured to require an initial access token.
Request
POST /as/clients.oauth2 HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImsxIn0.eyJzY29wZSI6WyJkQ1IiXSwiY2xpZW50X2lkX25hbWUiOiJwYXJ0bmVyRGV2X0FjbWUiLCJhZ2lkIjoiMG44NHV6Nm1mZFJWbzNIWU9VODlrc3FxMTVNR3hxUFMiLCJVc2VybmFtZSI6Ikl2YW4gTW9rIiwiT3JnTmFtZSI6IkFDTUUgRGV2IiwiZXhwIjoxNTA4MzY3MDcyfQ.XfKd8--CHtcQ79Wefz2Sw5GOB5LfV9mWJ0n3vzJ93Ie7wbEAkalIFg53J-9e7s59MjA1igx6ybflGMQ9QAjYobs-jM24arJZZgopEXvcx6IQpyU8U4AMTJ7tr9Lmody8P0QZOKcUDBTT5egv9vr5NuXCtUBfVPhGZ-3p5g5mwrnGHBfqZOAsg7U4hKq8cauKQtVyBBV9iIZNG5Q3ovnxBTclKII9HX-oDhmilbmiga4319YSFfX5-U3li9XPeN3JZB2ukLbTFjjVIVLJIInbSR_IFTWP5Irg92aXLrIfm5MvBp8D1fOU6xYjbgjvw9QKNiFFVD7oEeJG9MwzgcGruw
Host: www.example.com

{
  "client_name":"Example Org Sample Three",
  "redirect_uris":[
    "https://example.org/app3",
    "https://example.org/appN"
  ],
  "scope":"email phone",
  "grant_types":[
    "authorization_code"
  ]
}
Response
HTTP/1.1 201 Created
Date: Fri, 13 Oct 2017 15:30:00 GMT
Referrer-Policy: origin
Content-Type: application/json
Transfer-Encoding: chunked

{
  "client_id": "dc-rqUtii4vRXj5NMztkAeJ1S",
  "client_name": "Example Org Sample Three",
  "redirect_uris": [
    "https://example.org/app3",
    "https://example.org/appN"
  ],
  "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
}

Note that the registration request must include an Authorization HTTP header with a valid access token as its value.

If the authorization fails, PingFederate returns the following JSON payload in the response:

{
  "error": "invalid_access_token",
  "error_description": "Please provide a valid Access Token with the correct scope"
}