PingFederate Server

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

glossary:gJWT[]  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 {pingfed} 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 check box is not selected by default.

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.

    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), 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 are 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), see the JSON Web Algorithms 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 JSON Web Token (JWT) 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 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.

    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 check box is selected, the JWTs require a Client ID Claim Name and a minimum JWT ID Claim Length of 22 alphanumeric characters.

    This check box 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 check box 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 check box 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 check box 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 check box 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.

    include::ROOT:partial$pf_rc_clientidclaimname_novalue.adoc[tags=pf_ph_clientIdClaimName_noValue]If clients might use the UserInfo endpoint to retrieve additional claims about the users, see UserInfo endpoint 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 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 check box 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 check box is selected.

    JWT ID Claim Length

    Indicates the number of characters of the JWT ID (jti) claim in the JWT.

    The default value is 0, meaning no claim is included.

    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.

    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://<pf_host>:<pf.https.port>/ext/<JWKS Endpoint Path>.

    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://<pf_host>:<pf.https.port>/ext/oauth/x509/kid?v=<id>.

    This check box is not selected by default.

    Publish Thumbprint X.509 URL

    Indicates whether certificates will be made accessible by thumbprint at https://<pf_host>:<pf.https.port>/ext/oauth/x509/x5t?v=<base64url encoded SHA-1 thumbprint>.

    This check box 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 check box 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.