PingFederate Server

Managing client configuration defaults

On the Client Configuration Defaults tab, specify the default settings that are proprietary to PingFederate for clients created with the OAuth 2.0 Dynamic Client Registration protocol.

About this task

Although these settings are shared among all clients created through dynamic client registration, they can be overridden by client registration policies enforced during dynamic client registration. You can also modify the client configuration using the administrative console, the administrative API, or the OAuth Client Management Service after the client has been created.

Steps

  1. Go to System → OAuth Settings → Client Settings and click Client Configuration Defaults.

  2. Optional: Modify the default values as needed.

    The following table describes each field.

    Field Description

    Private Key JWT - Replay Prevention

    This field determines whether PingFederate mandates [.ph]a unique signed JWT from the client for each request when the client is configured to authenticate using the private_key_jwt client authentication method, to transmit request parameters using signed request objects, or to do both.

    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.

    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 authorization request parameters. The OpenID Connect (OIDC) specification calls this JWT a request object.

    This check box is not selected by default.

    Require JWT Secured Authorization Response Mode (JARM)

    When selected, the client must use JARM. The client’s authorization requests must include one of the following authorization response mode values:

    • jwt:

      • query JWT response in the case of the authorization code grant

      • fragment JWT response in the case of the implicit grant

    • query.jwt:

      • JWT response in the case of the authorization code grant

      • Failure in the case of the implicit grant unless the response is an encrypted JWT based on the client settings

    • fragment.jwt: fragment JWT response

    • form_post.jwt: auto form-post JWT response

    JARM is a mechanism to enhance the security of the standard authorization response. It adds support for signing and encryption, sender authentication, and audience restriction. It also offers protection from replay, credential leakage, and mix-up attacks. JARM can be combined with any response type. 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 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.

    Default Access Token Manager

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

    Restrict to Default Access Token Manager

    If selected, the client can use only the Default Access Token Manager, even if other ATMs include the client in their access control lists.

    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.

    Client Authentication Certificate Issuer DN

    Select a trusted CA from the list. You can review CA certificates imported into PingFederate them in Security → Certificate & Key Management → Trusted CAs. You can select Trust Any to trust all the issuers found in the list.

    The default selection is None (Client TLS Certificate Authentication Disabled), which does not allow developers to submit client registrations with a token_endpoint_auth_method parameter value of tls_client_auth.

    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, minutes, or seconds.

      • For Hours, enter an integer between 0 and 8760

      • For Minutes, enter an integer between 0 and 525600

      • For Seconds, enter an integer between 0 and 31536000

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

    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.

    While all settings on this window can be overridden by client registration policies enforced during the registration, ID Token Signing Algorithm is the only default setting that can also be overridden by including a different id_token_signed_response_alg client metadata value in the client registration.

    For a list of supported signing algorithm, see the id_token_signing_alg_values_supported parameter values returned by the PingFederate OpenID Provider configuration endpoint at /.well-known/openid-configuration.
    Policy

    Select a specific OpenID Connect policy from the list.

    Device Authorization

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

    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:

    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.

    Require Proof Key for Code Exchange (PKCE)

    This field is only applicable 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.

    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.

    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 authorization request parameters. The OIDC specification calls this JWT a request object.

    This check box is not selected by default.

    Note that if client-initiated back channel authentication (CIBA) signed requests are required, the dynamic client registration must include either the JWKS URL or the actual JWKS.

    Token Exchange

    This field determines which token exchange processor policy PingFederate uses when the OAuth server receives an OAuth token exchange request from the client. If you select Default, PingFederate uses the token exchange processor policy that was set as the default on the Token Exchange Processor Policy Management tab, under Applications → Token Exchange → Processor Policies.

    For more information, see OAuth token exchange.

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

    You must select the Retain Client Secret check box on the Dynamic Client Registration page for this option to appear.

    Malicious Actions Count for Lockout

    The maximum number of malicious actions allowed before PingFederate locks out the client.

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

    Use Global Setting

    Use the default global setting as defined by the MaxMaliciousActions parameter in com.pingidentity.common.security.AccountLockingService.xml.

    Do Not Lockout

    Disables the lockout function for malicious attempts to revoke an invalid token.

    Custom count field

    Enter an integer to specify the number of malicious actions to allow before PingFederate locks out the client.