PingFederate Server

Configuring OAuth clients

Use the Client page to control the usage and behavior of the applications requesting access to protected resources through the PingFederate OAuth authorization server (OAuth AS).

Steps

  1. Go to Applications > OAuth > Clients.

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

    The following table describes each field on the Client page:

    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 that 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 doesn’t 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. 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 can access the Session Revocation API. Refer to the Allow Access to Session Revocation API checkbox.

    • This client can access the Session Management API. Refer to the Allow Access to Session Management API checkbox.
    Client Secret

    Select this option for HTTP Basic authentication.

    • To create a strong, random alphanumeric string or manually enter a secret, click Generate Secret.

    • To modify an existing secret, select the Change Secret checkbox, then click Generate Secret to create a strong random alphanumeric string or manually enter a secret.

    Client Secret Retention Period

    Select this option to set the number of minutes for which PingFederate retains a client secret after it is replaced. The retention period enables application teams to 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 equates to a 1-month retention period.

    Use one of the following options:

    • Select Use Global Setting, which is configured on the Authorization Server Settings page.

    • Override the global setting by entering an integer in the field.

      The default is to use the global setting. Learn more about configuring the global setting in the "Client Secret Retention Period" section of 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 in the Issuer list.

      These are CA certificates imported into PingFederate. You can review them on the Security > Certificate & Key Management > Trusted CAs page. 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 using this option, you must configure a secondary PingFederate HTTPS port. Refer to the description for the pf.secondary.https.port property in the table in 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 (OIDC) (OIDC) specification.

    When authenticating an OAuth client that uses the private key JWT authentication scheme, PingFederate validates that the issuer and subject claims in the JWT have the same value.

    The following administrative API endpoint exposes the validation on/off switch:

    https://{{pf_base_host_port}}/pf-admin-api/v1/configStore/oauth-credentials-validator/issuerMustBeEqualToClientId

    To disable validation, send an HTTP POST request with the following body to the endpoint:

    {
 "id": "issuerMustBeEqualToClientId",
 "stringValue": "false",
 "type":"STRING"
}
    Client Secret JWT

    Select this option for the client_secret_jwt client authentication method as defined in Client Authentication in the OpenID Connect (OIDC) specification.

    Replay Prevention

    Select the this checkbox if PingFederate should mandate a unique signed JSON Web Token (JWT) from the client for each request when the client is configured to authenticate with the private_key_jwt or client_secret_jwt client authentication method to transmit request parameters using in signed request objects, or to do both.

    This checkbox is cleared by default.

    The underlying Assertion Replay Prevention Service is cluster-aware. Learn more in Assertion Replay Prevention Service.
    Signing Algorithm

    In the Signing Algorithm list, select the algorithm that the client must use to sign the JWTs for client authentication.

    The following only applies if your client authentication method is private_key_jwt.

    If PingFederate is deployed to run in a Java 8 or Java 11 runtime environment or is integrated with an hardware Security Module (HSM) and configured to use static keys for OAuth and OIDC, additional RSASSA-PSS signing algorithms are available for selection. Learn more about HSM integration and static keys in Supported hardware security modules and Keys for OAuth and OpenID Connect, respectively.

    PingFederate also optionally allows defining symmetric key algorithms.

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

    Require Pushed Authorization Requests

    When selected, the client must use the Pushed Authorization Request (PAR) endpoint /as/par.oauth2 on the AS to initiate authorization flows. When not selected, 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 cannot access the AS.

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

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

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

    This checkbox is cleared by default.

    Require Signed Request

    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.

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

    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 might 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 an HSM and configured to use static keys for OAuth and OIDC, additional RSASSA-PSS signing algorithms become available for selection. You can find information on HSM integration and static keys in Supported hardware security modules and

    The Allow Any default selection 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 or client_secret_jwt client authentication method to transmit request parameters in signed request objects or to transmit CIBA request parameters in signed request objects, only one of the previous values is required for PingFederate to verify the authenticity of the JWTs.

      Either value can be defined even if the client is not configured to use JWTs for authentication or transmission of request parameters. This flexibility allows the client to transmit request parameters in signed request objects for some requests and without the use of signed request objects for some other transactions.

    • 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. You can find information on HSM integration and static keys in 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. Refer to 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 a single URI uses wildcards, 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 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.

    Enable Cookieless Authentication API

    When selected, the client can 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-Auth-Api-State.

    You can configure the name and lifetime of the header in the config-store/authn-api-cookieless-configuration.xml file.

    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 example, you can 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. If the client tries to use such scopes or scope groups, 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. You can find detailed information in the "Dynamic scope evaluation and per-client scope management" section of 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. If the client tries to use such scopes or scope groups, it receives 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.

    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. You can find detailed information in the Dynamic scope evaluation and per-client scope management section of Scopes and scope management.

    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 checkbox, then select the checkbox beside one or more of the supported authorization detail types you want to accept from the client.

    By default, the Allow Authorization Details checkbox is cleared and the page hides the supported types.

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

    Learn more about each grant type in Grant types.

    Require Offline_Access Scope to Issue Refresh Tokens

    Select to require the authorization server to issue refresh tokens when the offline_access scope is requested.

    Offline_Access Requires Consent Prompt

    Select to require the prompt parameter value to be set to consent when the offline_access scope is requested.

    Available only if Require Offline_Access Scope to Issue Refresh Tokens is selected.

    Restrict Response Types

    Select this checkbox 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

    Learn more about these response types in Definitions of Multiple-Valued Response Type Combinations.

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

    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 checkbox is selected, the Validate Against All Eligible Access Token Managers checkbox is hidden.

    This checkbox is cleared 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, aud, or resource 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 cleared 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. 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.

    This checkbox is cleared 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-grained 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

    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. Learn more in 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 checkbox is selected, PingFederate requests consent from the user only once. The user isn’t asked for authorization on subsequent requests until the access grant is revoked.

    When the Authorization Code checkbox 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 page.

    • Don’t Roll

    Refresh Token Rolling Interval

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

    Select one of the following options:

    • Use Global Setting (default)

    • A custom value in hours, minutes, or seconds

      • For Hours, enter an integer between 0 - 8760

      • For Minutes, enter an integer between 0 - 525600

      • For Seconds, enter an integer between 0 - 31536000

    Refresh Token Rolling Grace Period (seconds)

    The amount of time in seconds that a rolled refresh token is still valid if 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, you should set 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.

    OIDC
    ID Token Signing Algorithm

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

    If PingFederate is deployed to run in a Java 8 or Java 11 runtime environment, or 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 and static keys in Supported hardware security modules and Keys for OAuth and OpenID Connect.

    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. Learn more in 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 in the ID Token Key Management Encryption Algorithm list.

    UserInfo Response Signing Algorithm

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

    UserInfo Response Key Management Encryption Algorithm

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

    UserInfo Response Content Encryption Algorithm

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

    Policy

    Select a specific OpenID Connect policy in the list.

    Use Pairwise Identifier

    When selected, the use of pairwise pseudonymous identifiers (PPIDs) is enabled for open banking. This checkbox is cleared by default.

    Sector Identifier URI

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

    If the Track User Sessions for Logout checkbox is selected in System > Server > 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 URI field

    • Post-Logout Redirect URIs field
    Logout Mode

    Select one of the following options:

    • None: When selected, PingFederate doesn’t send logout requests or tokens to the client.

    • OIDC Front-Channel: When selected, PingFederate sends logout requests, using the browser, to replying parties' Front-Channel Logout URI. This feature conforms to the OpenID Connect Front-Channel Logout specification.

    • Ping Front-Channel: When selected, PingFederate sends logout requests, using the browser, to PingAccess and additional requests to other relying parties.

    • OIDC Back-Channel: When selected, PingFederate sends a logout token to the client’s Back-Channel Logout URI. This feature conforms to the OpenID Connect Back-Channel Logout specification.

    PingAccess Logout Capable

    When selected, PingFederate sends logout requests through the browser to an OIDC endpoint in PingAccess as part of the logout process. Learn more in OpenID Connect endpoints in the PingAccess documentation. This checkbox is cleared by default.

    Front-Channel Logout URIs

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

    Back-Channel Logout URI

    When the Logout Mode is set to OIDC Back-Channel, PingFederate sends a logout token to the client’s Back-Channel Logout URI.

    Post-Logout Redirect URIs

    URIs to which the OpenID Provider (OP) can redirect the end-user’s user agent after a logout is performed, if the relying party (RP) initiated logout request includes the post_logout_redirect_uri parameter and it matches one the URIs configured in this field.

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

    Session API Endpoints
    Allow Access to Session Revocation API

    Select this checkbox to allow this client application to add sessions to or query the revocation status through the Back-Channel Session Revocation API endpoint at /pf-ws/rest/sessionMgmt/revokedSris. Authentication is required. This checkbox is cleared 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. Learn more in 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. 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 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 checkbox.This checkbox is cleared by default.

    CIBA

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

    Token Delivery Method

    The token delivery method that the client supports. PingFederate supports poll and ping.

    • 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

    The client’s notification endpoint to which PingFederate sends its ping callback messages.

    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.

    Valid values are an integer between 1 - 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, validity of unsigned login hint tokens, and 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 checkbox is cleared 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 a signed JWT whose claims represent the request parameters of the authorization request. The OpenID Connect (OIDC) specification calls this JWT a request object.

    This checkbox is cleared 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.

    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. Learn more about HSM integration and static keys in Supported hardware security modules and Keys for OAuth and OpenID Connect.

    The Allow Any default selection allows the client to use any of the signing algorithms in 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.

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

    Demonstrating Proof of Possession (DPoP)

    Select the Require DPop checkbox if the client must use the DPoP protocol for authentication. The protocol is specified in OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP). DPoP is not required by default.

    The Authorization Server Settings page provides Demonstrating Proof-of-Possession (DPoP) settings for configuring DPoP behavior.

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

    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. Learn more in Extended properties.

  4. Click Save.