The Client screen provides controls over the usage and behavior of the applications requesting access to protected resources through the PingFederate OAuth AS.

  1. On the Manage Client screen, configure the OAuth client to suit your use cases.
    Refer to the following table for detailed information about each field.
    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.
    Tip:

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

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

    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 field).
    • 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 endpoint (see the Grant Access to Session Revocation API field).
    Client Secret
    Select this option for HTTP Basic authentication.
    • Click Generate Secret to create a strong random alphanumeric string or manually enter a 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 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 > Trusted CAs screen.) Alternatively, you may 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.
    Important:

    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 (openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication).
    • Select the Replay Prevention check box if PingFederate should mandate a unique signed JWT from the client for each request when the client is configured to authenticate via the private_key_jwt client authentication method, to transmit request parameters using in signed request objects, or to do both.

      This check box is not selected by default.

      Note:

      The underlying Assertion Replay Prevention Service is cluster-aware (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 either deployed to run in a Java 11 runtime environment or integrated with a hardware security module (HSM) and configured to use static keys for OAuth and OpenID Connect, additional RSASSA-PSS signing algorithms become available for selection. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)

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

    Require Signed Request Indicates 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 specification calls this JWT a request object.
    Note:

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

    It is also worth noting that if a request parameter is found only outside of the signed request object, such request parameter is dropped and ignored; no error message is returned.

    Tip:

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

    For more information about request object, please refer to the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#RequestObject).

    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 either deployed to run in a Java 11 runtime environment or integrated with a hardware security module (HSM) and configured to use static keys for OAuth and OpenID Connect, additional RSASSA-PSS signing algorithms become available for selection. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)

    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.

    Only one of them is required 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 parameter in signed request objects (or to do any of them) so that PingFederate can verify the authenticity of the JWTs.

    In addition, either may also be defined even if the client is not configured to use JWTs for authentication or transmission of request parameters. This flexibility allows the client to transmit request parameters in signed request objects for some requests and without the use of signed request objects for some other transactions. (For runtime processing, see Authorization endpoint.)

    If the client signs its JWTs using an RSASSA-PSS signing algorithm, PingFederate must be deployed to run in a Java 11 runtime environment or integrated with a hardware security module (HSM) to process the digital signatures. (For more information on HSM integration, see Supported hardware security modules.)

    Finally, if the client is configured to encrypt ID tokens using an asymmetric encryption algorithm (see the ID Token Key Management Encryption Algorithm setting), either the JWKS URL or the actual JWKS must be provided.

    Redirection URIs URIs to which the OAuth AS may redirect the resource owner's user agent after authorization is obtained. At least one redirection URI is required by the authorization code and implicit grant types.

    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

    Important:

    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.)
    Bypass Authorization Approval When selected, resource-owner approval for client access is assumed; 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.

    Use this setting, for example, when you want to deploy a trusted application and authenticate end users via an IdP adapter or IdP connection.

    Restrict Common Scopes This setting controls whether all existing common scopes and scope groups (and those created in the future) or only the select few should be made available to the client.

    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; that is, 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.

    Note:

    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, refer to the Dynamic scope evaluation and per-client scope management section in Scopes and scope management.

    Exclusive Scopes This setting 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; that is, 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.

    Note:

    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, refer to the Dynamic scope evaluation and per-client scope management section in Scopes and scope management.

    Allowed Grant Types Select at least one grant type that this client is allowed to use.
    Available grant types are:
    • 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 (openid.net/specs/oauth-v2-multiple-response-types-1_0.html#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, it is worth noting that 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. The following table provides a summary of their relationship.
    Response type Grant types
    code Authorization Code
    code id_token Authorization Code and Implicit
    code id_token token Authorization Code and Implicit
    code token Authorization Code and Implicit
    id_token Implicit
    id_token token Implicit
    token Implicit
    Default Access Token Manager The default Access Token Management (ATM) instance for this client.
    Validate Against All Eligible Access Token Managers Applicable only to RS clients.

    If selected, this RS client is not required to specify additional parameters (access_token_manager_id or aud) to disambiguate the ATM instance in its token validation requests. When the RS 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) Applicable and shown only when the client is configured to support the authorization code grant type.

    This field 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 (tools.ietf.org/html/rfc7636).

    When enabled, this client must include a one-time string value through the use of the code_challenge parameter in its authorization request (see Authorization endpoint). It must also submit the corresponding code verifier via the code_verifier parameter in its token request when exchanging an authorization code for an access token (see OAuth grant type parameters).

    This check box is not selected by default.

    Persistent Grants Max Lifetime Overrides the Persistent Grant Max Lifetime field value set globally in the OAuth Server > Authorization Server Settings screen.
    Options are:
    • Use Global Setting (the default selection)
    • Grants Do Not Expire
    • A custom value in days, hours, or minutes.
    Note:

    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 on the OAuth Server > Authorization Server Settings screen. Once added, the lifetime of persistent grants can be set 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, they can be configured to use the default value.

    Persistent Grants Idle Timeout Overrides the Persistent Grant Idle Timeout field value set globally in the OAuth Server > Authorization Server Settings screen.
    Options are:
    • Use Global Setting (the default selection)
    • Grants Do Not Timeout Due To Inactivity
    • A custom value in days, hours, or minutes.

    If an idle timeout value is configured, the idle timeout window slides when a persistent grant is updated (see Persistent versus transient grants).

    When an idle timeout value is configured without a maximum lifetime, persistent grants remain valid until they expire due to inactivity, or are revoked or removed. When an idle timeout value is configured with a maximum lifetime, persistent grants remain valid until they expire (due to inactivity or lifetime expiration) or are removed from the grant storage.

    Refresh Token Rolling Policy Overrides the Roll Refresh Token Values setting configured globally in the OAuth Server > Authorization Server Settings screen.
    Options are:
    • Use Global Setting (the default selection)
    • Roll

      Note that this selection does not override the Minimum Interval to Roll Refresh Tokens (Hours) value set on the Authorization Server Settings screen.

    • Don't Roll
    OpenID Connect
    Note:

    These options are displayed only when the OpenID Connect protocol is enabled in System > Protocol Settings > Roles & Protocols screen.

    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 either deployed to run in a Java 11 runtime environment or integrated with a hardware security module (HSM) and configured to use static keys for OAuth and OpenID Connect, additional RSASSA-PSS signing algorithms become available for selection. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)

    Note:

    If static keys for OAuth and OpenID Connect are enabled, EC algorithms that have not been configured with an active static keys are hidden.

    Changes made in the static-key configuration may affect runtime transactions and require additional changes here. For more information, see Managing 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 (Direct Encryption with symmetric key, AES ... Key Wrap. and AES-GCM ... key encryption) and asymmetric algorithms (ECDH-ES, ECDH-ES ... Key Wrap, and RSAES OAEP).
    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.

    Grant 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.
    Note:

    Generally speaking, if clients are allowed to add sessions to the revocation list, consider enabling the Check session revocation status option in the applicable Access Token Management instances so that the token validation process takes into account whether a session has been added to the revocation list. (For more information, see Managing session validation settings.)

    Note:

    If the Track User Sessions for Logout check box is selected in the OAuth Server > Authorization Server Settings screen, there are two additional fields: PingAccess Logout Capable and Logout URIs.

    PingAccess Logout Capable
    When selected, PingFederate sends (via the browser) logout requests to an OpenID Connect endpoint in PingAccess as part of the logout process (see OpenID Connect endpoints in the PingAccess documentation). This check box is not selected by default.
    Logout URIs
    Enter additional endpoints at the relying parties as needed. PingFederate sends (via the browser) requests to these URIs as part of the logout process. Note that the relying parties must return an image in their logout responses; otherwise, PingFederate returns an error message or redirect 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
    This field is shown only when Use pairwise identifier is selected. Optionally, enter one HTTPS URI.
    Device Authorization Grant This field controls whether to use global device authorization grant settings defined on the OAuth Server > Authorization Server Settings screen.

    Applicable and shown only if the Device Authorization Grant grant type is enabled for the client.

    The default selection is Use Global Settings.

    Select Override and configure any of the following settings.

    User Authorization URL
    This field controls whether PingFederate should use a different URL, perhaps for ease of use or branding purposes, when formulating the verification URLs to be included in its device authorization responses (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.
    Important:

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

    For instance, if the base URL of your PingFederate server is https://www.example.com and this field is configured with a value of https://www.example.org/welcome, the target web server must redirect as follows:
    • https://www.example.org/welcome to https://www.example.com/as/user_authz.oauth2
    • https://www.example.org/welcome?user_code=<activationcode> to https://www.example.com/as/user_authz.oauth2?user_code=<activationcode>
    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.
    This field controls whether PingFederate should skip this confirmation step.
    Select the Bypass Activation Code Confirmation check box if you want PingFederate to skip the confirmation step.
    This check box is not selected by default.
    CIBA Applicable and shown only if the CIBA grant type is enabled for the client.
    Token Delivery Method
    The token delivery method supported by the client. 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 call back messages.
    Required and shown only if ping is the configured token delivery method.
    Polling Interval (seconds)
    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
    The CIBA request policy associated with the client.
    PingFederate uses CIBA request policies to determine various aspects of CIBA authentication requests; for example, 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 on the OAuth Server > Request Policies screen.

    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.

    Note that when user code support is enabled, the associated CIBA request policy must also be user code-enabled.

    Require CIBA Signed Requests
    Indicates 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 specification calls this JWT a request object.

    This check box is not selected by default.

    Note that 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 either deployed to run in a Java 11 runtime environment or integrated with a hardware security module (HSM) and configured to use static keys for OAuth and OpenID Connect, additional RSASSA-PSS signing algorithms become available for selection. (For more information on HSM integration and static keys, see Supported hardware security modules and Managing keys for OAuth and OpenID Connect, respectively.)

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

    Token Exchange Applicable and shown only if the Token Exchange grant type is enabled for the client.
    Processor Policy
    Select the token exchange processor policy that PingFederate uses when the OAuth server 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

    If you want to enable or disable the client, click the toggle switch.

  2. Optional: On the Extended Properties screen, add, remove, or update one or more values for any extended properties defined on the System > Extended Properties screen.

    Applicable and shown only if one or more extended properties are defined on the System > Extended Properties screen.

    Extended property values can serve as metadata. They can also help drive authentication requirements. To learn more, see Extended Properties.

  3. Click Save.