Configuring OAuth clients

On the Clients page, configure the behavior of applications (clients) requesting access to protected resources through the PingFederate OAuth authorization server (OAuth AS).

Steps

In the PingFederate admin console, go to Applications > OAuth > Clients.
Click Add Client.

All fields are optional unless otherwise noted.

Configuration

(Required) In the Client ID field, enter a unique identifier for the client.

This identifier is included with every request that the client makes to the resource server.
(Required) In the Name field, enter a descriptive name for this client.

This name appears when the user is prompted for authorization.

To localize the displayed name, enter a unique alias in the Name field. Then use the same alias in language resource files. Learn more in Localizing messages for end users.
In the Description field, enter a description of what the client application does.

This description appears when the user is prompted for authorization.

To localize the description, enter a unique alias in the Description field. Then use the same alias in language resource files. Learn more in Localizing messages for end users.

Select one or more of the following Client Authentication methods, and configure the fields for each selected method:

Authentication Method Details

None

Select this option if your use case doesn’t require client authentication. This is the default selection.

If any of the following are true of this client, you can’t use None:

This client uses the Client Credentials grant type. Refer to the Allowed Grant Types checkboxes.
This client signs its ID tokens using an HMAC signing algorithm. Refer to the ID Token Signing Algorithm field.
This client is allowed to access the Session Revocation API. Refer to the Allow Access to Session Revocation API checkbox.
This client is allowed to access the Session Management API. Refer to the Allow Access to Session Management API checkbox.
None can’t be combined with any other client authentication method.

Client Secret

Select this option for HTTP Basic authentication. Choose how your secret is managed:

Click Internally Managed and enter your secret in the Client Secret field.
Click Secret Manager and enter your Client Secret Reference in the field. Learn more in Secret managers.

Client Secret JWT

Select Replay Prevention for PingFederate to mandate a unique signed JSON Web Token (JWT) from the client for each request, to transmit request parameters used in signed request object, or to do both.

The underlying Assertion Replay Prevention Service is cluster-aware. Learn more in Assertion Replay Prevention Service.
In the Signing Algorithm list, select the algorithm that the client must use to sign the JWTs for client authentication. The default selection is Allow Any, which enables the client to use any of the signing algorithms in the list.

Private Key JWT

Select Replay Prevention for PingFederate to mandate a unique signed JWT from the client for each request, to transmit request parameters used in signed request objects, or to do both.

The underlying Assertion Replay Prevention Service is cluster-aware. Learn more in Assertion Replay Prevention Service.
In the Signing Algorithm list, select the algorithm that the client must use to sign the JWTs for client authentication. The default selection is Allow Any, which enables the client to use any of the signing algorithms in the list.

The aud claims of outbound Private Key JWT authorizations are set to the issuer identifier of the PingFederate AS. The complies with RFC 7523 specfication.

Client TLS Certificate

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

In the Issuer list, select a trusted certificate authority. Learn more in Manage trusted certificate authorities.
In the Subject DN field, enter the client-certificate subject DN.
Alternatively, you can extract the subject DN by uploading a certificate file and clicking Extract.

If you select Client TLS Certificate, you must configure a secondary PingFederate HTTPS port. Refer to the description for the pf.secondary.https.port property in Configuring PingFederate properties.

In the Client Secret field, enter a secret, or click Generate Secret.
For Client Secret Retention Period (Minutes), select either Use Global Settings or enter an integer in the field.

Learn more about global client secret settings in Configuring authorization server settings.
Click Revoke Previous Secret(s) to revoke any previous secrets that are no longer in use prior to the end of their retention period. This button is available only when previous secrets exist.

Click Add Redirect URI and enter a fully qualified URL.

Wildcards are allowed, but you should make the URL as restrictive as possible. For example, https://www.example.com/OAuthClientApp/callback.jsp.

If you add more than one URI, or a single URI uses wildcards, the authorization code grant and token requests must contain a specific matching redirect_uri parameter when contacting the authorization endpoint (/as/authorization.oauth2) and token endpoint (/as/token.oauth2).

In the Logo URL field, enter the location of the logo used on user-facing OAuth grant and authorization and revocation pages.

The recommended size is 72 x 72 pixels.

Choose a JSON Web Key Set (JWKS) method:

In the JWKS URL field, enter the location of the JWKS.

In the JWKS field, paste the JWKS from the application.

The JWKS is a JSON object containing a keys array. This array holds one or more JWKs. For a single key, the JSON structure still includes the keys array.
If the client is configured to use the private_key_jwt or client_secret_jwt authentication method to transmit 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. Learn more about runtime processing in Authorization endpoint.
If the client signs its JWTs using an RSASSA-PSS signing algorithm, PingFederate must be integrated with an HSM and a static-key configuration for OAuth and OIDC. Learn more about HSM integration in Supported hardware security modules. Learn more about static keys in Keys for OAuth and OpenID Connect.
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.

In the Tags list, select tags to apply to this client.

Learn more in Tag Management.
Select the Grant Type that this client can use.

Learn more in Grant types.

OAuth and OpenID Connect Scope Settings

Select Restrict Response Types to limit the response_type parameter values that this client can use.

If selected you must select at least one allowable response_type parameter value. Learn more about these response types in Definitions of Multiple-Valued Type Combinations in the OpenID Connect specifications.
Select Restrict Common Scopes to limit this client to using selected common scopes and scope groups. The default behavior allows all common scopes and scope groups.
1. With Restrict Common Scopes selected, click the Selected link to manage the scopes and scope groups for this client to use. Learn more about creating scopes and scope groups in Defining scopes.
Select Allow Exclusive Scopes to allow this client to use selected exclusive scopes and scope groups.
1. With Allow Exclusive Scopes selected, click the Selected link to manage the exclusive scopes and scope groups for the client to use. Learn more about creating exclusive scopes and scope groups in Defining scopes.
For Require Scope Offline_Access to Issue Refresh Tokens, select whether to require the authorization server to issue refresh tokens when the offline_access scope is requested.

Click one of the following:
- Use Global Setting is the default. You can configure the global setting on the Authorization Server Settings page.
- Yes requires the authorization server to issue refresh tokens and opens the Offline_Access Require Consent Prompt dialog.
- No doesn’t require the authorization server to issue refresh tokens.
If you clicked Yes, select whether to require the prompt parameter value to be set to consent when the offline_access scope is requested.
- Use Global Setting is the default. You can configure the global setting on the Authorization Server Settings page.
- Yes requires the consent prompt.
- No doesn’t require the consent prompt.
Select Support Authorization Details to accept rich authorization details from this client. Learn more in OAuth rich authorization requests.
1. With Support Authorization Details selected, select the specific authorization details to allow.

Select algorithms for any OpenID Connect operations:

Algorithm

Description

ID Token Signing Algorithm

Used to sign ID tokens

If PingFederate is integrated with an HSM and configured to use static keys for OAuth and OIDC, additional RSASSA-PSS signing algorithms become available for selection. Learn more about HSM integration in Supported hardware security modules. Learn more about static keys in Keys for OAuth and OpenID Connect.

If static the keys for OAuth and OIDC are enabled, elliptic-curve (EC) algorithms that haven’t been configured with an active static key are hidden.

Changes made in the static-key configuration could affect runtime transactions and require additional changes. Learn more in Keys for OAuth and OpenID Connect.

ID Token Key Management Encryption 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 is 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

Used to perform authenticated encryption on the plain text payload of the token.

Required if an algorithm is selected in the ID Token Key Management Encryption Algorithm list.

UserInfo Response Signing Algorithm

Used to sign a JWT returned in a response from the UserInfo endpoint.

UserInfo Response Key Management Encryption Algorithm

Used to encrypt a JWT returned in a response from the UserInfo endpoint.

UserInfo Response Content Encryption Algorithm

Used to encrypt the content of a response returned from the UserInfo endpoint.

In the OpenID Connect Policy list, select a policy to apply to this client.

Learn more in Configuring OpenID Connect policies.

Select Pairwise Identifier to enable the use of pairwise pseudonymous identifiers (PPIDs) for open banking. This checkbox is cleared by default.

If you enabled Pairwise Identifier, you can enter an HTTPS URI in the Sector Identifier URI field.

If the Track User Sessions for Logout checkbox is enabled in Authorization Server Settings, the Client page also displays the following:

Logout Mode list
PingAccess Logout Capable checkbox
Front-Channel Logout URIs field
Back-Channel Logout URIs field
Post-Logout Redirect URIs field

Learn more in Configuring authorization server settings.

Select Require Pushed Authorization Requests (PAR) to require the client to use the Pushed Authorization Requests (PAR) endpoint /as/par.oauth2 on the AS to initiate authorization flows. When cleared, the client can use the PAR endpoint. This checkbox is cleared 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, the client must use PAR.
- If PAR is Enabled on the AS but not required on the client, the client can use PAR.
- If PAR is Required on the AS but not required on the client, the client must use PAR.
- If PAR is Disabled on the AS and required on the client, the client can’t access the AS.
  
  Don’t select this checkbox if PAR is disabled on the AS.
  
  Learn more about PAR in Pushed authorization requests endpoint and Configuring authorization server settings.
Select Require JWT Secured Authorization Response Mode to require the client to 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 for authorization code grant
  - Fragment JWT response for implicit grant
- query.jwt:
  - JWT response for authorization code grant
  - Failure for 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 a response type. Learn more in the JARM specification.
  
  This setting works in conjunction with the other JWT Secured Authorization Response Mode settings in the client configuration.
  
  This checkbox is cleared by default.

Select Require Signed Requests to require the client to 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 authorization request parameters. The OIDC specification calls this JWT a request object.

If a client includes in an authorization request 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 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.

From the Request Object Signing Algorithm list, select an algorithm to use for signing request objects for transmission of request parameters.

This is applicable only when the client might send its authorization requests using request objects.

If PingFederate is integrated with an HSM and configured to use static keys for OAuth and OIDC, additional RSASSA-PSS signing algorithms become available for selection. Learn more about HSM integration in Supported hardware security modules. Learn more about static keys in Keys for OAuth and OpenID Connect.

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

DPoP Settings

Select Require Demonstrate Proof-of-Possession (DPoP) to require the client to use the DPoP protocol. DPoP isn’t required by default.

Require Demonstrate Proof-of-Possession (DPoP) is configured only at the client level. The following DPoP settings can use the global values configured in Configuring authorization server settings or be configured for each client.

Learn more in the DPoP specifications.
For Require DPoP Nonce, click one of the following:
- Use Global Setting is the default.
- Yes requires a nonce in the DPoP JWT.
- No doesn’t require a nonce in the DPoP JWT.
For DPoP JWT Lifetime (Seconds), click Use Global Setting or enter the lifetime of the DPoP JWT in seconds. Valid values are 1 to 3600.
For Enforce DPoP JWT Replay Prevention, click one of the following:
- Use Global Setting is the default.
- Yes requires a unique signed DPoP JWT for each request.
- No doesn’t require a unique signed DPoP JWT for each request.
  
  The underlying Assertion Replay Prevention Service is cluster-aware. Learn more in Assertion Replay Prevention Service.

OAuth Token Manager, Grant, and Session Settings

In the Default Access Token Manager list, select an access token manager.

Learn more in Configuring an access token management instance.
Select Restrict to Selected ATM to restrict this client to using only the selected access token manager.
Select Validate Using All Eligible ATMs to allow this client to use any available access token manager. This option isn’t available if Restrict to Selected ATM is selected.

For Persistent Grants Max Lifetime, choose one of the following to define the lifetime of persistent grants:

Use Global Setting: You can configure the global setting on the Authorization Server Settings page.
Grants Do Not Expire

In the field, enter an integer and select either Days, Hours, or Minutes.

You can override this setting per grant-mapping configuration by using 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-grained control, you can configure them to use the default value.

Grants expire at the max lifetime set when they’re created. When a grant is reused, the max lifetime should be reused as well. New refresh token requests only update the accessGrantUpdated value, and won’t change the grant’s max lifetime.

For Persistent Grants Idle Timeout, choose one of the following to define how long persistent grants can be inactive before timing out:
- Use Global Setting: You can configure the global setting on the Authorization Server Settings page.
- Grants Do Not Expire Due To Inactivity
- In the field, enter an integer and select either Days, Hours, or Minutes.
  
  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 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. Learn more in Transient grants and persistent grants.
For Reuse Existing Persistent Access Grants for Grant Types, click either Use Global Setting or Override Global Setting.
1. If you click Override Global Setting, select the grant types for PingFederate to reuse the existing grant for when the client makes multiple requests for the same user and the same or lesser scope. You can choose one or more of:
  - Implicit
  - Authorization Code
  - Resource Owner Password Credentials
    
    Learn more in Grant types.
For Refresh Token Rolling Policy, select whether PingFederate generates a new refresh token when a new access token is issued.
- Use Global Setting is the default. You can configure the global setting on the Authorization Server Settings page.
- Don’t Roll means each refresh token is used until it becomes invalid, either by manual revocation or another security setting that renders the token invalid.
- Roll means PingFederate generates a new refresh token when a new access token is issued.
For Refresh Token Rolling Interval configure the minimum time that must pass before a new refresh token can be issued. Choose from:
- Use Global Setting is the default. You can configure the global setting on the Authorization Server Settings page.
- Enter an integer in the field and select either Seconds, Minutes, or Hours.
For Refresh Token Rolling Grace Period (Seconds), configure 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 refresh token during a roll.
- Use Global Setting is the default. You can configure the global setting on the Authorization Server Settings page.
- Enter an integer in the field.
For Enable Session API Endpoints, select which endpoints to enable for this client. Learn more about the endpoints in Session Revocation API endpoint and Session Management API by user identifiers.

Other Settings

Select Allow Authentication API Redirectless Mode to enable the client to initiate an authentication API OAuth flow through the authorization endpoint without needing to handle HTTP redirects.

When enabling this feature, consider the following:
- Redirection URLs are optional. But without a redirection URL, browser-based OAuth flows won’t work.
- This flow doesn’t support getting scope consent through the user-facing Request for Approval page. Enabling this feature automatically enables the Bypass Authorization Approval and Restrict Common Scopes features.
- The client must manage the PF cookie and, if persistent authentication sessions are configured, the PF.PERSISTENT cookie.
  
  Learn more in Mobile application authentication through REST APIs.
  1. Select Enable Cookieless Authentication API to enable the client to initiate a redirectless API OAuth flow through the authorization endpoint without HTTP cookies.
    
    Instead of cookies, the flow uses an HTTP header to track the state of the authentication flow. The default header name is X-PF-Authn-Api-State.
    
    You can configure the name and lifetime of the header in the <pingfed-install>/pingfederate/server/default/data/config-store/authn-api-cookieless-configuration.xml file.
Select Bypass Authorization Approval to bypass client authorization to a resource.

When selected, 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 example, use this setting when you want to deploy a trusted application and authenticate end users with an identity provider (IdP) adapter or IdP connection.

This option is automatically enabled when Allow Authentication API Redirectless Mode is selected.
For Malicious Actions Count For Lockout, configure the number of malicious actions allowed before PingFederate locks out the client.

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

Choose one of the following:
- Use Global Setting is the default. You can configure the global setting using the MaxMaliciousActions parameter in the <pingfed-install>/pingfederate/server/default/data/config-store/com.pingidentity.common.security.AccountLockingService.xml file.
- Do Not Lockout disables the lockout function for malicious actions.
- Enter an integer in the field.
When you’re done configuring the client, click Save.