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 several OAuth clients, for allowing programmatic management of OAuth clients, and as an alternative to using the administrative console, the administrative 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 use of external storage for storing client records. |
|
Applications must authenticate to this web service using HTTP Basic authentication and credentials that are validated through a password credential validator (PCV) instance. The PCV instance, in turn, must be selected in the OAuth authorization server 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 endpoint 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
MIMEtype isapplication/json.- JSON Parameters
| Parameter | Description | ||||
|---|---|---|---|---|---|
|
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. Valid values are |
||||
|
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 > 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. |
||||
|
Determines whether PingFederate mandates 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 in signed request objects, or to do both. Valid values are
|
||||
|
Determines whether the client must transmit request parameters in a single, self-contained parameter. The parameter name is The value of the Valid values are
Learn more about request objects in RFC 9101: JWT Secured Authorization Request (JAR). If this parameter is not provided, the default value of |
||||
|
PingFederate accepts the following values:
Applicable only when the client might send its authorization requests using request objects. If this parameter is not provided, the client can use any of the supported signing algorithms. |
||||
|
Determines whether PingFederate mandates 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 in signed request objects, or to do both. Valid values are |
||||
|
URIs where the OAuth AS can redirect the resource owner’s user agent after authorization is obtained. The authorization code and implicit grant types require at least one redirection URI. |
||||
|
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. |
||||
|
If set to Valid values are If this parameter is not provided, the default value of |
||||
|
Controls whether all existing common scopes and scope groups and those created in the future, or only the selected ones, should be made available to the client. Valid values are When set to When set to If this parameter is not provided, the default value of
|
||||
|
Used in conjunction with the Scopes and scope groups that are not listed or are created in the future become invalid for the client. If the client tries to use an excluded scope or scope group, it will receive an |
||||
|
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. Excluded scopes and scope groups and those created in the future become invalid for the client. If the client tries to use an excluded 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:
Learn more about each grant type in Grant types. |
||||
|
An array of one or more response types, which a client can request. PingFederate accepts the following values:
Learn more about these response types, in 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 |
Determines the default Access Token Management (ATM) instance for this client. | ||||
|---|---|---|---|---|---|
|
Applicable only to resource server clients. If selected, this resource server client is not required to specify the additional This checkbox is not selected by default. |
||||
|
Applicable when the client is configured to support the Valid values are Determines whether the client must provide certain parameters to reduce the risk of authorization code interception attack. Learn more in 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 default value of |
||||
|
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. Valid values are
If this parameter is not provided, the Roll Refresh Token Values setting configured globally in the System > OAuth Settings > Authorization Server Settings window is used. |
||||
|
When set to the default value, When set to |
||||
|
The minimum number of hours 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 Valid values are an integer between Required when the |
||||
|
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.
|
||||
|
When set to 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 OAuth 2.0 Demonstrating Proof of Possession (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. Learn more in Configuring authorization server settings. |
||||
|
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 Valid values are If this parameter is not provided, the default value of
|
||||
|
Set to |
||||
|
Specify one HTTPS URL only. This parameter is applicable only if |
||||
|
|||||
|
If set to Valid values are If this parameter is not provided, the default 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 |
||||
|
Controls whether to use global device authorization grant settings defined on the System > OAuth Settings > [.wintitle] Authorization Server Settings** window. Valid 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 |
||||
|
The token delivery method that the client supports. PingFederate supports 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 Valid values are an integer 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.
|
||||
|
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. Valid values are 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. |
||||
|
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. |
||||
|
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) 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:
|
||||
|
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. Learn more in the JARM specification. Valid values are |
||||
|
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:
|
||||
|
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 > 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.
Valid values are true or false.
If this parameter is not provided, the default value of false applies.
|
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 – SuccessThe 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 CredentialsThe user does not exist or is not authorized to update a client.
-
500 – Internal Server ErrorAn unknown error has occurred.
-
- GET
-
Retrieves details for all OAuth clients.
- JSON Parameters
-
None.
- Return codes
-
-
200 – SuccessThe 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 ClientsThe response contains details as to why clients could not be retrieved.
-
401 – Invalid CredentialsThe user does not exist or is not authorized.
-
500 – Internal Server ErrorAn 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 – SuccessJSON 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 ClientThe response contains details as to why client could not be retrieved.
-
401 – Invalid CredentialsThe user does not exist or is not authorized.
-
500 – Internal Server ErrorAn unknown error has occurred.
-
- DELETE
-
Deletes records for the specified client ID.
- JSON Parameters
-
None.
- Return codes
-
-
200 – Success -
400 – Failed To Delete ClientThe response contains details as to why client could not be deleted.
-
401 – Invalid CredentialsThe user does not exist or is not authorized.
-
405 – Method Not AllowedThe client ID was not specified.
-
500 – Internal Server ErrorAn 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.