The Authorization Server Settings screen provides overall controls over the usage and behavior of PingFederate as an OAuth authorization server (AS), including the policies and settings for various grant types, refresh-tokens, persistent grants, and ID tokens.

  1. Go to the OAuth Server > Authorization Server Settings screen.
  2. Configure AS settings that suit your use cases.
    Refer to the following table for detailed information about each field.
    Field Description
    Authorization Code Timeout (Seconds) The amount of time in seconds that an authorization code is considered valid.

    The default value is 60.
    Authorization Code Entropy (Bytes) The length in bytes of the authorization code returned to clients.

    The default value is 30.

    Track User Sessions for Logout When selected, PingFederate links the sessions for IdP adapters that are used by clients to the PingFederate authentication session of the user (the resource owner). When a user initiates logout, PingFederate sends (via the browser) logout requests to close the adapter sessions.

    If the OpenID Connect protocol is enabled in System > Protocol Settings > Roles & Protocols screen, selecting this check box also allows per-client logout endpoints to be defined, which will be invoked during logout.

    The check box is not selected by default.

    Refresh Token and Persistent Grant Settings
    Persistent Grant Max Lifetime This field controls whether persistent grants should expire, and if so, the default maximum lifetime for persistent grants.
    • Select Grants Do Not Expire and let persistent grants remain valid until they are revoked or removed.
    • Select the time value option to set a maximum lifetime for persistent grants. Enter an integer between 1 and 999 in the field and select a unit of measurement (minutes, hours, or days) from the list.

    The default selection is Grants Do Not Expire.

    Note:

    You may override the expiration in individual client records or grant-mapping configurations. The latter takes precedence and requires an extended persistent grant attribute PERSISTENT_GRANT_LIFETIME.
    Persistent Grant Idle Timeout This field controls whether persistent grants should expire due to inactivity (regardless of whether the maximum lifetime has been reached), and if so, the default idle timeout period.
    • Select Grants Do Not Timeout Due To Inactivity and let persistent grants remain valid until they expire or are removed.
    • Select the time value option to set the default idle timeout window. Enter an integer between 1 and 999 in the field and select a unit of measurement (minutes, hours, or days) from the list.

      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.

    For new installations, the default inactivity allowance is 30 days. For upgrades, Grants Do Not Timeout Due To Inactivity is the default selection unless a specific value was set previously.

    Note:

    You may override the expiration in individual client records.
    Refresh Token Length (Characters) The length of the refresh tokens in number characters.

    The default value is 42.

    Roll Refresh Token Values (Default Policy) When selected, PingFederate generates a new refresh token when a new access token is issued.
    Note:

    New refresh tokens are not issued during the interval defined by the Minimum Interval to Roll Refresh Tokens field.

    When not selected, each refresh token is used until it becomes invalid (either by manually revoking or by some other security setting that renders it invalid).

    This check box is not selected by default.

    Minimum Interval to Roll Refresh Tokens (Hours) The minimum number of hours that must pass before a new refresh token can be issued. This setting provides a way to allow for rolling refresh tokens without having to send a new refresh token on every request.

    The default value is 0.

    Reuse Existing Persistent Access Grants for Grant Types If a client makes multiple requests for the same user and the same (or lesser) scope, select the grant type (or grant types) that you want PingFederate to reuse the existing grant rather than creating a new grant for each request.

    Reusing an existing persistent grant imposes a limit of one grant per client, per user. In the context of refresh tokens, only one (the most recently issued) is valid; the previously issued refresh token is invalidated. If the same client are installed on multiple devices and used regularly by the same user, the grant type used by this client should be cleared.

    The applicable grant types are:

    • Implicit (selected by default)
    • Authorization Code
    • Resource Owner Password Credentials

    When the Implicit check box is selected, PingFederate requests consent from the user only once. The user is not asked for authorization on subsequent requests until the access grant is revoked.

    When the Authorization Code check box is selected, the same is true if the Bypass Authorization for Previously Approved Persistent Grants check box is also selected.

    Allow Unidentified Clients to Make Resource Owner Password Credentials Grants When selected, PingFederate allows resource owners to obtain access tokens without client ID or client authentication.

    The check box is not selected by default.

    Allow Unidentified Clients to Request Extension Grants When selected, PingFederate allows user-initiated or client-initiated events (for example, a mobile application or a scheduled task) to obtain access tokens without the client presenting a client_id or client_secret for the extension grant types, namely:
    • JWT Bearer Token grant type

      urn:ietf:params:oauth:grant-type:jwt-bearer

    • SAML 2.0 Bearer Assertion grant type

      urn:ietf:params:oauth:grant-type:saml2-bearer

    • Validation grant type

      urn:pingidentity.com:oauth2:grant_type:validate_bearer

    The check box is not selected by default.

    Token Endpoint Base URL When clients authenticate via the private_key_jwt authentication method, PingFederate validates the aud parameter value (found inside the signed JWT) against its base URL or any configured virtual host names. If the values do not match, the authentication fails.

    Enter a separate base URL that PingFederate can take into consideration as well when validating the aud parameter.

    If configured, the OpenID Provider configuration endpoint (/.well-known/openid-configuration) uses the Token Endpoint Base URL field value as the base for the token endpoint.

    This field has no default value.

    Persistent Grant Extended Attributes
    Attributes Extend persistent grants to include additional attributes from your authentication systems.
    Lifetime of persistent grants
    Add the attribute PERSISTENT_GRANT_LIFETIME to enable the option to 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.
    This capability applies to the following grant-mapping configurations:
    • IdP Adapter Mapping
    • OAuth Attribute Mapping
    • Authentication Policy Contract Mapping
    • Resource Owner Credentials Mapping

    This field has no default entry. Multiple entries are allowed.

    Note:

    If you have already created some grant mapping configurations and then add one or more attributes in this section, the newly added attributes are configured as No Mapping in all existing grant mapping configurations. You can configure fulfillment for the newly added attributes in individual grant mapping configurations when your use cases require those attributes.
    Authorization Consent
    Bypass Authorization for Previously Approved Persistent Grants When selected, PingFederate requests consent from the user only once. The user is not asked for authorization on subsequent requests until the access grant is revoked. This behavior applies only when using the authorization code grant type and when the Reuse Existing Persistent Access Grants for Grant Types check box is selected.

    The check box is not selected by default.

    Note:

    You may override this setting in individual client records.
    Consent User Interface This field controls whether PingFederate or a trusted web application should handle consent approval.
    Default
    Select Default and let PingFederate handles consent approval by presenting the Request for Approval page to the resource owner.
    External
    Select External to delegate the responsibilities of consent approval to a trusted web application.
    For example, if you have created an instance of the Reference ID Adapter version (version 1.5 or a subsequent version), you may select it from the list. The expectation is that the trusted web application is integrated with PingFederate through this Reference ID Adapter instance.
    When selected, you must also configure two additional fields: External Consent IdP Adapter and External Consent Scopes Attribute.
    External Consent IdP Adapter
    The External Consent IdP Adapter field displays a list of IdP adapter instances that are capable of facilitating the consent approval process.
    For example, if you have created an instance of the Reference ID Adapter version (version 1.5 or a subsequent version), you may select it from the list. The expectation is that the trusted web application is integrated with PingFederate through this Reference ID Adapter instance.
    Your development team may also create a custom adapter using the PingFederate SDK. For more information, refer to the Javadoc for the IdpAuthenticationAdapterV2 interface, the ExternalConsentPageAdapter.java file for a sample implementation, and the SDK developer's guide for build and deployment information.
    Tip:

    The Javadoc for PingFederate and the sample implementation are located under the <pf_install>/pingfederate/sdk directory.

    Once deployed, you may create an instance of the custom adapter and select it from the list.
    External Consent Scopes Attribute
    The External Consent Scopes Attribute field displays a list of attributes defined in the IdP adapter contract of the selected adapter instance. Select the attribute whose value contains the approved scopes returned by the trusted web application.
    For example, if you have added an attribute called approvedScopes to the adapter instance with the expectation that approvedScopes is the attribute that the trusted web application passes approved scopes to PingFederate, select approvedScopes from the list.
    OAuth Administrative Web Services Settings
    Password Credential Validator If you want to manage clients using the OAuth Client Management Service or to manage persistent grants using the OAuth Access Grant Management Service, select a Password Credential Validator instance from the list.

    This setting has no default selection. When no validator is selected, neither services can be used.

    Persistent Grant Management API

    The Persistent Grant Management API facilitates the use case where clients can assume the responsibility of grant management if the users authorize the clients to do so. In this scenario, a client prompts the user to approve a specific scope for managing persistent grants on the user's behalf. If the user approves, the client requests an access token with such scope from PingFederate. As long as the access token remains valid, the client can retrieve and revoke persistent grants and their associated extended attribute names and values (if any) for that user. (For more information, see OAuth Persistent Grant Management API.)

    Access Token Manager Select an Access Token Management instance under which the access tokens issued can be used by one or more clients to manage persistent grants on their users' behalves.

    Note that such clients must also be configured to use this Access Token Management instance in their client configurations.

    Required Scope Select the scope that PingFederate looks for in access tokens prior to granting clients the permission to manage persistent grants on their users' behalves.

    Note that clients must obtain access tokens with this scope and include them in their grant-management requests.

    Cross-Origin Resource Sharing Settings
    Allowed Origin Enter any number of trusted origins to enable cross-origin resource sharing (CORS) support for the following OAuth endpoints:
    • /as/token.oauth2
    • /as/revoke_token.oauth2
    • /idp/userinfo.openid
    • /pf-ws/rest/oauth/grants/
    • /pf/JWKS
    • /.well-known/openid-configuration
    • /as/bc-auth.ciba
    Once configured, client-side web applications from the trusted origins are allowed to make requests to the PingFederate authorization server for the purpose of accessing protected resources, such as obtaining (or renewing) access tokens (with refresh tokens), presenting access tokens for revocation, querying additional claims (user attributes), and retrieving OpenID Provider configuration information and JSON Web Key Sets. For more information about CORS, please refer to W3C's recommendation on Cross-Origin Resource Sharing (www.w3.org/TR/cors).
    Sample entry Expected behavior
    https://www.example.com CORS requests originating from https://www.example.com are allowed.
    https://www.example.com:8080 CORS requests originating from https://www.example.com:8080 are allowed.
    https://www.example.com:* CORS requests originating from https://www.example.com:<any port> are allowed.
    Note:

    Given this sample entry, a port number is required in the Origin request header.

    Important:

    While using the wildcard character provides the convenience of allowing multiple origins with one entry, consider adding individual origins to limit CORS requests to a list of trusted hosts.

    This field has no default entry. Multiple entries are allowed.

    Device Authorization Grant Settings

    The OAuth 2.0 Device Authorization Grant specification defines the process that allows a user to grant authorization to a device using a browser on a second device, such as a smartphone or a computer. For more information, see Device authorization grant.
    User Authorization URL

    (Optional)

    		 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.

    Note:

    You may override this setting in individual client records.
    Registered Authorization Path

    (Optional)

    		 This field controls whether PingFederate should replace the user authorization endpoint with a different path, 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). The domain portion remains to be the base URL of PingFederate. For example, if the base URL is https://www.example.com and this field is configured with a value of /go, PingFederate returns https://www.example.com/go and https://www.example.com/go?user_code=<activationcode> as the user authorization URLs.

    If PingFederate receives a device authorization request at one of the configured virtual host names, PingFederate preserves the virtual host name in its device authorization responses.

    Note:

    The registered authorization path behaves the same way as the user authorization endpoint does (see User authorization endpoint).

    This field is ignored when the User Authorization URL field is configured here or in the individual client records.

    The configured value must begin with a forward slash (/).

    This field has no default value.

    Pending Authorization Timeout (seconds) The lifetime of an activation code (the user_code parameter value) in seconds.

    The default value is 600.

    Note:

    You may override this setting in individual client records.
    Device Polling Interval (seconds) The amount of time in seconds that the device waits between polling requests to the PingFederate token endpoint.

    The default value is 5.

    Note:

    You may override this setting in individual client records.
    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.

    Note:

    You may override this setting in individual client records.