Configuring OAuth clients

The Client window provides controls over the usage and behavior of the applications requesting access to protected resources through the PingFederate OAuth authorization server (AS).

Steps

Go to Applications → OAuth → Clients.

Configure a new or existing OAuth client to suit your use cases.

The following table describes each field on the Client window.

Field Description

Client ID

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

Name

(Required)

A descriptive name for the client instance. This name appears when the user is prompted for authorization.

If you want to localize the displayed name, you can enter a unique alias here, then use the same alias in language resource files.

Description

A description of what the client application does. This description appears when the user is prompted for authorization.

If you want to localize the displayed description, you can enter a unique alias here, then use the same alias in language resource files.

Client Authentication

The authentication method that the client uses.

None

Select this option if your use case does not require client authentication. This is the default selection.

A selection other than None is required for any of the following use cases:

This client uses the Client Credentials grant type. See the Allowed Grant Types check boxes.
This client signs its ID tokens using an HMAC signing algorithm. See the ID Token Signing Algorithm field.
This client is allowed to access the Session Revocation API. See the Allow Access to Session Revocation API check box.
This client is allowed to access the Session Management API. See the Allow Access to Session Management API check box.

Client Secret

Select this option for HTTP Basic authentication.

To create a strong, random alphanumeric string or to manually enter a secret, click Generate Secret.
To modify an existing secret, select the Change Secret check box. Then, click Generate Secret to create a strong random alphanumeric string or manually enter a secret.

Client Secret Retention Period

Set the number of minutes that PingFederate retains a client secret after it is replaced. The retention period lets application teams update the client secret in their app without disruption.If the value is 0, PingFederate won’t retain replaced secrets. The maximum value is 43800, which is one month.Use one of these options:

Select Use Global Setting, which is configured on the Authorization Server Settings window
Override the global setting by entering a number in the field

The default is to use the global setting. For information about configuring the global setting, see "Client Secret Retention Period" in Configuring authorization server settings.

Client TLS Certificate

Select this option for mutual TLS certificate-based authentication; recommended for client applications where security policies prohibit storing passwords.

Select a trusted CA from the Issuer list.

These are CA certificates imported into PingFederate. You can review them on the Security → Certificate & Key Management → Trusted CAs window. Alternatively, you can select Trust Any to trust all the issuers found in the list.
Enter the client-certificate subject DN in the Subject DN or extract the subject DN from the certificate if the certificate is stored on an accessible file system.

If choosing this option, you must configure a secondary PingFederate HTTPS port. See the property pf.secondary.https.port in the table under Configuring PingFederate properties.

Private Key JWT

Select this option for the private_key_jwt client authentication method, as defined in Client Authentication in the OpenID Connect specification.

Select the Replay Prevention check box if PingFederate should mandate a unique signed JSON Web Token (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.

This check box is not selected by default.

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

Select from the Signing Algorithm list the algorithm that the client must use to sign the JWTs for client authentication.

If PingFederate is deployed to run in a Java 8 or Java 11 runtime environment, or is integrated with a hardware security module (HSM) and configured to use static keys for OAuth and OpenID Connect (OIDC), additional RSASSA-PSS signing algorithms become available for selection. For more information on HSM integration and static keys, see Supported hardware security modules and Keys for OAuth and OpenID Connect.

The default selection is Allow Any, which allows the client to use any of the signing algorithms from the list.

Require Pushed Authorization Requests

When selected, the client must use the PAR endpoint /as/par.oauth2 on the AS to initiate authorization flows. When not selected, the client can use the PAR endpoint. This check box is not selected by default.

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

If PAR is Enabled on the AS and required on the client, then the client must use PAR
If PAR is Enabled on the AS but not required on the client, then the client can use PAR
If PAR is Required on the AS but not required on the client, then the client must use PAR
If PAR is Disabled on the AS and required on the client, then the client cannot access the AS

Do not select this check box if PAR is disabled on the AS.

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

Require JWT Secured Authorization Response Mode

When selected, the client must use JWT secured authorization response mode (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.

This setting works in conjunction with the other JWT Secured Authorization Response Mode settings on this window.

This check box is cleared by default.

Require Signed Requests

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.

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

Request Object Signing Algorithm

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.

If PingFederate is deployed to run in a Java 8 or Java 11 runtime environment, or is integrated with a hardware security module (HSM) and configured to use static keys for OAuth and OIDC, additional RSASSA-PSS signing algorithms become available for selection. For more information on HSM integration and static keys, see Supported hardware security modules and Keys for OAuth and OpenID Connect.

The default selection is Allow Any, which allows the client to use any of the signing algorithms from the list.

JWKS URL and JWKS

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

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.

Redirection URIs

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.

Enter a fully qualified URL and click Add for each entry required. Wildcards are allowed. However, for security reasons, make the URL as restrictive as possible, for example, https://www.example.com/OAuthClientApp/callback.jsp.

If more than one URI is added or if a single URI uses wildcards, then the authorization code grant and the token requests must contain a specific matching redirect_uriparameter when contacting the authorization endpoint (/as/authorization.oauth2) and token endpoint (/as/token.oauth2).

Logo URL

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.

Allow Authentication API Redirectless Mode

When selected, the client can initiate an authentication API OAuth flow through the authorization endpoint without needing to handle HTTP redirections.

When enabling this feature, consider the following:

Redirection URLs are optional, but without a redirection URL, browser-based OAuth flows will not work.
This flow does not support the user-facing scope consent page, Request for Approval. So, enabling this feature automatically enables the Bypass Authorization Approval feature and Restrict Common Scopes feature.
The client must manage the PF cookie and, if persistent authentication sessions are configured, the PF.PERSISTENT cookie.

For more information, see Mobile application authentication through REST APIs.

Bypass Authorization Approval

When selected, 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.

For instance, use this setting when you want to deploy a trusted application and authenticate end users with an identity provider (IdP) adapter or IdP connection.

Restrict Common Scopes

Controls whether all existing and future common scopes and scope groups should be made available to the client, or only the select few.

When selected, the administrative console displays a list of existing common scopes and scope groups. Choose the common scope and scope groups that are intended for the client. The rest and any common 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.

When cleared, all existing common scopes and scope groups and those created in the future are available to the client. This is the default behavior.

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 section "Dynamic scope evaluation and per-client scope management" in Scopes and scope management.

Exclusive Scopes

Controls whether any exclusive scopes and scope groups should be made available to the client.

When selected, the administrative console displays a list of existing exclusive scopes and scope groups. Choose the exclusive scopes and 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.

When cleared, no exclusive scopes and scope groups are available to the client. This is the default behavior.

Authorization Detail Types

If you configured PingFederate to support rich authorization requests from OAuth clients, and you want it to process authorization details from this client, select the Allow Authorization Details check box. Then select the check box beside one or more of the supported authorization detail types you want to accept from the client.

By default, the Allow Authorization Details check box is cleared and the window hides the supported types.

For more information, see OAuth rich authorization requests.

Allowed Grant Types

The grant types that this client can use.

Select at least one of the following:

Authorization Code
Implicit
Refresh Token
Client Credentials
Device Authorization Grant
CIBA
Token Exchange
Resource Owner Password Credentials
Assertion Grants
Access Token Validation (Client is a Resource Server)

There is no default selection.

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

Restrict Response Types

Select this check box to limit the response_type parameter values that this client can use.

Available response types are:

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.

The Restrict Response Type check box is not selected by default. If selected, you must select at least one allowable response_type parameter value.

Additionally, the Restricted Response Types and Allowed Grant Types settings must be configured in tandem because certain response types require one or more grant types, and vice versa.

Authorization code grant types are compatible with the following response types:

code
code id_token
code id_token token
code token

Implicit grant types are compatible with the following response types:

code id_token
code id_token token
code token
id_token
id_token token
token

Default Access Token Manager

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

Restrict to Default Access Token Manager

If selected, this client can use only the Default Access Token Manager, even if other ATMs include this client in their access control lists. When this check box is selected, the Validate Against All Eligible Access Token Managers check box is hidden.

This check box is not selected by default.

Validate Against All Eligible Access Token Managers

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.

Require Proof Key for Code Exchange (PKCE)

Displayed only when the client is configured to support the authorization code grant type.

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.

This check box is not selected by default.

Persistent Grants Max Lifetime

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

Select one of the following options:

Use Global Setting (default)
Grants Do Not Expire
A custom value in days, hours, or minutes.

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.

Persistent Grants Idle Timeout

Overrides the Persistent Grant Idle Timeout field value set globally in System → OAuth Settings → Authorization Server Settings.

Select one of the following options:

Use Global Setting (default)
Grants Do Not Timeout Due To Inactivity
A custom value in days, hours, or minutes.

include::ROOT:partial$pf_rc_persistentgrantidletimeoutexpinfo.adoc[tags=pf_ph_desc_persistentGrantIdleTimeoutExpInfo] For more information, see Transient grants and persistent grants.

Reuse Existing Persistent Access for Grant Types

Overrides the Reuse Existing Persistent Access Grants for Grant Types setting configured globally in System → OAuth Settings → Authorization Server Settings.

Select one of the following options:

Use Global Setting(default)
Override Global Setting (The admin selects or clears individual grant types as needed.)
- Implicit
- Authorization Code
- Resource Owner Password Credentials

If the Bypass Authorization Approval client setting isn’t enabled (the default), when the Implicit check box is selected, PingFederate requests consent from the user only one time. The user isn’t asked for authorization on subsequent requests until the access grant is revoked.

When the Authorization Code check box is selected, the same is true if the Bypass Authorization for Previously Approved Persistent Grants authorization setting is enabled and the Bypass Authorization Approval client setting is disabled. If the Bypass Authorization Approval client setting is enabled, resource-owner approval for client access is always assumed.

Refresh Token Rolling Policy

Overrides the Roll Refresh Token Values setting configured globally in System → OAuth Settings → Authorization Server Settings.

Select one of the following options:

Use Global Setting (default)
Roll

This value does not override the Minimum Interval to Roll Refresh Tokens value set in the Authorization Server Settings window.
Don’t Roll

Refresh Token Rolling Interval

Overrides the Minimum Interval to Roll Refresh Tokens value set in the Authorization Server Settings window.

Select one of the following options:

Use Global Setting (default)
A custom value in hours. The maximum is 8760 hours (365 days).

Refresh Token Rolling Grace Period (seconds)

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.

Select one of the following options:

Use Global Setting (default)
A custom value in seconds. The maximum is 86400.

For security reasons, we recommend setting the custom value as low as possible.

If specified:

the currently issued refresh tokens must be refreshed once and converted to the new format.
this overrides the Authorization Server Settings default setting.

OpenID Connect

ID Token Signing Algorithm: Select the signing algorithm for the ID tokens from the list. The default algorithm is RSA using SHA-256.

If static keys for OAuth and OpenID Connect are enabled, Elliptic-curve cryptography (EC) algorithms that have not been configured with an active static keys are hidden.

Changes made in the static-key configuration might affect runtime transactions and require additional changes here. For more information, see Keys for OAuth and OpenID Connect.

ID Token Key Management Encryption Algorithm: The algorithm used to encrypt or otherwise determine the value of the content encryption key.PingFederate supports symmetric algorithms, such as Direct Encryption with symmetric key, AES … Key Wrap, and AES-GCM … key encryption, and asymmetric algorithms, such as ECDH-ES, ECDH-ES … Key Wrap, and RSAES OAEP.

If you select a symmetric algorithm, you should provide a Client Secret. The client secret will be used as the symmetric key even if your client doesn’t use the client secret for authentication.

If you select an asymmetric algorithm, you should provide a JWKS or JWKS URL so PingFederate can find the right client key.

ID Token Content Encryption Algorithm

The content encryption algorithm used to perform authenticated encryption on the plain text payload of the token.Required if an algorithm is selected from the ID Token Key Management Encryption Algorithm list.

Policy

Select a specific OpenID Connect policy from the list.

If the Track User Sessions for Logout check box is selected in the Authorization Server Settings window, PingFederate also displays the PingAccess Logout Capable and Logout URIs fields.

PingAccess Logout Capable

When selected, PingFederate sends logout requests through the browser to an OpenID Connect endpoint in PingAccess as part of the logout process. For more information, see OpenID Connect endpoints. This check box is not selected by default.

Logout URIs

Enter additional endpoints at the relying parties as needed. PingFederate sends requests to these URIs through the browser as part of the logout process. 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.

Use pairwise identifier

When selected, the use of pairwise pseudonymous identifiers (PPIDs) is enabled for Open Banking. This check box is not selected by default.

Sector Identifier URI

Displayed only when Use pairwise identifier is selected. Optionally, enter one HTTPS URI.

Session API Endpoints

Allow Access to Session Revocation API: Select this check box to allow this client application to add sessions to or query the revocation status via the Back-Channel Session Revocation API endpoint at /pf-ws/rest/sessionMgmt/revokedSris. Authentication is required. This check box is not selected by default.

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

Allow Access to Session Management API: The session management API lets client applications get information about user sessions, extend sessions, and revoke sessions. For more information, see Session Management API by session identifiers.

Device Authorization Grant

Determines whether to use global device authorization grant settings defined in System → OAuth Settings → Authorization Server Settings.

Displayed only if the Device Authorization Grant grant type is enabled for the client.

The default selection is Use Global Settings.

You can select Override and configure any of the following settings.

User Authorization URL: This field determines whether PingFederate should use a different URL when formulating the verification URLs to be included in its device authorization responses. For more information, see 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. It must also preserve the user_code parameter value, if provided.

For example, if your PingFederate server’s base URL is https://www.example.com and the User Authorization URL value is 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>

This field has no default value.

Pending Authorization Timeout (seconds): The lifetime of an activation code (the user_code parameter value) in seconds.This field has no default value.
Device Polling Interval (seconds): The amount of time in seconds that the device waits between polling requests to the PingFederate token endpoint.This field has no default value.
Bypass Activation Code Confirmation: 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.For PingFederate to skip this confirmation step, select this check box.This check box is not selected by default.

CIBA

Displayed only if the CIBA grant type is enabled for the client.

Token Delivery Method: include::ROOT:partial$pf_rc_tokendeliverymethod.adoc[tags=pf_ph_desc_tokenDeliveryMethod]Select Poll if the client can check for the authorization results at the token endpoint periodically. Select 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.The default selection is Poll.
Notification Endpoint: include::ROOT:partial$pf_rc_notificationendpoint.adoc[tags=pf_ph_desc_notificationEndpoint]Required and displayed only if ping is the configured token delivery method.
Polling Interval (seconds): 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.

The default value is 3.

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

Select an existing CIBA policy. You may also leave the selection of Default to indicate that PingFederate should use the CIBA request policy that has been designated as the default CIBA request policy in Applications → OAuth → CIBA Request Policies.

User Code Support: 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.

This check box is not selected by default.

When user code support is enabled, the associated CIBA request policy must also be user code enabled.

Require CIBA Signed Requests: 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.

This check box is not selected by default.

If CIBA signed requests are required, the client must also be configured with either the JWKS URL or the actual JWKS from the client.

CIBA Request Object Signing Algorithm: The signing algorithm that the client must use to sign its request objects for transmission of request parameters.

The default selection, Allow Any allows the client to use any of the signing algorithms from the list.

Token Exchange

Displayed only if the Token Exchange grant type is enabled.

Select the token exchange processor policy that PingFederate uses when the AS receives an OAuth token exchange request from the client. If you select Default, PingFederate uses the default token exchange processor policy.

For more information, see OAuth token exchange.

Token Introspection

The algorithms that allow for token introspection signing and encryption.

Displayed only when the Access Token Validation (Client is a Resource Server) grant type is enabled.

Token Introspection Signing Algorithm: The JSON Web Signature (JWS) algorithm used to sign the token introspection response. The default value is RS256.
Token Introspection Key Management Encryption Algorithm: The optional JSON Web Encryption (JWE) encryption algorithm used to encrypt the content-encryption key of the token introspection response.
Token Introspection Content Encryption Algorithm: The JWE content-encryption algorithm for the token introspection response. It’s displayed only if a Token Introspection Key Management Encryption Algorithm is selected.

JWT Secured Authorization Response Mode (JARM)

The algorithms that allow for JARM signing and encryption.

Displayed only when the Access Code or Implicit grant type is enabled.

JARM Signing Algorithm: The JWS algorithm used to sign the authorization response. The default value is RS256.
JARM Key Management Encryption Algorithm: The optional JWE algorithm used to encrypt the content-encryption key of the authorization response.
JARM Content Encryption Algorithm: The JWE content-encryption algorithm for the authorization response. It’s displayed only if a JARM Key Management Encryption Algorithm is selected.

To enable or disable the client, click the toggle switch.

On the System tab, add, remove, or update one or more values for any extended properties defined in System → Server → Extended Properties.

Any values defined for these extended properties will be passed to all applicable velocity templates and as a request context parameter in the authentication API.

Extended property values can serve as metadata. They can also help drive authentication requirements. For more information, see Extended properties.
Click Save.

PingFederate Server

Configuring OAuth clients

Steps