PingFederate Server

Configuring authorization server settings

The Authorization Server Settings page provides control over the usage and behavior of PingFederate as an authorization server, including the policies and settings for various grant types, refresh-tokens, persistent grants, and ID tokens.

Steps

  1. Go to System > OAuth Settings > Authorization Server Settings.

  2. Configure the authorization server to suit your use cases.

  3. Click Save.

    The following tables describe each field.

General configuration and policy settings

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.

Disallow the Plain PKCE Code Challenge Method (optional)

When selected, PingFederate, acting as the authorization server, rejects an authorization request that uses the PKCE plain code_challenge_method.

By default, this checkbox is cleared.

Learn more in Proof Key for Code Exchange by OAuth Public Clients.

Include Issuer in Authorization Response

When selected, PingFederate’s issuer identifier iss parameter is returned in the authorization response. By default, this checkbox is cleared.

Track User Sessions for Logout

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

Selecting this checkbox also lets you configure the logout mode and logout endpoints for each client. Learn more about Logout Mode in Configuring OAuth clients.

By default, this checkbox is cleared.

Client Secret Retention Period

The amount of time in minutes that the previous client secret is retained after changing the secret.

If value is 0, client secrets will not be retained. Maximum value is one month or 43800 minutes.

Global configuration can be overridden on a per client basis.

Pushed Authorization Request (PAR) Settings

Field Description

PAR Status

This field determines whether clients can or must use the PAR endpoint /as/par.oauth2 on the authorization server to initiate authorization flows. The default setting is Enabled.

This setting works in conjunction with each client’s Require Pushed Authorization Requests checkbox on the Client page.

For example:

  • If PAR is Enabled on the authorization server and required on the client, then the client must use PAR.

  • If PAR is Enabled on the authorization server but not required on the client, then the client can use PAR.

  • If PAR is Required on the authorization server but not required on the client, then the client must use PAR.

  • If PAR is Disabled on the authorization server and required on the client, then the client cannot access the authorization server.

Learn more about PAR in Pushed authorization requests endpoint and Configuring OAuth clients.

PAR Reference Timeout (Seconds)

Specifies the lifetime of the request Uniform Resource Identifier (URI) that the PAR endpoint returns to the client. The default is 60 seconds. The allowable values are 1 to 1800.

PAR Reference Entropy (Bytes)

Specifies the length of the request URI. Longer request URIs are more secure. The default is 24 bytes. The allowable values are 20 to 256.

Refresh Token and Persistent Grant Settings

Field Description

Persistent Grant Max Lifetime

This field determines whether persistent grants should expire, and if so, the default maximum lifetime for persistent grants.

  • Select Grants Do Not Expire to 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 Days, Hours, or Minutes from the list.

The default selection is Grants Do Not Expire.

You can override the expiration in individual client records or grant-mapping configurations. Grant-mapping configurations take precedence and require an extended persistent grant attribute, PERSISTENT_GRANT_LIFETIME.

Grants expire at the max lifetime set when they are created. When a grant is reused, the max lifetime should be reused as well. New refresh token requests only update the accessGrantUpdated value, and won’t change the grant’s max lifetime.

Persistent Grant Idle Timeout

This field determines whether persistent grants should expire due to inactivity, regardless of whether the maximum lifetime has been reached, and 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 from the list.

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.

Learn more in Transient grants and persistent grants.

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.

You can override the expiration in individual client records.

Refresh Token Length (Characters)

The length of the refresh tokens in numerical 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. Otherwise, each refresh token is used until it becomes invalid, either by manual revocation or another security setting that renders the token invalid.

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

By default, this checkbox is cleared.

Minimum Interval to Roll Refresh Tokens

The minimum time 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.

In the list, select Hours, Minutes, or Seconds and enter an integer in the field.

The default value is 0.

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

The maximum value is 86400. For security reasons, you should set the custom value as low as possible.

If specified:

  • The most recently issued refresh tokens must be refreshed once and converted to the new format.

  • The global settings apply to all clients.

The default value is 60.

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 types that you want PingFederate to reuse the existing grant for, 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 the most recently issued is valid, and 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 (default)

  • Authorization Code

  • Resource Owner Password Credentials

When the Implicit checkbox 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 checkbox is selected, the same is true if the Bypass Authorization for Previously Approved Persistent Grants checkbox 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.

By default, this checkbox is cleared.

Allow Unidentified Clients to Request Extension Grants

When selected, PingFederate allows user-initiated or client-initiated events, such as 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:

  • JSON Web Token (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

By default, this checkbox is cleared.

Token Endpoint Base URL

When clients authenticate with 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 also take into consideration when validating the aud parameter.

If configured, the OpenID Provider (OP) 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.

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.

Persistent Grant Extended Attributes

Field Description

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 Grant Mapping

  • OAuth Attribute Mapping

  • Authentication Policy Contract Mapping

  • Resource Owner Credentials Grant Mapping

This field has no default entry. PingFederate allows multiple entries.

If you have already created 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.
Field Description

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 applies only when using the authorization code grant type and when the Reuse Existing Persistent Access Grants for Grant Types checkbox is selected.

By default, this checkbox is cleared.

Bypass Authorization for Previously Approved Consents

When selected, PingFederate will persist consent decisions.

For flows with clients that request the same scope or a reduced list of scopes, as previously granted by the user, PingFederate will not show the Request for Approval screen again if not explicitly requested. For example prompt=consent.

By default, this checkbox is cleared.

PingFederate will create consent records even if no refresh_token is generated.

Consent Max Lifetime (Days)
Consents Do Not Expire

Consent will not be removed.

Days Field

A number of days. Valid range is 1-999. After that period, persisted consents will be treated as non-existent and removed.

Consent User Interface

Specifies whether PingFederate or a trusted web application should handle consent approval.

Default

Select Default and let PingFederate handle 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 (1.5 or later), you can select it in 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 (1.5 or later), you can select it in the list. The expectation is that the trusted web application is integrated with PingFederate through this Reference ID Adapter instance.

Your development team can also create a custom adapter using the PingFederate SDK. Learn more in the Javadoc about the IdpAuthenticationAdapterV2 interface, the ExternalConsentPageAdapter.java file for a sample implementation, and the SDK Developer’s Guide for build and deployment information.

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

After you’ve deployed, you can create an instance of the selected adapter instance.

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 in the list.

OAuth Administrative Web Services Settings

Field Description

Password Credential Validator

Selects a password credential validator (PCV) instance to manage clients using the OAuth Client Management Service or to manage persistent grants using the OAuth Access Grant Management Service.

This setting has no default selection. When no PCV is selected, neither service can be used.

Persistent Grant Management API

The Persistent Grant Management API allows clients to 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 for that user. Learn more in OAuth Persistent Grant Management API.

Field Description

Access Token Manager

Selects an Access Token Management instance under which one or more clients can use the access tokens issued to manage persistent grants on their users.

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

Required Scope

Selects the scope that PingFederate looks for in access tokens prior to granting clients the permission to manage persistent grants for their users.

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

Cross-Origin Resource Sharing Settings

Field Description

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

After configuration, 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(JWKS). Learn more about CORS in W3C’s recommendation on Cross-Origin Resource Sharing.

Here are some example entries and their behaviors:

  • 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. However, a port number is required in the Origin request header.

Although 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. PingFederate allows multiple entries.

Device Authorization Grant Settings

The OAuth 2.0 Device Authorization Grant specification defines the process of a user granting authorization to a device using a browser on a second device, such as a smartphone or a computer. Learn more in Device authorization grant.

Field Description

User Authorization URL

(Optional)

This field determines whether PingFederate should use a different URL, possibly for ease of use or branding purposes, 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. Learn more in User authorization endpoint. The target web server 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.

You can 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. learn more in 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.

The registered authorization path behaves the same way as the user authorization endpoint does. Learn more in 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.

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

You can override this setting in individual client records.

Check Activation Code

This setting determines whether the activation code verification step should happen before or after the user is authenticated. One advantage of checking before authentication is that it allows PingFederate to determine up front the client ID and scopes for the flow. As a result, selectors such as the OAuth Client Set Authentication Selector, Extended Property Authentication Selector, and OAuth Scope Authentication Selector will work as expected in deciding the authentication policy for the user.

The default setting is After Authentication.

Checking the activation code before authentication means that the key PingFederate uses for rate limiting is based only on the user’s IP address. This means that the rate limit must be higher, because the key will be shared across all users who have the same IP address. Learn more through the <pf_install>/pingfederate/server/default/data/config-store/oauth-device-flow.xml file, including how to tune the rate limit appropriately for your deployment.

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 determines whether PingFederate skips this confirmation step.

Select the Bypass Activation Code Confirmation checkbox for PingFederate to skip the confirmation step.

By default, this checkbox is cleared.

You can override this setting in individual client records.

JWT Secured Authorization Response Mode (JARM)

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 through the JARM specification.

Field Description

JWT Lifetime (Seconds)

The lifetime of the authorization response token that PingFederate returns.

The default value is 600 seconds.

Demonstrating Proof-of-Possession (DPoP)

The DPoP protocol provides a way for clients to prove possession of a private key associated with a specific access token during each request. By including a DPoP token in the request, the authorization server can verify that the client has legitimate access to the private key. You can require a client to use DPoP by selecting the Require DPoP checkbox on the Client page. Learn more about the protocol in the OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer specification.

Field Description

Require DPoP Proof JWT Nonce

Specifies whether a nonce is required in the DPoP proof JWT. By default, the nonce is not required.

DPoP Proof JWT Lifetime (Seconds)

Specifies the lifetime of the DPoP proof JWT. By default, the lifetime is 120 seconds.

Enforce DPoP Proof JWT Replay Prevention

Specifies whether PingFederate requires a unique signed DPoP proof JWT from the client for each request. By default, the checkbox is cleared.

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