OAuth Client Management Service
PingFederate includes a REST-based web service for OAuth client management.
The OAuth client management service is provided primarily for organizations with many OAuth clients, for allowing programmatic management of OAuth clients, and as an alternative to using the administrative console, the administrative application programming interface (API), or dynamic client registration.
The Endpoint: /pf-ws/rest/oauth/clients and Endpoint:/pf-ws/rest/oauth/clients/<clientId> REST resources are URL path extensions of the PingFederate runtime endpoint:
-
https://www.example.com:9031/pf-ws/rest/oauth/clients
-
https://www.example.com:9031/pf-ws/rest/oauth/clients/<clientId>
|
The OAuth Client Management Service requires client records to be stored on an external storage. |
|
Applications must authenticate to this web service using HTTP Basic authentication and credentials validated through an instance of a password credential validator (PCV). The PCV instance, in turn, must be selected in the OAuth authorization server (OAuth AS) configuration. |
|
The administrative API can also manage OAuth clients programmatically regardless of whether the client records are managed in XML files or in a database. |
Endpoint: /pf-ws/rest/oauth/clients
This resource accepts the POST, PUT, and GET methods. The POST and PUT methods described in this section require parameter name/value pairs formatted in JSON.
POST
Use the POST method to create a new client based on the parameters provided in the request. Parameters correspond to the fields on the Client window. The required MIME type is application/json.
- JSON Parameters
| Parameter | Description | ||||
|---|---|---|---|---|---|
(Required) |
A unique identifier the client provides to the resource server to identify itself. This identifier is included with every request the client makes |
||||
|
Specifies whether the client is enabled. The default value is |
||||
(Required) |
A descriptive name for the client instance. This name appears when the user is prompted for authorization |
||||
|
A description of what the client application does. This description appears when the user is prompted for authorization. |
||||
|
The authentication method that the client uses.
This authentication method requires the This authentication method requires the
|
||||
|
The client password or phrase. Required when the |
||||
|
The issuer distinguished name (DN) of the client certificate. These are certificate authority (CA) certificates imported into PingFederate on the Security → Certificate & Key Management → [.wintitle] Trusted CAs window. Alternatively, it might be set to Required when the |
||||
|
The subject DN of the client certificate. Required when the |
||||
|
The signing algorithm that the client must use to sign the JSON Web Token (JWT) for client authentication. Applicable only when the PingFederate accepts the following values:
If this parameter is not provided, the client can use any of the supported signing algorithms. |
||||
|
This field determines whether PingFederate mandates [.ph]a unique signed JWT from the client for each request when the client is configured to authenticate using the private_key_jwt client authentication method, to transmit request parameters using signed request objects, or to do both. A valid value is either
|
||||
|
Determines whether the client must transmit request parameters in a single, self-contained parameter. The parameter name is A valid value is either
For more information about request objects, see RFC 9101: JWT Secured Authorization Request (JAR). If this parameter is not provided, a value of |
||||
|
The signing algorithm that the client must use to sign its request objects for transmission of request parameters. Applicable only when the client might send its authorization requests using request objects. PingFederate accepts the following values:
If this parameter is not provided, the client can use any of the supported signing algorithms. |
||||
|
The URL of the JSON Web Key Set (JWKS) or the actual JWKS from the client. If the client is configured to use the Either value can be defined even if the client is not configured to use JWTs for authentication or transmission of request parameters. This flexibility allows the client to transmit request parameters in signed request objects for some requests and without the use of signed request objects for some other transactions. If the client signs its JWTs using an RSASSA-PSS signing algorithm, PingFederate must be deployed to run in a Java 8 or Java 11 runtime environment, or integrated with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. Learn more about HSM integration and static keys in Supported hardware security modules and Keys for OAuth and OpenID Connect, respectively. If the client is configured to encrypt ID tokens using an asymmetric encryption algorithm, either the JWKS URL or the actual JWKS must be provided. See the ID Token Key Management Encryption Algorithm setting. |
||||
|
include::ROOT:partial$pf_rc_redirect_uris.adoc[tags=pf_ph_desc_redirect_uris]. include::ROOT:partial$pf_rc_redirect_uris_granttypesinfo.adoc[tags=pf_ph_desc_redirect_uris_grantTypesInfo]. |
||||
|
The location of the logo used on user-facing OAuth grant authorization and revocation pages. For best results with the installed HTML templates, the recommended size is 72 x 72 pixels. |
||||
|
Whether the client can initiate an authentication API OAuth flow through the authorization endpoint without needing to handle HTTP redirects. Valid values are Consider the following when enabling this feature:
|
||||
|
Whether to enable the client to initiate a redirectless API OAuth flow through the authorization endpoint without HTTP cookies. Valid values are Instead of cookies, the flow uses an HTTP header to track the state of the authentication flow. The default header name is You can configure the name and lifetime of the header in the |
||||
|
If set to A valid value is either If this parameter is not provided, a value of |
||||
|
This setting controls whether all existing common scopes and scope groups, and those created in the future, or only the select few should be made available to the client. A valid value is either When set to When set to If this parameter is not provided, a value of
|
||||
|
Used in conjunction with the |
||||
|
This setting controls whether any exclusive scopes and scope groups should be made available to the client. As needed, provide this parameter with a list of exclusive scopes or scope groups that are intended for the client. The rest and any exclusive scopes and scope groups created in the future become invalid for the client. In other words, if the client tries to use such scope or scope group, it will receive an If this parameter is not provided, no exclusive scopes or scope groups are available to the client.
|
||||
|
An array of one or more grant types, which a client can request. PingFederate accepts the following values:
For more information about each grant type, see Grant types. |
||||
|
An array of one or more response types, which a client can request. PingFederate accepts the following values:
For more information about these response types, see Definitions of Multiple-Valued Response Type Combinations. If one or more response types are specified, the resulting client is only allowed to send one of the specified response types at runtime. Requests from this client with other response types will be rejected. Response type and grant type parameters must be provided in tandem because certain response types require one or more grant types, and vice versa. The following table provides a summary of their relationship. |
| response type | grant types |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
defaultAccessTokenManagerId |
include::ROOT:partial$pf_rc_defaultaccesstokenmanager.adoc[tags=pf_ph_desc_defaultAccessTokenManager] | ||||
|---|---|---|---|---|---|
|
| Applicable only to resource server clients. If selected, this resource server client is not required to specify the additional This check box is not selected by default. |
||||
|
Applicable when the client is configured to support the A valid value is either Determines whether the client must provide certain parameters to reduce the risk of authorization code interception attack. For more information, see the Proof Key for Code Exchange (PKCE) by OAuth Public Clients specification. When enabled, this client must include a one-time string value through the use of the If this parameter is not provided, the assumed value is |
||||
|
Overrides the Persistent Grant Max Lifetime value set globally in System → OAuth Settings → Authorization Server Settings.
|
||||
|
An integer representing units of time for storage of persistent grants for this client. Required when the |
||||
|
Units for the expiration time set by the Allowed values:
Required when the |
||||
|
Overrides the Persistent Grant Idle Timeout field value set globally in System → OAuth Settings → Authorization Server Settings. Allowed values:
If an idle timeout value is configured, the idle timeout window slides when a persistent grant is updated. For more information, see Transient grants and persistent grants. If you configure an idle timeout value, the idle timeout window slides when a persistent grant updates. When you have an idle timeout value configured without a maximum lifetime, persistent grants remain valid until they expire because of inactivity or until the grant storage revokes or removes them. When you have an idle timeout value configured with a maximum lifetime, persistent grants remain valid until they expire due to inactivity or lifetime expiration or until the grant storage removes them. |
||||
|
An integer representing the inactivity timeout value for this client. Required when the |
||||
|
Units for the inactivity timeout value set by the Allowed values:
Required when the |
||||
|
Overrides the Roll Refresh Token Values setting configured globally in System → OAuth Settings → Authorization Server Settings. A valid value is either Note that a value of If this parameter is not provided, the Roll Refresh Token Values setting configured globally in the System → OAuth Settings → [.wintitle] Authorization Server Settings** window is used. |
||||
|
When set to the default value, When set to |
||||
|
An integer that represents the minimum number of time that must pass before a new refresh token can be issued. This value overrides the global value in the Minimum Interval to Roll Refresh Tokens field on the Authorization Server Settings window when the Required when the |
||||
|
Units for the refresh token rolling interval set by the Valid values:
The default value is |
||||
|
The amount of time in seconds that a rolled refresh token is still valid in the event that the client failed to receive an updated one during a roll. NOTE: When a new refresh token is issued, it is the only valid token, and it invalidates its predecessor. |
||||
|
When set to This parameter works in conjunction with the PAR Status setting on the AS. For example:
Do not set this parameter to For more information about PAR, see Pushed authorization requests endpoint and Configuring authorization server settings. |
||||
|
Specifies whether the client must use the DPoP protocol for authentication. Valid values are The protocol is specified in OAuth 2.0 Demonstrating Proof of Possesion (DPoP) The Authorization Server Settings window includes settings for determining DPoP behavior. To learn more, see Configuring authorization server settings. |
||||
|
Whether the authorization server issues refresh tokens when the Valid values are |
||||
|
Whether the authorization server requires a prompt parameter value to be set to Valid values are This parameter will be ignored and set to |
||||
OpenID Connect client settings NOTE: The following parameters are only applicable when this client supports the OpenID Connect use cases. |
|||||
|
| The JSON Web Signature (JWS) algorithm required for the OIDC tokens. Allowed values:
|
||||
|
The algorithm used to encrypt or otherwise determine the value of the content encryption key. Allowed values: *
|
||||
|
The content encryption algorithm used to perform authenticated encryption on the plain text payload of the token. Required if an algorithm is provided through the Allowed values:
|
||||
|
The desired Open ID Connect policy. |
||||
|
Set to A valid value is either If this parameter is not provided, a value of
|
||||
|
Set to |
||||
|
Specify one HTTPS URL only. This parameter is applicable only if
|
||||
|
If set to A valid value is either If this parameter is not provided, a value of |
||||
|
A list of additional endpoints at the relying parties as needed. When the Logout Mode is set to OIDC Front-Channel or Ping Front-Channel, PingFederate sends requests to these URIs through the browser as part of the logout process. For Ping Front-Channel mode, the relying parties must return an image in their logout responses, otherwise PingFederate returns an error message or redirects to the |
||||
|
URIs to which PingFederate can redirect the user after a logout is performed, if the relying party’s logout request includes the |
||||
Device Authorization Grant client settings |
|||||
|
This field controls whether to use global device authorization grant settings defined on the System → OAuth Settings → [.wintitle] Authorization Server Settings** window. Allowed values are Set to
For example, if the base URL of your PingFederate server is https://www.example.com and this field is configured with a value of https://www.example.org/welcome, the target web server must redirect as follows:
This field controls whether PingFederate should skip this confirmation step. Set to |
||||
Client-initiated backchannel authentication (CIBA) client settings |
|||||
|
The token delivery method that the client supports. PingFederate supports poll and ping. Set to Set to If the client-initiated backchannel authentication (CIBA) grant type is enabled, this parameter is required; no value is assumed. |
||||
|
The client’s notification endpoint, to which PingFederate sends its ping call back messages. Required only if |
||||
|
Specifies the number of seconds that the client must wait between its attempts to check for the authorization results at the token endpoint. When PingFederate receives a token request within this time interval, it returns a A valid value ranges from If the CIBA grant type is enabled, this parameter is required; no value is assumed. |
||||
|
Specifies the CIBA request policy associated with the client. PingFederate uses CIBA request policies to determine various aspects of CIBA authentication request, such as the maximum lifetime of authentication requests, the validity of unsigned login hint tokens, and the mapping configuration of identity hints. Provide an existing CIBA policy If this parameter is not provided and the CIBA grant type is enabled, PingFederate associates the client with the CIBA request policy has been designated as the default CIBA request policy on the Applications → OAuth → [.wintitle] CIBA Request Policies** window. |
||||
|
Indicates whether the client supports user code. The purpose of this code is to authorize the transmission of an authentication request to the user’s authentication device. A valid value is either If this parameter is not provided and the CIBA grant type is enabled, user code support is not enabled. When user code support is enabled, the associated CIBA request policy must also be user code enabled. |
||||
|
Determines whether the client must transmit request parameters in a single, self-contained parameter. The parameter name is A valid value is either If this parameter is not provided and the CIBA grant type is enabled, CIBA signed requests are not required. If CIBA signed requests are required, the client must also be configured with either the JWKS URL or the actual JWKS from the client. |
||||
|
The signing algorithm that the client must use to sign its request objects for transmission of request parameters. PingFederate accepts the following values:
If this parameter is not provided and the CIBA grant type is enabled, the client can use any of the allowed signing algorithms. |
||||
Token introspection settings |
|||||
|
The JWS algorithm used to sign token introspection responses. This parameter is optional. PingFederate accepts the following values:
Default value is |
||||
|
The JSON Web Encryption (JWE) encryption algorithm used to encrypt the content-encryption key of token introspection responses. This parameter is optional. PingFederate accepts the following values:
For asymmetric algorithms, a JWKS or the HTTPS URL of a JWKS endpoint is required. For symmetric algorithms, the reversible secret is required. |
||||
|
The JWE content-encryption algorithm for token introspection responses. This parameter’s value must be set if the PingFederate accepts the following values:
|
||||
JWT secured authorization response mode (JARM) settings |
|||||
|
When enabled, the client must use JARM. The client’s authorization requests must include one of the following authorization response mode values:
JARM is a mechanism to enhance the security of the standard authorization response. It adds support for signing and encryption, sender authentication, and audience restriction. It also offers protection from replay, credential leakage, and mix-up attacks. JARM can be combined with any response type. For more information, see the JARM specification. A valid value is either |
||||
|
The JWS algorithm that PingFederate uses to sign JARM authorization responses. This parameter is optional. PingFederate accepts the following values:
Default value is |
||||
|
The JWE encryption algorithm used to encrypt the content-encryption key of JARM authorization responses. This parameter is optional. PingFederate accepts the following values:
For asymmetric algorithms, a JWKS or the HTTPS URL of a JWKS endpoint is required. For symmetric algorithms, the reversible secret is required. |
||||
|
The JWE content-encryption algorithm for JARM authorization responses. This parameter’s value must be set if the This parameter’s value must be null if the PingFederate accepts the following values:
|
||||
Extended properties |
|||||
|
{
"extendedParams": {
"entry": [
{
"key": "ContactName",
"value": {
"elements": "J. Smith"
}
},
{
"key": "ContactNumbers",
"value": {
"elements": [
"555-123-4567",
"555-987-6543"
]
}
}
]
}
}
Provide values for extended client metadata fields. {
...,
"extendedParams": {
"entry": [
{
"key": "ContactName",
"value": {
"elements": "J. Smith"
}
},
{
"key": "ContactNumbers",
"value": {
"elements": [
"555-123-4567",
"555-987-6543"
]
}
}
]
},
...
}
This sample request provides a value for a single-valued client metadata field, Extended client metadata fields are defined on the System → Server → [.wintitle] Extended Properties** window. |
||||
- Sample JSON
{
"client": [
{
"secret": "L1u508MfeZYTvR03kcpa6ezysNEspFEtzxSAIEOTll8AuNd2pnNqjkRdOXzfTFXc",
"clientId": "SampleClient",
"description": "This is a sample client.",
"grantTypes": [
"refresh_token",
"authorization_code"
],
"name": "Sample Client",
"redirectUris": [
"https://www.example.com/redirect1",
"https://www.example.com/redirect2"
]
}
]
}- Return codes
-
-
200 – Success
-
400 – Failed To Create Client
The response contains details as to why the client creation failed.
-
401 – Invalid Credentials
The user does not exist or is not authorized to create a client.
-
500 – Internal Server Error
An unknown error has occurred.
-
PUT
::
Updates client details for a specified client.
|
You cannot update a client ID value. You can delete the client record and create a new one with a new client ID value. |
- JSON Parameters
-
The same parameters described for POST apply for PUT with one addition:
forceSecretChange.
Use this parameter, set to true, in conjunction with the secret parameter to change a client pass phrase.
A valid value is either true or false.
If this parameter is not provided, a value of false is assumed.
|
If the |
- Sample JSON
{
"client": [
{
"secret": "L1u508MfeZYTvR03kcpa6ezysNEspFEtzxSAIEOTll8AuNd2pnNqjkRdOXzfTFXc",
"forceSecretChange": "true",
"clientId": "SampleClient",
"description": "This is a sample client.",
"grantTypes": [
"refresh_token",
"authorization_code"
],
"name": "Sample Client",
"redirectUris": [
"https://www.example.com/redirectOne",
"https://www.example.com/redirectTwo"
]
}
]
}- Return codes
-
-
200 – Success
The body contains a list of updated clients.400 – Failed To Update Client
The response contains details as to why the client could not be updated.
-
401 – Invalid Credentials
The user does not exist or is not authorized to update a client.
-
500 – Internal Server Error
An unknown error has occurred.
-
GET
::
Retrieves details for all OAuth clients.
- JSON Parameters
-
None.
- Return codes
-
-
200 – Success
The body contains JSON data for all clients.
The parameter
refreshRollingis not returned if the AS global setting is set for a client (the default). -
400 – Failed To Retrieve Clients
The response contains details as to why clients could not be retrieved.
-
401 – Invalid Credentials
The user does not exist or is not authorized.
-
500 – Internal Server Error
An unknown error has occurred.
-
Endpoint:/pf-ws/rest/oauth/clients/<clientId>
This resource accepts the GET and DELETE methods.
GET
::
Retrieves details for the specified client ID.
- JSON Parameters
-
None.
- Return codes
-
-
200 – Success
JSON client parameters are included.
The parameter
refreshRollingis not returned if the AS global setting is set for a client, the default setting. -
400 – Failed To Retrieve Client
The response contains details as to why client could not be retrieved.
-
401 – Invalid Credentials
The user does not exist or is not authorized.
-
500 – Internal Server Error
An unknown error has occurred.
-
DELETE
::
Deletes records for the specified client ID.
- JSON Parameters
-
None.
- Return codes
-
-
200 – Success
-
400 – Failed To Delete Client
The response contains details as to why client could not be deleted.
-
401 – Invalid Credentials
The user does not exist or is not authorized.
-
405 – Method Not Allowed
The client ID was not specified.
-
500 – Internal Server Error
An unknown error has occurred.
-
Logging
PingFederate records the actions performed through this endpoint in the runtime-api.log file. While the events themselves are not configurable, you can adjust the log4j2.xml configuration settings to alter the format and desired level of detail surrounding each event.
Each log entry contains information relating to the event, including:
-
Time the event occurred on the PingFederate server
-
Administrator username performing the action
-
Authentication method
-
Client IP
-
HTTP method
-
REST endpoint
-
HTTP status code
Each of the above fields is separated by a vertical pipe (|) for ease of parsing.