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 several OAuth clients to allow programmatic management of OAuth clients and 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:

  • 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 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 page. 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. Valid values are true or false. The default value is true.

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 doesn’t 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. Refer to the grantTypes parameter.

    • This client signs its ID tokens using an HMAC signing algorithm. Refer to the idTokenSigningAlgorithm parameter.

    • This client can access the Session Revocation API endpoint. Refer to 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. This value is recommended for client applications where security policies prohibit storing passwords.

    This authentication method requires the clientCertIssuerDn and clientCertSubjectDn parameters.

    If you select mutual SSL/TLS authentication, you must configure a secondary PingFederate HTTPS port. You can find more information in the description of the pf.secondary.https.port property in the table in Configuring PingFederate properties.

  • Set to PRIVATE_KEY_JWT if the client authenticates through the private_key_jwt client authentication method as defined in Client Authentication in the OpenID Connect (OIDC) specification

  • Set to CLIENT_SECRET_JWT if the client authenticates through the client_secret_jwt client authentication method as defined in Client Authentication in the OIDC specification.

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 page. Alternatively, it might be set to Trust Any to trust all of the issuers found on the Trusted CAs page.

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.

Allowed 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 an hardware security module (HSM) and a static-key configuration for OAuth and OIDC. You can find information on HSM integration and static keys in Supported hardware security modules and Keys for OAuth and OpenID Connect, respectively.

If this parameter isn’t 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 using the private_key_jwt client authentication method to transmit request parameters using signed request objects or to do both.

Valid values are true or false.

The underlying Assertion Replay Prevention Service is cluster-aware. Learn more in 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 a signed JWT whose claims represent the request parameters of the authorization request. The OIDC specification calls this JWT a request object.

Valid values are 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 don’t 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 OIDC specifications, a client must always include in an authorization request the client_id parameter outside of the signed request object.

Learn more about request objects in RFC 9101: JWT Secured Authorization Request (JAR).

If this parameter isn’t provided, the default value of false applies.

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.

Allowed 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 an HSM and a static-key configuration for OAuth and OIDC. You can find information on HSM integration and static keys in Supported hardware security modules and Keys for OAuth and OpenID Connect, respectively.

If this parameter isn’t 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 isn’t configured to use JWTs for authentication or transmission of request parameters.

    This flexibility allows the client to transmit request parameters in signed request objects for some requests and without the use of signed request objects for some other transactions.

  • If the client signs its JWTs using an RSASSA-PSS signing algorithm, PingFederate must be deployed to run in a Java 8 or Java 11 runtime environment or integrated with an HSM and a static-key configuration for OAuth and OIDC.

    Learn more about runtime processing in Authorization endpoint.

  • 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. Refer to the ID Token Key Management Encryption Algorithm setting.

redirectUris

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.

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.

Valid values are true or false.

If this parameter isn’t provided, the default value of false applies.

restrictScopes

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 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 isn’t provided, the default value of false applies.

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 could impact the results of scope evaluation. The default scope, however, is always allowed for and available to all clients. You can find detailed information in 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.

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 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. 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 invalid_scope error message from PingFederate.

If this parameter isn’t 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 is always allowed for and available to all clients. You can find detailed information in the Dynamic scope evaluation and per-client scope management section in Scopes and scope management.

grantTypes

An array of one or more grant types, 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)

Learn more about each grant type in Grant types.

restrictedResponseTypes

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

Allowed values:

  • code

  • code id_token

  • code id_token token

  • code token

  • id_token

  • id_token token

  • token

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 inversely). 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 isn’t required to specify the additional access_token_manager_id, aud, or resource parameters to disambiguate the ATM instance in its token validation requests. When the resource server client doesn’t 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 checkbox is cleared by default.

requireProofKeyForCodeExchange

Applicable when the client is configured to support the authorization_code grant type.

Valid values are true or false.

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 code_challenge parameter in its authorization request. Learn more in 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. Learn more in OAuth grant type parameters.

If this parameter isn’t provided, the default value of false applies.

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 don’t require 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 (default value): Use the global setting.

  • NONE: Grants don’t 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. Learn more in 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.

Valid values are true or false.

A value of true doesn’t override the Minimum Interval to Roll Refresh Tokens value set on the Authorization Server Settings page.

If this parameter isn’t provided, the Roll Refresh Token Values setting configured globally in the System > OAuth Settings > Authorization Server Settings page 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 page.

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

refreshTokenRollingInterval

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 page when the refreshTokenRollingIntervalType parameter is set to OVERRIDE_SERVER_DEFAULT.

Valid values are an integer between 0 - 8760.

Required when the refreshTokenRollingInterval parameter is set to OVERRIDE_SERVER_DEFAULT.

refreshTokenRollingIntervalTimeUnit

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

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

When a new refresh token is issued, it’s the only valid token and it invalidates the previous token.

requirePushedAuthorizationRequests

When set to true the client must use the pushed authorization requests (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, the client must use PAR.

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

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

  • If PAR is Disabled on the AS and this parameter is set to true, the client can’t access the AS.

Don’t set this parameter to true if PAR is disabled on the AS.

Learn more about PAR in Pushed authorization requests endpoint and Configuring authorization server settings.

requireDpop

Specifies whether the client must use the OAuth 2.0 Demonstrating Proof of Possession (DPoP) protocol for authentication.

Valid values are true or false. The default value is false.

The protocol is specified in OAuth 2.0 Demonstrating Proof of Possesion (DPoP)

The Authorization Server Settings page includes settings for determining DPoP behavior. Learn more in Configuring authorization server settings.

OIDC client settings

The following parameters are only applicable when this client supports the OIDC 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 an HSM and a static-key configuration for OAuth and OIDC. You can find more detailed information about HSM integration and static keys in Supported hardware security modules and Keys for OAuth and OpenID Connect, respectively.

If static keys for OAuth and OIDC 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

  • A128GCM: AES-GCM-128

  • A192GCM: AES-GCM-192

  • A256GCM: AES-GCM-256

userInfoResponseSigningAlgorithm

The algorithm used to sign a JWT returned in a response from the UserInfo endpoint.

Allowed values:

  • 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

userInfoResponseEncryptionAlgorithm

The algorithm used to the encrypt a JWT returned in a response from the UserInfo endpoint.

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

userInfoResponseContentEncryptionAlgorithm

The algorithm used to encrypt the content of a response returned from the UserInfo endpoint.

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

  • A128GCM: AES-GCM-128

  • A192GCM: AES-GCM-192

  • A256GCM: AES-GCM-256

policyGroupId

The desired OIDC policy.

grantAccessSessionRevocationApi

Set to true to allow this client to access the Session Revocation API for back-channel session query and revocation.

Valid values are true or false.

If this parameter isn’t provided, the default value of false applies.

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 checkbox is selected in the System > OAuth Settings > Authorization Server Settings page, you can provide the following three additional parameters to enable asynchronous front-channel logout for this client.

pingAccessLogoutCapable

If set to true, PingFederate sends logout requests through the browser to an OIDC endpoint in PingAccess as part of the logout process.

Valid values are true or false.

If this parameter isn’t provided, the default value of false applies.

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

Controls whether to use global device authorization grant settings defined on the System > OAuth Settings > Authorization Server Settings page.

Valid 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, such as 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. Learn more in User authorization endpoint. 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 CIBA grant type is enabled, this parameter is required. No value is applied.

cibaNotificationEndpoint

The client’s notification endpoint to which PingFederate sends its ping callback 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.

Valid values are an integer from 1 - 3600.

If the CIBA grant type is enabled, this parameter is required. No value is applied.

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, validity of unsigned login hint tokens, and mapping configuration of identity hints.

Provides an existing CIBA policy.

If this parameter isn’t provided and the CIBA grant type is enabled, PingFederate associates the client with the CIBA request policy that has been designated as the default CIBA request policy on the Applications > OAuth > CIBA Request Policies page.

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.

Valid values are true or false.

If this parameter isn’t provided and the CIBA grant type is enabled, user code support isn’t 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 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 isn’t 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.

Allowed 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 an HSM and a static-key configuration for OAuth and OIDC. Learn more about HSM integration and static keys in Supported hardware security modules and Keys for OAuth and OpenID Connect, respectively.

If this parameter isn’t 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.

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

The default value is RS256.

introspectionEncryptionAlgorithm

The JSON Web Encryption (JWE) algorithm used to encrypt the content-encryption key of token introspection responses.

This parameter is optional.

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

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.

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

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. Learn more in the JARM specification.

Valid values are true or false. The default value is false.

authorizationResponseSigningAlgorithm

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

This parameter is optional.

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

The default value is RS256.

authorizationResponseEncryptionAlgorithm

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

This parameter is optional.

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

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 isn’t set.

Alllowed 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

Max Malicious Actions properties

lockoutMaxMaliciousActionsType

Allows an administrator to override the Max Malicious Actions configuration set globally in AccountLockingService.

Valid values are:

  • DO_NOT_LOCKOUT

  • SERVER_DEFAULT (Default value)

  • OVERRIDE_SERVER_DEFAULT

To disable malicious actions lockout, set to DO_NOT_LOCKOUT.

lockoutMaxMaliciousActions

An integer that defines the number of malicious actions allowed before PingFederate locks out an OAuth client.

This value overrides the MaxMaliciousActions value on the AccountLockingService in config-store.

Currently, the only malicious action PingFederate tracks is an attempt to revoke an invalid access token or refresh token.

Extended properties

extendedParameters

Provides 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 multi-valued client metadata field, ContactNumbers.

Extended client metadata fields are defined on the System > Server > Extended Properties page.
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 doesn’t exist or isn’t authorized to create a client.

  • 500 – Internal Server Error

    An unknown error has occurred.

PUT

Updates client details for a specified client.

You can’t 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 isn’t provided, the default value of false applies.

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 doesn’t exist or isn’t 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 isn’t returned if the AS global setting is set for a client (default).

  • 400 – Failed To Retrieve Clients

    The response contains details as to why clients could not be retrieved.

  • 401 – Invalid Credentials

    The user doesn’t exist or isn’t 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 isn’t 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 doesn’t exist or isn’t 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 doesn’t exist or isn’t 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 aren’t 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.