Managing client configuration defaults - PingFederate - 10.2

PingFederate Server

bundle
pingfederate-102
ft:publication_title
PingFederate Server
Product_Version_ce
PingFederate 10.2
category
Product
pf-102
pingfederate
ContentType_ce

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.

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.

  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 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. For more information, see Assertion Replay Prevention Service.

    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 OpenID Connect specification calls this JWT a request object.

    This check box is not selected by default.

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

    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 due to 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. 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
    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 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 Keys for OAuth and OpenID Connect.

    Note:

    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.

    Note:

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

    The target web server must redirect the browser to PingFederate at its user authorization endpoint. For more information, see User authorization endpoint. It must also preserve the user_code parameter value, if provided.

    For example, if your PingFederate server's base URL is https://www.example.com and the User Authorization URL value is https://www.example.org/welcome, the target web server must redirect as follows:
    • https://www.example.org/welcome to https://www.example.com/as/user_authz.oauth2
    • https://www.example.org/welcome?user_code=<activationcode> to https://www.example.com/as/user_authz.oauth2?user_code=<activationcode>
    This field has no default value.
    Pending Authorization Timeout (seconds)
    The lifetime of an activation code (the user_code parameter value) in seconds.
    This field has no default value.
    Device Polling Interval (seconds)
    The amount of time in seconds that the device waits between polling requests to the PingFederate token endpoint.
    This field has no default value.
    Bypass Activation Code Confirmation
    When PingFederate receives a verification request that includes an activation code (the user_code parameter value), it prompts the user to confirm the activation code.
    For PingFederate to skip this confirmation step, select this check box.
    This check box is not selected by default.
    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 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 client-initiated backhannel 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.