Configuring JSON token management

Steps

Go to Applications → OAuth → Access Token Management and click Create New Instance.

On the Instance Configuration tab, add one or more symmetric keys, signing certificates, or both:

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.

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.

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.

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.

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

PingFederate Server

Configuring JSON token management

Steps

Result: