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.
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 PingAccess® or your choice of web access management solution to do so.
configuration wizard. To further protect against unauthorized access to the dynamic client registration endpoint, consider usingPer specification, this endpoint accepts only the HTTP POST method.
Endpoint: /as/clients.oauth2
- 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" }