PingFederate Server

Dynamic client registration endpoint

The client registration endpoint allows developers to dynamically register OAuth clients on a PingFederate authorization server.

The OAuth 2.0 Dynamic Client Registration Protocol defines this endpoint. Developers can send client registrations with the desired properties, such as client metadata, to this endpoint. If the requests are valid, PingFederate evaluates them and returns a response with a client ID and the registered client metadata values.

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

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.

You can configure access token requirement and client registration policies using the System → OAuth Settings → Client Settings window. 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.

This endpoint accepts only the HTTP POST method.

Endpoint: /as/clients.oauth2

Both the request and the response follow the OAuth 2.0 Dynamic Client Registration Protocol.

Example 1

A developer wants to register a client that supports the authorization code flow, two 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
  "grant_access_session_management_api": false
}

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

Additionally, when a registration request does not specify a client authentication method (token_endpoint_auth_method), PingFederate defaults to client_secret_basic per OAuth 2.0 Dynamic Client Registration Protocol.

Example 2

A developer wants to register a client that supports the authorization code flow, refresh tokens, one redirection URI, one profile scope, 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."
}

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, two 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
  "grant_access_session_management_api": false
}

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"
}