PingFederate includes a REST-based web service for OAuth client management. This service is provided primarily for organizations with many OAuth clients, allowing programmatic management of OAuth clients, as an alternative to using the administrative console, the administrative API, or dynamic client registration.
The /pf-ws/rest/oauth/clients and /pf-ws/rest/oauth/clients/<clientId> REST resources are URL path extensions of the PingFederate runtime endpoint; for example:
- 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. The Password Credential Validator instance, in turn, must be selected in the OAuth AS configuration.
The administrative API can also be used to 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 JavaScript Object Notation (JSON).
- POST
- Use the POST method to creates a new client based on the parameters provided in
the request. Parameters correspond to the fields on the Client
Management screen. The required MIME type is
application/json
.- JSON Parameters
-
Parameter Description clientId (Required)
A unique identifier the client provides to the resource server (RS) to identify itself. This identifier is included with every request the client makes. enabled Specifies whether the client is enabled. The default value is true
. A valid value is eithertrue
orfalse
.name (Required)
A descriptive name for the client instance. This name appears when the user is prompted for authorization. description A description of what the client application does. This description appears when the user is prompted for authorization. clientAuthnType The authentication method that the client uses. - Set to
none
if your use case does not require client authentication.Note: A value other thannone
is required for any of the following use cases:- This client uses the
client_credentials
grant type (see the grantTypes parameter). - This client signs its ID tokens using an HMAC signing algorithm (see the idTokenSigningAlgorithm parameter).
- This client is allowed to access the Session Revocation API endpoint (see the grantAccessSessionRevocationApi parameter).
- This client sends a secret parameter value.
- This client uses the
- Set to
SECRET
for HTTP Basic authentication.This authentication method requires the secret parameter.
- Set to
CLIENT_CERT
for mutual SSL/TLS authentication; recommended for client applications where security policies prohibit storing passwords.This authentication method requires the clientCertIssuerDn and clientCertSubjectDn parameters.
Important:If you choose mutual SSL/TLS authentication, you must configure a secondary PingFederate HTTPS port (see the property pf.secondary.https.port in the table under Configuring PingFederate properties).
- Set to
PRIVATE_KEY_JWT
check box if the client authenticates via the private_key_jwt client authentication method, as defined in Client Authentication in the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication).
secret The client password or phrase. Required when the clientAuthnType parameter is set to
SECRET
.clientCertIssuerDn The issuer DN of the client certificate. Note that these are CA certificates imported into PingFederate on the
screen. Alternatively, it may be set toTrust Any
to trust all the issuers found on the Trusted CAs screen.Required when the clientAuthnType parameter is set to
CLIENT_CERT
.clientCertSubjectDn The subject DN of the client certificate. Required when the clientAuthnType parameter is set to
CLIENT_CERT
.tokenEndpointAuthSigningAlgorithm The signing algorithm that the client must use to sign the JWTs for client authentication. Applicable only when the clientAuthnType parameter is provided with a value of
PRIVATE_KEY_JWT
.Allowed values:-
RS256
- RSA using SHA-256 -
RS384
- RSA using SHA-384 -
RS512
- RSA using SHA-512 -
ES256
- ECDSA using P256 Curve and SHA-256 -
ES384
- ECDSA using P384 Curve and SHA-384 -
ES512
- ECDSA using P521 Curve and SHA-512 -
PS256
- RSASSA-PSS using SHA-256 -
PS384
- RSASSA-PSS using SHA-384 -
PS512
- RSASSA-PSS using SHA-512Note:RSASSA-PSS signing algorithms require either a Java 11 runtime environment or an integration with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)
If this parameter is not provided, the client can use any of the supported signing algorithms.
enforceReplayPrevention Determines whether PingFederate mandates a unique signed JWT from the client for each request when the client is configured to authenticate via the private_key_jwt client authentication method, to transmit request parameters using in signed request objects, or to do both. A valid value is either
true
orfalse
.Note:The underlying Assertion Replay Prevention Service is cluster-aware (see Assertion Replay Prevention Service).
requireSignedRequests Indicates whether the client must transmit request parameters in a single, self-contained parameter. The parameter name is request. The value of the request parameter is a signed JWT whose claims represent the request parameters of the authorization request. The OpenID Connect specification calls this JWT a request object. A valid value is either
true
orfalse
.Note:If a client includes in an authorization request a request parameter (other than client_id and response_type) as a parameter outside of the signed request object and a claim inside of the signed request object, PingFederate always uses the claim value found inside the signed request object to process the request further.
For the client_id and response_type request parameters, the values outside of the signed request object must match the claim values inside of the signed request object. If the values do not match, PingFederate returns an error message to the client.
It is also worth noting that if a request parameter is found only outside of the signed request object, such request parameter is dropped and ignored; no error message is returned.
Tip:Per OAuth and OpenID Connect specifications, a client must always include in an authorization request the client_id, response_type, and scope request parameters outside of the signed request object.
For more information about request object, please refer to the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#RequestObject).
If this parameter is not provided, a value of
false
is assumed.requestObjectSigningAlgorithm The signing algorithm that the client must use to sign its request objects for transmission of request parameters. Applicable only when the client may send its authorization requests using request objects.
Allowed values:-
RS256
- RSA using SHA-256 -
RS384
- RSA using SHA-384 -
RS512
- RSA using SHA-512 -
ES256
- ECDSA using P256 Curve and SHA-256 -
ES384
- ECDSA using P384 Curve and SHA-384 -
ES512
- ECDSA using P521 Curve and SHA-512 -
PS256
- RSASSA-PSS using SHA-256 -
PS384
- RSASSA-PSS using SHA-384 -
PS512
- RSASSA-PSS using SHA-512Note:RSASSA-PSS signing algorithms require either a Java 11 runtime environment or an integration with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)
If this parameter is not provided, the client can use any of the supported signing algorithms.
jwksUrl, or jwks
The URL of the JSON Web Key Set (JWKS) or the actual JWKS from the client. Only one of them is required if the client is configured to use the private_key_jwt client authentication method, to transmit request parameters in signed request objects, or to transmit CIBA request parameter in signed request objects (or to do any of them) so that PingFederate can verify the authenticity of the JWTs.
In addition, either may also 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. (For runtime processing, see Authorization endpoint.)
If the client signs its JWTs using an RSASSA-PSS signing algorithm, PingFederate must be deployed to run in a Java 11 runtime environment or integrated with a hardware security module (HSM) to process the digital signatures. (For more information on HSM integration, see Supported hardware security modules.)
Finally, if the client is configured to encrypt ID tokens using an asymmetric encryption algorithm (see the ID Token Key Management Encryption Algorithm setting), either the JWKS URL or the actual JWKS must be provided.
redirectUris URIs to which the OAuth AS may redirect the resource owner's user agent after authorization is obtained. At least one redirection URI is required by the authorization code and implicit grant types. logoUrl 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.) bypassApprovalPage If set to true
, resource-owner approval for client access is assumed; PingFederate no longer presents to the user an authorization consent page or redirects to a trusted web application that is responsible to prompt the user for authorization for this client.A valid value is either
true
orfalse
.If this parameter is not provided, a value of
false
is assumed.restrictScopes 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
true
orfalse
.When set to
true
, PingFederate limits the client to a list of common scopes and scope groups as specified by the restrictedScopes parameter.When set to
false
, all existing common scopes and scope groups and those created in the future are available to the client.If this parameter is not provided, a value of
false
is assumed.Note: Depending on the configured dynamic scope patterns and whether they are defined as common or exclusive dynamic scopes, this setting and the restrictedScopes parameter value can impact the results of scope evaluation. The default scope, however, is always allowed for and available to all clients. For detailed information, refer to the Dynamic scope evaluation and per-client scope management section in Scopes and scope management.restrictedScopes Used in conjunction with the restrictScopes parameter value of true
to limit this client to a list of common scopes or scope groups in addition to the default scope. The rest and any common scopes and scope groups created in the future become invalid for the client; that is, if the client tries to use such scope or scope group, it will receive aninvalid_scope
error message from PingFederate.exclusiveScopes 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; that is, if the client tries to use such scope or scope group, it will receive an
invalid_scope
error message from PingFederate.If this parameter is not provided, no exclusive scopes or scope groups are available to the client.
Note: Depending on the configured dynamic scope patterns and whether they are defined as common or exclusive dynamic scopes, this setting can impact the results of scope evaluation. The default scope, however, is always allowed for and available to all clients. For detailed information, refer to the Dynamic scope evaluation and per-client scope management section in Scopes and scope management.grantTypes An array of one or more grant types, for which a client can request. Allowed values:-
authorization_code
-
implicit
-
refresh_token
-
client_credentials
-
urn:ietf:params:oauth:grant-type:device_code
-
urn:openid:params:grant-type:ciba
-
password
-
extension
(JWT Bearer Token or SAML 2.0 Bearer Assertion) -
urn:pingidentity.com:oauth2:grant_type:validate_ bearer
(For more information about each grant type, see Grant types.)
restrictedResponseTypes An array of one or more response types, for which a client can request. . Allowed values:-
code
-
code id_token
-
code id_token token
-
code token
-
id_token
-
id_token token
-
token
For more information about these response types, see Definitions of Multiple-Valued Response Type Combinations (openid.net/specs/oauth-v2-multiple-response-types-1_0.html#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.
Additionally, it is worth noting that the response types and grant types 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 code
authorization_code
code id_token
authorization_code
andimplicit
code id_token token
authorization_code
andimplicit
code token
authorization_code
andimplicit
id_token
implicit
id_token token
implicit
token
implicit
defaultAccessTokenManagerId The default Access Token Management (ATM) instance for this client. validateUsingAllEligibleAtms Applicable only to RS clients. If selected, this RS client is not required to specify additional parameters (access_token_manager_id or aud) to disambiguate the ATM instance in its token validation requests. When the RS client does not specify the desired ATM instance, PingFederate validates the access tokens against all eligible ATM instances. This simplifies interactions with PingAccess® by avoiding the need to align resource URIs between PingAccess and PingFederate.
This check box is not selected by default.
requireProofKeyForCodeExchange Applicable when the client is configured to support the authorization_code
grant type.A valid value is either
true
orfalse
.This field 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 (tools.ietf.org/html/rfc7636).
When enabled, this client must include a one-time string value through the use of the code_challenge parameter in its authorization request (see Authorization endpoint). It must also submit the corresponding code verifier via the code_verifier parameter in its token request when exchanging an authorization code for an access token (see OAuth grant type parameters).
If this parameter is not provided, the assumed value is
false
.persistentGrantExpirationType Overrides the Persistent Grant Max Lifetime field value set globally in the screen. Note:This setting can be overridden per grant-mapping configuration through the use of an extended persistent grant attribute
PERSISTENT_GRANT_LIFETIME
. ThePERSISTENT_GRANT_LIFETIME
attribute is defined on the screen. Once added, the lifetime of persistent grants can be set based on the outcome of attribute mapping expressions in individual grant-mapping configurations. For grant-mapping configurations that do not require this fine-grain control, they can be configured to use the default value.persistentGrantExpirationTime An integer representing units of time for storage of persistent grants for this client. Required when the persistentGrantExpirationType parameter is provided with a value of
OVERRIDE_SERVER_DEFAULT
.persistentGrantExpirationTimeUnit Units for the expiration time set by the persistentGrantExpirationTime parameter. Allowed values:-
h
(hours) -
d
(days) -
n
(minutes)
Required when the persistentGrantExpirationType parameter is provided with a value of
OVERRIDE_SERVER_DEFAULT
.persistentGrantIdleTimeoutType Overrides the Persistent Grant Idle Timeout field value set globally in the screen. Allowed values:-
SERVER_DEFAULT
(the default): Use the global setting. -
NONE
: Grants do not expire due to inactivity. -
OVERRIDE_SERVER_DEFAULT
: Use in conjunction with the persistentGrantIdleTimeout and persistentGrantIdleTimeoutUnit parameters to set the idle timeout window.
If an idle timeout value is configured, the idle timeout window slides when a persistent grant is updated (see Persistent versus transient grants).
When an idle timeout value is configured without a maximum lifetime, persistent grants remain valid until they expire due to inactivity, or are revoked or removed. When an idle timeout value is configured with a maximum lifetime, persistent grants remain valid until they expire (due to inactivity or lifetime expiration) or are removed from the grant storage.
persistentGrantIdleTimeout An integer representing the inactivity timeout value for this client. Required when the persistentGrantIdleTimeoutType parameter is provided with a value of
OVERRIDE_SERVER_DEFAULT
.persistentGrantIdleTimeoutTimeUnit Units for the inactivity timeout value set by the persistentGrantIdleTimeout parameter. Allowed values:-
h
(hours) -
d
(days) -
n
(minutes)
Required when the persistentGrantIdleTimeoutType parameter is provided with a value of
OVERRIDE_SERVER_DEFAULT
.refreshRolling Overrides the Roll Refresh Token Values setting configured globally in the screen. A valid value is either
true
orfalse
.Note that a value of
true
does not override the Minimum Interval to Roll Refresh Tokens (Hours) value set on the Authorization Server Settings screen.If this parameter is not provided, the Roll Refresh Token Values setting configured globally setting in the screen is used.
OpenID Connect client settings
Note: The following parameters are only applicable when the OpenID Connect protocol is enabled in screen and this client supports the OpenID Connect use cases.idTokenSigningAlgorithm The JSON Web Signature (JWS) algorithm required for the OpenID Connect ID tokens. Allowed values:-
none
- No signing algorithm -
HS256
- HMAC using SHA-256 -
HS384
- HMAC using SHA-384 -
HS512
- HMAC using SHA-512 -
ES256
- ECDSA using P256 Curve and SHA-256 -
ES384
- ECDSA using P384 Curve and SHA-384 -
ES512
- ECDSA using P521 Curve and SHA-512 -
RS256
- RSA using SHA-256 -
RS384
- RSA using SHA-384 -
RS512
- RSA using SHA-512 -
PS256
- RSASSA-PSS using SHA-256 -
PS384
- RSASSA-PSS using SHA-384 -
PS512
- RSASSA-PSS using SHA-512Note:RSASSA-PSS signing algorithms require either a Java 11 runtime environment or an integration with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)
Important:If static keys for OAuth and OpenID Connect are enabled, use either an RSA algorithm or an EC algorithm that has been configured with an active static key.
idTokenEncryptionAlgorithm The algorithm used to encrypt or otherwise determine the value of the content encryption key. Allowed values:-
dir
- Direct Encryption with symmetric key -
A128KW
- AES-128 Key Wrap -
A192KW
- AES-192 Key Wrap -
A256KW
- AES-256 Key Wrap -
A128GCMKW
- AES-GCM-128 key encryption -
A192GCMKW
- AES-GCM-192 key encryption -
A256GCMKW
- AES-GCM-256 key encryption -
ECDH-ES
- ECDH-ES -
ECDH-ES+A128KW
- ECDH-ES with AES-128 Key Wrap -
ECDH-ES+A192KW
- ECDH-ES with AES-192 Key Wrap -
ECDH-ES+A256KW
- ECDH-ES with AES-256 Key Wrap -
RSA-OAEP
- RSAES-OAEP
idTokenContentEncryptionAlgorithm 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 idTokenEncryptionAlgorithm parameter.
Allowed values:-
A128CBC-HS256
- Composite AES-CBC-128 HMAC-SHA-256 -
A192CBC-HS384
- Composite AES-CBC-192 HMAC-SHA-384 -
A256CBC-HS512
- Composite AES-CBC-256 HMAC-SHA-512 -
AES-GCM-128
- A128GCM -
AES-GCM-192
- A192GCM -
AES-GCM-256
- A256GCM
policyGroupId The desired Open ID Connect policy. grantAccessSessionRevocationApi Set to true
to allow this client to access the Session Revocation API for back-channel session query and revocation.A valid value is either
true
orfalse
.If this parameter is not provided, a value of
false
is assumed.Note:Generally speaking, if clients are allowed to add sessions to the revocation list, consider enabling the Check session revocation status option in the applicable Access Token Management instances so that the token validation process takes into account whether a session has been added to the revocation list. (For more information, see Managing session validation settings.)
pairwiseUserType Set to true
to allow this client to use pairwise pseudonymous IDs. This parameter is set tofalse
by default.sectorIdentifierUri Specify one HTTPS URL only. This parameter is applicable only if pairwiseUserType is set to true. Note: If the Track User Sessions for Logout check box is selected in the screen, you can provide two additional parameters to enable asynchronous front-channel logout for this client.pingAccessLogoutCapable If set to true
, PingFederate sends (via the browser) logout requests to an OpenID Connect endpoint in PingAccess as part of the logout process.A valid value is either
true
orfalse
.If this parameter is not provided, a value of
false
is assumed.logoutUris A list of additional endpoints at the relying parties as needed. PingFederate sends (via the browser) requests to these URIs as part of the logout process. Note that the relying parties must return an image in their logout responses; otherwise, PingFederate returns an error message or redirect to the InErrorResource parameter value (if specified).. Device Authorization Grant client settings
deviceFlowSettingType This field controls whether to use global device authorization grant settings defined on the screen.Allowed values are
SERVER_DEFAULT
andOVERRIDE_SERVER_DEFAULT
.Set to
OVERRIDE_SERVER_DEFAULT
and configure any of the following settings.- userAuthzUrlOverride
- This field controls whether PingFederate should use a different URL, perhaps for ease of use or branding purposes, when formulating the verification URLs to be included in its device authorization responses (see Device authorization endpoint).
- pendingAuthzTimeoutOverride
- The lifetime of an activation code (the user_code parameter value) in seconds.
- devicePollingIntervalOverride
- The amount of time in seconds that the device waits between polling requests to the PingFederate token endpoint.
- bypassActivationCodeConfirmationOverride
- When PingFederate receives a verification
request that includes an activation code (the
user_code parameter value),
it prompts the user to confirm the activation
code.
This field controls whether PingFederate should skip this confirmation step.
Set to
true
if you want PingFederate to skip the confirmation step.
Client-initiated backchannel authentication (CIBA) client settings
cibaTokenDeliveryMode The token delivery method supported by the client. PingFederate supports poll and ping. Set to
poll
if the client can check for the authorization results periodically at the token endpoint.Set to
ping
if the client prefers to wait for a ping callback message from PingFederate as a signal that the authorization result is ready for pickup.If the CIBA grant type is enabled, this parameter is required; no value is assumed.
cibaNotificationEndpoint The client's notification endpoint, to which PingFederate sends its ping call back messages. Required only if ping is the configured token delivery method.
cibaPollingInterval 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 slow_down
error message to the client.A valid value ranges from
1
to3600
.If the CIBA grant type is enabled, this parameter is required; no value is assumed.
cibaPolicyId The CIBA request policy associated with the client. PingFederate uses CIBA request policies to determine various aspects of CIBA authentication requests; for example, 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
screen.cibaUserCodeSupported 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
true
orfalse
.If this parameter is not provided and the CIBA grant type is enabled, user code support is not enabled.
Note that when user code support is enabled, the associated CIBA request policy must also be user code-enabled.
cibaRequireSignedRequests Indicates whether the client must transmit request parameters in a single, self-contained parameter. The parameter name is request. The value of the request parameter is a signed JWT whose claims represent the request parameters of the authorization request. The OpenID Connect specification calls this JWT a request object. A valid value is either
true
orfalse
.If this parameter is not provided and the CIBA grant type is enabled, CIBA signed requests are not required.
Note that if CIBA signed requests are required, the client must also be configured with either the JWKS URL or the actual JWKS from the client.
cibaRequestObjectSigningAlgorithm The signing algorithm that the client must use to sign its request objects for transmission of request parameters. Allowed values:-
RS256
- RSA using SHA-256 -
RS384
- RSA using SHA-384 -
RS512
- RSA using SHA-512 -
ES256
- ECDSA using P256 Curve and SHA-256 -
ES384
- ECDSA using P384 Curve and SHA-384 -
ES512
- ECDSA using P521 Curve and SHA-512 -
PS256
- RSASSA-PSS using SHA-256 -
PS384
- RSASSA-PSS using SHA-384 -
PS512
- RSASSA-PSS using SHA-512Note:RSASSA-PSS signing algorithms require either a Java 11 runtime environment or an integration with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)
If this parameter is not provided and the CIBA grant type is enabled, the client can use any of the allowed signing algorithms.
Extended properties
extendedParameters Provide values for extended client metadata fields; for example: { ..., "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 (ContactName) and multiple values for a multivalued client metadata field (ContactNumbers).
(Extended client metadata fields are defined on the
screen.) - Set to
- 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.Note:
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
orfalse
.If this parameter is not provided, a value of
false
is assumed.Note:If the secret parameter is used without a forceSecretChange parameter value of
true
, the secret value is ignored. - 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 ClientThe 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.
- 200 – Success
- GET
- Retrieves details for all OAuth clients.
- JSON Parameters
- None.
- Return codes
-
- 200 – SuccessThe body contains JSON data for all clients.Note:
The parameter refreshRolling is 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.
- 200 – Success
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.Note:
The parameter refreshRolling is not returned if the AS global setting is set for a client (the default).
- 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.
- 200 – Success
- 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 via this endpoint in the runtime-api.log file. While the events themselves are not configurable, you may 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.