--- title: Configuring an access token management instance description: The configuration varies depending on the type of the access token manager. component: pingfederate version: 13.1 page_id: pingfederate:administrators_reference_guide:pf_configuring_access_token_management_instance canonical_url: https://docs.pingidentity.com/pingfederate/13.1/administrators_reference_guide/pf_configuring_access_token_management_instance.html llms_txt: https://docs.pingidentity.com/pingfederate/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: March 28, 2023 section_ids: the-reference-token-data-model: The reference token data model the-json-web-token-data-model: The JSON web token data model configuring-reference-token-management: Configuring reference token management steps: Steps related-links: Related links configuring-json-token-management: Configuring JSON token management steps-2: Steps result: Result: --- # Configuring an access token management instance The configuration varies depending on the type of the access token manager. ## The reference token data model Access tokens that use the reference token data model provide a reference to a set of attributes. The resource server must de-reference the access tokens for the corresponding identity and security information at the OAuth *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)* authorization server that issued them. The reference token data model supports both adaptive clustering and directed clustering. For adaptive clustering, PingFederate, as the authorization server, shares token information across a replica set. If region identifiers are defined, PingFederate shares token information across replica sets in multiple regions. You can optionally override this default behavior in the configuration file for adaptive clustering. For directed clustering, PingFederate shares token information among all engine nodes, despite any state server or subcluster setup. ## The JSON web token data model JSON Web Token (JWT) *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)* bearer access tokens are secure and self-contained tokens. This allows the target resource server to validate the access tokens locally or to send the access tokens to PingFederate for validation. This configuration uses either symmetric keys or asymmetric signing-certificate keys for token security. To facilitate rollover of keys when they expire, multiple entries are allowed for either signing mechanism. The JWT token data model is suitable for both standalone and clustered environments. * Reference-token management * JSON token management ## Configuring reference token management ### Steps 1. Go to **Applications > OAuth > Access Token Management** and click **Create New Instance**. 2. In the **Instance Configuration** window, modify the default values as needed. The following table describes each field. | Field | Description | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Token Length**(Required) | The number of characters that PingFederate uses to define the token reference. Increasing the length enhances token security.The default value is `28` characters. The minimum and maximum values are 22 and 256, respectively. | | **Token Lifetime**(Required) | The amount of time in minutes that an access token is considered valid.The default value is `120` minutes. | | **Lifetime Extension Policy** | Indicates whether PingFederate should reset the lifetime of an access token each time the token is validated, subject to the values defined in the **Maximum Token Lifetime** and **Lifetime Extension Threshold Percentage** fields.The options are:- **No Extension** - **Tokens Not Backed by Persistent Access Grants (Transient Grants)** - **All Tokens**The default selection is **No Extension**. | | **Maximum Token Lifetime** | Defines an absolute maximum token lifetime for use with the **Lifetime Extension Policy** setting, in minutes. When configured, the lifetime of access tokens can be extended but not beyond the configured value. Any value, if specified, must be greater than or equal to the value specified in the **Token Lifetime** field.This optional field has no default value. | | **Lifetime Extension Threshold Percentage**(Required) | When PingFederate is deployed in a cluster and token-lifetime extension is enabled, there must be a cluster-group remote procedure call (RPC) to extend the life of a token.To limit RPC overhead, this setting suspends the calls until the remaining time is less than the chosen value, as a percentage of token lifetime. For example, if the token lifetime is 60 minutes and the **Lifetime Extension Threshold Percentage** value is `30` percent, the lifetime will not be extended until the remaining time is less than 18 minutes. This option can drastically reduce RPC traffic between nodes, while still supporting a lifetime extension policy.The default value is `30` percent. | | **Advanced Fields** | | | **Mode for Synchronous RPC** | Synchronous RPC calls occur when a node receives a verification request for a token it does not recognize, and for token issuance.When **Majority of Nodes** is selected, the server waits for the majority of recipients to respond. It also eliminates the need for a complete state synchronization at startup.When **All Nodes** is selected, the server waits for all recipients to respond.The default selection is **Majority of Nodes**. | | **RPC Timeout**(Required) | The timeout value between cluster nodes during synchronous communication, in milliseconds. The recommended value ranges from 100 milliseconds to 1000, or 1 second.The default value is `500` milliseconds. | | **Expand Scope Groups** | Determines whether to expand scope groups into their corresponding scopes in the access token contents and introspection response.This checkbox is not selected by default. | ### Related links * [Adaptive clustering](../server_clustering_guide/pf_adaptiv_cluster.html) * [Directed clustering](../server_clustering_guide/pf_directed_cluster.html) ## Configuring JSON token management ### Steps 1. Go to **Applications > OAuth > Access Token Management** and click **Create New Instance**. 2. On the **Instance Configuration** tab, add one or more symmetric keys, signing certificates, or both: 1. Click **Add a new row to…​**, or click **Update** to modify an existing entry. | | | | - | ----------------------------------------------------------------------------------------------------------------- | | | The **Key ID** field values must be unique across all JSON token management instances, including child instances. | ![A screen capture of the Symmetric keys section in the Create Token Management Instance window configuration. There are Symmetric Keys and Certificates sections.](_images/jjr1637089310257.png) 2. If you have not yet created or imported your certificate into PingFederate, click **Manage Signing Certificates** to do so. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To use an RSA-based algorithm for JSON Web Signature (JWS) *(tooltip: \
\

A signed instance of a JSON Web Token (JWT) based on IETF standard syntax and used for the exchange of signed content.\

\
)*, the key size of the signing certificate must be at least 2,048 bits. For an EC-based JWS algorithm, the key size depends on the chosen algorithm. | ### Result: You're directed back to the **Instance Configuration** tab. 3. Change or select the remaining field entries as needed, which the following table describes. For more information about JSON Web Algorithms (JWA) *(tooltip: \
\

Registers cryptographic algorithms to be used with JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK).\

\
)*, see the [JSON Web Algorithms](https://datatracker.ietf.org/doc/html/rfc7518) specification. \+ | Field | Description | | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Token Lifetime**(Required) | The amount of time that an access token is considered valid, in minutes.The default value is `120` minutes.Additionally, you can extend the contract of the access tokens with an attribute named `exp` on the **Access Token Attribute Contract** tab. When mapping attribute values from authentication sources to the access tokens issued by this Access Token Management instance, the value you specify on the **Contract Fulfillment** tab sets the expiry as this many minutes from the current time. PingFederate internally calculates the actual epoch time for the JWT *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)* `exp` claim value. | | **Use Centralized Signing Key** | Select this option to use a centralized key when signing JWTs using an RSA-based or EC-based algorithm.When this option is selected and static keys are not enabled, PingFederate manages and rotates a set of keys, and uses the current key corresponding to the selected signing algorithm to sign the JWT.When this option is selected and static keys are enabled, PingFederate uses the current key corresponding to the selected signing algorithm to sign the JWT.When this option is selected, an OAuth *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)* client that has been configured to use JWT access tokens through this ATM instance can retrieve the key it needs to validate the digital signature by contacting PingFederate at the `/pf/JWKS` endpoint. | | **JSON Web Signature (JWS) configuration** | | | **JWS Algorithm** | The hash-based message authentication code (HMAC) or the signing algorithm (EC or RSA) used to protect the integrity of the token. If PingFederate is deployed to run in a Java 8 or Java 11 runtime environment, or integrated with a hardware security module (HSM), additional RSASSA-PSS signing algorithms become available for selection. For more information on HSM integration, see [Supported hardware security modules](../getting_started_with_pingfederate/pf_supported_hardware_security_modules.html).Required if an asymmetric algorithm is selected in the **JWE Algorithm** list. | | **Active Symmetric Key ID** | The ID of the symmetric key to use when producing JWTs using an HMAC-based algorithm.Required if an HMAC-based JWS algorithm is selected in the **JWS Algorithm** list. | | **Active Signing Certificate Key ID** | The ID of the key pair and certificate to use when producing JWTs using an EC-based or RSA-based algorithm.Required if an EC-based or RSA-based JWS algorithm is selected in the **JWS Algorithm** list. | | **JSON Web Encryption (JWE) configuration** | | | **JWE Algorithm** | The algorithm used to encrypt or otherwise determine the value of the content encryption key.PingFederate supports symmetric algorithms, such as **Direct Encryption with symmetric key**, **AES …​ Key Wrap**, and **AES-GCM …​ key encryption**, and asymmetric algorithms, such as **ECDH-ES**, **ECDH-ES …​ Key Wrap**, and **RSAES OAEP**. | | **JWE 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 in the **JWE Algorithm** list. | | **Active Symmetric Encryption Key ID** | The ID of the key to use when using a symmetric encryption algorithm.Required if a symmetric algorithm is selected in the **JWE Algorithm** list. | | **Asymmetric Encryption Key** | An asymmetric encryption public key from your partner, which can be in either JSON web key (JWK) format or a certificate.Applicable only if an asymmetric algorithm is selected from the **JWE Algorithm** list. You can only specify an asymmetric encryption key here or the partner's JSON web key set (JWKS) endpoint in the Asymmetric Encryption JWKS URL field. | | **Asymmetric Encryption JWKS URL** | The HTTPS URL of a JWKS endpoint that provides a list of one or more public keys for encryption.Applicable only if an asymmetric algorithm is selected from the **JWE Algorithm** list. You can only specify an asymmetric encryption JWK URL here or the asymmetric encryption public key from your partner in the Asymmetric Encryption Key field. | | **Enable Token Revocation** | When selected, PingFederate will directly revoke a JWT access token if the client that was issued the token requests its revocation. The client can request token revocation by sending a POST request with the token to the revocation endpoint at `/as/revoke_token.oauth2`.When this checkbox is selected, the JWTs require a **Client ID Claim Name** and a minimum **JWT ID Claim Length** of 22 alphanumeric characters.This checkbox is cleared by default. When this feature is enabled, validation of access tokens may take longer, depending on the configuration of the session revocation service. | | **Advanced fields** | | | **Include Key ID Header Parameter** | When selected, the key ID is used in the `kid` header parameter for the token.This checkbox is selected by default. | | **Include X.509 Thumbprint Header Parameter** | When selected, the X.509 certificate thumbprint is used in the `x5t` header parameter for the token.This checkbox is not selected by default. | | **Default JWKS URL Cache Duration** | When an asymmetric encryption JWKS URL is specified, if the remote server does not contain any cache directives in its response, PingFederate only caches the content for 720 minutes (12 hours). When this threshold is reached or if the cache directives indicate that the content has expired at runtime, PingFederate contacts the remote server to refresh the list of encryption keys from the partner. | | **Include JWE Key ID header parameter** | When selected, indicates whether the key ID (`kid`) header parameter will be included in the encryption header of the token, which can help identify the appropriate key during decryption.This checkbox is selected by default. | | **Include JWE X.509 Thumbprint Header Parameter** | When selected, the X.509 certificate thumbprint is used as the `x5t` header parameter value in the encryption header of the token. This can help identify the appropriate key during decryption.This checkbox is not selected by default. | | **Client ID Claim Name** | The name of a JWT claim used to represent the OAuth client ID.The default value is `client_id`.If the field value is empty, PingFederate will not include the client ID of the requesting client in the self-contained tokens. If clients might use the `UserInfo` endpoint to retrieve additional claims about the users, see [UserInfo endpoint](../developers_reference_guide/pf_userinfo_endpoint.html) for more information. | | **Scope Claim Name** | The name of a JWT claim used to represent the scope of the grant.The default value is `scope`.If the field value is empty, PingFederate will not include any scope information in the self-contained token. If clients might use the `UserInfo` endpoint to retrieve additional claims about the users, see [UserInfo endpoint](../developers_reference_guide/pf_userinfo_endpoint.html) for more information. | | **Space Delimit Scope Values** | When selected, indicates scope strings will be delimited by spaces rather than represented as a JSON array.This checkbox is not selected by default. | | **Issuer Claim Value** | The value of the Issuer claim (`iss`) in the JWT. If left blank, this field is omitted.Additionally, you may extend the contract of the access tokens with an attribute named `iss` on the **Access Token Attribute Contract** tab. When mapping attribute values from authentication sources to the access tokens issued by this ATM instance, the value that you specify on the **Contract Fulfillment** tab overrides the value here. | | **Audience Claim Value** | The value of the Audience claim (`aud`) in the JWT. If left blank, this field is omitted.When no value is specified, PingFederate does not validate the `aud` value, if any is included in the access token.You can also extend the contract of the access tokens with an attribute named `aud` in the **Access Token Attribute Contract** tab. When mapping attribute values from authentication sources to the access tokens issued by this ATM instance, the value specified in the **Contract Fulfillment** window overrides this value. | | **Not Before Claim Offset** | To account for clock skew, you can enter a positive value that indicates the number of minutes *before* the token issuing time to which the Not Before (`nbf`) claim value will be set. For example, if the token is issued at 09:30 and the value of this offset is `10`, then the `nbf` claim value will be `09:20`.Conversely, a negative value indicates the number of minutes *after* the token issuing time to which the `nbf` claim value will be set. For example, if the token is issued at 09:30 and the value of this offset is `-10`, then the `nbf` claim value will be `09:40`.By default, the field is blank. | | **Include Issued At Claim** | Indicates whether to include the Issued At (`iat`) claim in the JWT. By default, the checkbox is selected. | | **JWT ID Claim Length** | Indicates the number of characters of the JWT ID (`jti`) claim in the JWT.The default value is `22`. The jti claim is omitted if the value is `0`. | | **Access Grant GUID Claim Name** | The name of the JWT claim used to carry the persistent access grant GUID. If left blank, this field is omitted.If the claim is present during validation, PingFederate checks the grant database to ensure that the grant is still valid. This use case requires that the RS must send the JWT bearer access tokens to PingFederate for validation. | | **Publish Keys to the PingFederate JWKS Endpoint** | Select to publish asymmetric signing keys to the PingFederate JWKS endpoint.Published keys are discoverable using the [OpenID Provider configuration endpoint](../developers_reference_guide/pf_openid_provider_config_endpoint.html). If publication is enabled, asymmetric key identifiers must be unique across all plugin instances, OAuth and OIDC keys, and token signing keys. | | **JWKS Endpoint Path** | The path on the PingFederate server to publish a JWKS with the keys and certificates that the partners can use for signature verification. Optional when an algorithm is selected in the **JWS Algorithm** list. If specified, the path must begin with a forward slash, such as `/oauth/jwks`.The resulting URL is https\://*\*:*\*/ext/*\*.The path must be unique across all plugin instances, including any child instances. | | **JWKS Endpoint Cache Duration** | Informs the clients of the duration that they could cache the content from the JWKS endpoint path. Applicable only if the **JWKS Endpoint Path** field is configured.The default is `720` minutes, or 12 hours. | | **Publish Key ID X.509 URL** | Indicates whether certificates will be made accessible by the key ID at https\://*\*:*\*/ext/oauth/x509/kid?v=*\*.This checkbox is not selected by default. | | **Publish Thumbprint X.509 URL** | Indicates whether certificates will be made accessible by thumbprint at https\://*\*:*\*/ext/oauth/x509/x5t?v=*\*.This checkbox is not selected by default. | | **Expand Scope Groups** | Determines whether to expand scope groups into their corresponding scopes in the access token contents and introspection response.This checkbox is not selected by default. | | **Type Header Value** | Indicates the value of the Type (`typ`) header in the JWT. If you do not specify a header, it is omitted. |