PingFederate Server

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 /pf-ws/rest/oauth/clients and /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

clientId

(Required)

A unique identifier the client provides to the resource server 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 either true or false.

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.

    A value other than none 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 can access the Session Revocation API endpoint. See the grantAccessSessionRevocationApi parameter.

    • This client sends a secret parameter value.

  • Set to SECRET for HTTP Basic authentication.

    This authentication method requires the secret or client_secret_jwt 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.

    If you choose mutual SSL/TLS authentication, you must configure a secondary PingFederate HTTPS port. For more information, 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 through the private_key_jwt client authentication method, as defined in Client Authentication in the OpenID Connect specification. For more information, see openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication.

  • Set to CLIENT_SECRET_JWT check box if the client authenticates through the client_secret_jwt client authentication method, as defined in Client Authentication in the OpenID Connect specification. For more information, see 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 or CLIENT_SECRET_JWT.

clientCertIssuerDn

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 Trust Any to trust all the issuers found on the Trusted CAs window.

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 JSON Web Token (JWT) for client authentication.

Applicable only when the clientAuthnType parameter is provided with a value of PRIVATE_KEY_JWT or CLIENT_SECRET_JWT.

PingFederate accepts the following values:

  • RS256 - RSA using SHA-256

  • RS384 - RSA using SHA-384

  • RS512 - RSA using SHA-512

  • 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

  • PS256 - RSASSA-PSS using SHA-256

  • PS384 - RSASSA-PSS using SHA-384

  • PS512 - RSASSA-PSS using SHA-512

    RSASSA-PSS signing algorithms require a Java 8 or 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 Keys for OAuth and OpenID Connect, respectively.

If this parameter is not provided, the client can use any of the supported signing algorithms.

enforceReplayPrevention

This field determines whether PingFederate mandates [.ph]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 or false.

The underlying Assertion Replay Prevention Service is cluster-aware. For more information, see Assertion Replay Prevention Service.

requireSignedRequests

Determines 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 [.ph]a signed JWT whose claims represent the request parameters of the authorization request. The OpenID Connect (OIDC) specification calls this JWT a request object.

A valid value is either true or false.

If a client includes in an authorization request a request parameter other than client_id, 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 request parameter, 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.

If a request parameter is found only outside of the signed request object, PingFederate ignores the request parameter and returns no error message.

Per OAuth and OpenID Connect specifications, a client must always include in an authorization request the client_id parameter outside of the signed request object.

For more information about request objects, see RFC 9101: JWT Secured Authorization Request (JAR).

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 might send its authorization requests using request objects.

PingFederate accepts the following values:

  • RS256 - RSA using SHA-256

  • RS384 - RSA using SHA-384

  • RS512 - RSA using SHA-512

  • 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

  • PS256 - RSASSA-PSS using SHA-256

  • PS384 - RSASSA-PSS using SHA-384

  • PS512 - RSASSA-PSS using SHA-512

    RSASSA-PSS signing algorithms require a Java 8 or 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 Keys for OAuth and OpenID Connect, respectively.

If this parameter is not provided, the client can use any of the supported signing algorithms.

jwksUrl orjwks

The URL of the JSON Web Key Set (JWKS) or the actual JWKS from the client.

If the client is configured to use the private_key_jwt or client_secret_jwt client authentication method, to transmit request parameters in signed request objects, or to transmit CIBA request parameters in signed request objects, only one of the previous values is required for PingFederate to verify the authenticity of the JWTs.

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.

For information on 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 8 or Java 11 runtime environment, or integrated 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 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.

redirectUris

URIs where the OAuth AS may redirect the resource owner’s user agent after authorization is obtained.

The authorization code and implicit grant types require at least one redirection URI.

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, and 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 or false.

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 or false.

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.

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, see the include::ROOT:partial$pf_rc_exclusivedynamicscopeevaluation.adoc[tags=pf_ph_exclusiveDynamicScopeEvaluation] 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 an invalid_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. In other words, 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.

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, see the include::ROOT:partial$pf_rc_exclusivedynamicscopeevaluation.adoc[tags=pf_ph_exclusiveDynamicScopeEvaluation] section in Scopes and scope management.

grantTypes

An array of one or more grant types, which a client can request.

PingFederate accepts the following 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)

For more information about each grant type, see Grant types.

restrictedResponseTypes

An array of one or more response types, which a client can request.

PingFederate accepts the following 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.

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

code

authorization_code

code id_token

authorization_code and implicit

code id_token token

authorization_code and implicit

code token

authorization_code and implicit

id_token

implicit

id_token token

implicit

token

implicit

defaultAccessTokenManagerId

Determines the default Access Token Management (ATM) instance for this client.

validateUsingAllEligibleAtms

Applicable only to resource server clients.

If selected, this resource server client is not required to specify the additional access_token_manager_id or aud parameters to disambiguate the ATM instance in its token validation requests. When the resource server 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 or false.

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 code_challenge parameter in its authorization request. For more information, see Authorization endpoint. It must also submit the corresponding code verifier through the code_verifier parameter in its token request when exchanging an authorization code for an access token. For more information, see OAuth grant type parameters.

If this parameter is not provided, the assumed value is false.

persistentGrantExpirationType

Overrides the Persistent Grant Max Lifetime value set globally in System → OAuth Settings → Authorization Server Settings.

This setting can be overridden per grant-mapping configuration through the use of an extended persistent grant attribute PERSISTENT_GRANT_LIFETIME. The PERSISTENT_GRANT_LIFETIME attribute is defined in System → OAuth Settings → Authorization Server Settings. When this attribute is active, you can set the lifetime of persistent grants 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, you can configure them 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 System → OAuth Settings → Authorization Server Settings.

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. 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.

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 System → OAuth Settings → Authorization Server Settings.

A valid value is either true or false.

Note that a value of true does not override the Minimum Interval to Roll Refresh Tokens value set on the Authorization Server Settings window.

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.

refreshTokenRollingIntervalType

When set to the default value, SERVER_DEFAULT, the client’s minimum refresh token rolling interval comes from the global value in the Minimum Interval to Roll Refresh Tokens field on the Authorization Server Settings window.

When set to OVERRIDE_SERVER_DEFAULT, the client’s refresh token rolling interval comes from the value of the refreshTokenRollingInterval parameter.

refreshTokenRollingInterval

An integer that represents the minimum 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 refreshTokenRollingIntervalType parameter is set to OVERRIDE_SERVER_DEFAULT.

Required when the refreshTokenRollingInterval parameter is set to OVERRIDE_SERVER_DEFAULT.

refreshTokenRollingIntervalTimeUnit

Units for the refresh token rolling interval set by the refreshTokenRollingInterval parameter.

Valid values:

  • d (days)

  • h (hours)

  • m (minutes)

The default value is h.

refreshTokenRollingGracePeriod

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.

requirePushedAuthorizationRequests

When set to true the client must use the PAR endpoint /as/par.oauth2 on the AS to initiate authorization flows. When set to false, the client can use the PAR endpoint. The default value is false.

This parameter works in conjunction with the PAR Status setting on the AS. For example:

  • If PAR is Enabled on the AS and this parameter is set to true, then the client must use PAR

  • If PAR is Enabled on the AS but this parameter is set to false, then the client can use PAR

  • If PAR is Required on the AS but this parameter is set to false, then the client must use PAR

  • If PAR is Disabled on the AS and this parameter is set to true, then the client cannot access the AS

Do not set this parameter to true if PAR is disabled on the AS.

For more information about PAR, see Pushed authorization requests endpoint and Configuring authorization server settings.

requireDpop

Specifies whether the client must use the DPoP protocol for authentication.

Valid values are true or false. Default value is false.

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.

OpenID Connect client settings

The following parameters are only applicable when this client supports the OpenID Connect use cases.

idTokenSigningAlgorithm

The JSON Web Signature (JWS) algorithm required for the OIDC 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-512

RSASSA-PSS signing algorithms require a Java 8 or 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 Keys for OAuth and OpenID Connect, respectively.

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

  • RSA-OAEP-256 - RSAES OAEP using SHA-256 and MGF1 with SHA-256

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 or false.

If this parameter is not provided, a value of false is assumed.

If clients are allowed to add sessions to the revocation list, you can enable the Check session revocation status option in the applicable Access Token Management instances for the token validation process to consider whether a session has been added to the revocation list

pairwiseUserType

Set to true to allow this client to use pairwise pseudonymous IDs. This parameter is set to false by default.

sectorIdentifierUri

Specify one HTTPS URL only. This parameter is applicable only if pairwiseUserType is set to true.

If #the Track User Sessions for Logout check box is selected in the [.wintitle]#System → OAuth Settings → Authorization Server Settings window, you can provide three additional parameters to enable asynchronous front-channel logout for this client.

pingAccessLogoutCapable

If set to true, [.ph]##PingFederate sends logout requests through the browser to an OpenID Connect endpoint in PingAccess as part of the logout process.

A valid value is either true or false.

If this parameter is not provided, a value of false is assumed.

logoutUris

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 InErrorResource parameter value, if specified.

postLogoutRedirectUris

URIs to which PingFederate can redirect the user after a logout is performed, if the relying party’s logout request includes the post_logout_redirect_uri parameter, and it matches one of the URIs configured in this field.

Device Authorization Grant client settings

deviceFlowSettingType

This field controls whether to use global device authorization grant settings defined on the System → OAuth Settings → Authorization Server Settings window.

Allowed values are SERVER_DEFAULT and OVERRIDE_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. Learn more in Device authorization endpoint.

For example, if this field is configured with a value of https://www.example.org/welcome, PingFederate returns https://www.example.org/welcome and https://www.example.org/welcome?user_code=<activationcode> as the verification URIs. After processing the device authorization response, which includes the verification URIs, the device presents one of them to the user. The user is expected to browse to the presented verification URI on a second device.

The target web server must redirect the browser to PingFederate at its user authorization endpoint. For more information, see User authorization endpoint. Moreover, it must also preserve the user_code parameter value, if provided.

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:

  • https://www.example.org/welcome to https://www.example.com/as/user_authz.oauth2

  • https://www.example.org/welcome?user_code=<activationcode> to https://www.example.com/as/user_authz.oauth2?user_code=<activationcode>

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 that the client supports. 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 client-initiated backchannel authentication (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

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 slow_down error message to the client.

A valid value ranges from 1 to 3600.

If the CIBA grant type is enabled, this parameter is required; no value is assumed.

cibaPolicyId

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 → CIBA Request Policies window.

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 or false.

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.

cibaRequireSignedRequests

Determines 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 [.ph]a signed JWT whose claims represent the request parameters of the authorization request. The OIDC specification calls this JWT a request object.

A valid value is either true or false.

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.

cibaRequestObjectSigningAlgorithm

The signing algorithm that the client must use to sign its request objects for transmission of request parameters.

PingFederate accepts the following values:

  • RS256 - RSA using SHA-256

  • RS384 - RSA using SHA-384

  • RS512 - RSA using SHA-512

  • 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

  • PS256 - RSASSA-PSS using SHA-256

  • PS384 - RSASSA-PSS using SHA-384

  • PS512 - RSASSA-PSS using SHA-512

    RSASSA-PSS signing algorithms require a Java 8 or 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 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.

Token introspection settings

introspectionSigningAlgorithm

The JWS algorithm used to sign token introspection responses.

This parameter is optional.

PingFederate accepts the following 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-512

Default value is RS256.

introspectionEncryptionAlgorithm

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:

  • 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

  • RSA-OAEP-256 - RSAES OAEP using SHA-256 and MGF1 with SHA-256

For asymmetric algorithms, a JWKS or the HTTPS URL of a JWKS endpoint is required.

For symmetric algorithms, the reversible secret is required.

introspectionContentEncryptionAlgorithm

The JWE content-encryption algorithm for token introspection responses.

This parameter’s value must be set if the introspectionEncryptionAlgorithm parameter is set.

PingFederate accepts the following 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

JWT secured authorization response mode (JARM) settings

requireJwtSecuredAuthorizationResponseMode

When enabled, the client must use JARM. The client’s authorization requests must include one of the following authorization response mode values:

  • jwt:

    • query JWT response in the case of the authorization code grant

    • fragment JWT response in the case of the implicit grant

  • query.jwt:

    • JWT response in the case of the authorization code grant

    • Failure in the case of the implicit grant unless the response is an encrypted JWT based on the client settings

  • fragment.jwt: fragment JWT response

  • form_post.jwt: auto form-post JWT response

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 true or false. The default value is false.

authorizationResponseSigningAlgorithm

The JWS algorithm that PingFederate uses to sign JARM authorization responses.

This parameter is optional.

PingFederate accepts the following 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-512

Default value is RS256.

authorizationResponseEncryptionAlgorithm

The JWE encryption algorithm used to encrypt the content-encryption key of JARM authorization responses.

This parameter is optional.

PingFederate accepts the following 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

  • RSA-OAEP-256 - RSAES OAEP using SHA-256 and MGF1 with SHA-256

For asymmetric algorithms, a JWKS or the HTTPS URL of a JWKS endpoint is required.

For symmetric algorithms, the reversible secret is required.

authorizationResponseContentEncryptionAlgorithm

The JWE content-encryption algorithm for JARM authorization responses.

This parameter’s value must be set if the authorizationResponseEncryptionAlgorithm parameter is set.

This parameter’s value must be null if the authorizationResponseEncryptionAlgorithm parameter is not set.

PingFederate accepts the following values:

  • AES_128_CBC_HMAC_SHA_256

  • AES_192_CBC_HMAC_SHA_384

  • AES_256_CBC_HMAC_SHA_512

  • AES_128_GCM

  • AES_192_GCM

  • AES_256_GCM

Extended properties

extendedParameters

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, ContactName, and multiple values for a multivalued client metadata field, ContactNumbers.

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.

+ A valid value is either true or false.

If this parameter is not provided, a value of false is assumed.

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 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 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.

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 refreshRolling is 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.