JSON Web Token (JWT) bearer access tokens are secure and self-contained tokens. This capability allows the target resource server (RS) to validate the access tokens locally or to send the access tokens to the token issuer (PingFederate as the AS) for validation. The configuration provides for token security using either symmetric keys or asymmetric signing-certificate keys. Multiple entries are allowed for either signing mechanism to facilitate rollover of keys when they expire. This token data model is suitable for both standalone and clustered environments.

  1. Add one or more symmetric keys, signing certificates, or both.
    Click Add a new row . . .Update under Action.
    Important:

    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 and use the Certificate Management workflow to complete the task.
    Note:

    To use an RSA-based algorithm for 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.

  2. Change or select entries for required fields and make other changes as needed.
    Refer to the following table for information about each field. For detailed information about the algorithms, please refer to the JSON Web Algorithms (JWA) specification (tools.ietf.org/html/rfc7518).
    Field Description
    Token Lifetime

    (Required)

    The amount of time in minutes that an access token is considered valid.

    The default value is 120 (minutes).

    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 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 (Direct Encryption with symmetric key, AES ... Key Wrap. and AES-GCM ... key encryption) and asymmetric algorithms (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 JWK format or a certificate.

    Applicable only if an asymmetric algorithm is selected from the JWE Algorithm list.

    Note that you can only specify an asymmetric encryption key here or the partner's JWKS endpoint in the Asymmetric Encryption JWKS URL field.

    Asymmetric Encryption JWKS URL The HTTPS URL of a JSON Web Key Set (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.

    Note that 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.

    Advanced fields
    Include Key ID Header Parameter When selected (the default), 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, in the event that the remote server does not contain any cache directives in its response, PingFederate only caches the content for 720 minutes (12 hours).

    Note that 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 (the default), 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, which 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.

    If the field value is removed and left blank, PingFederate does not include the client ID of the requesting client in the self-contained tokens. If clients may use the UserInfo endpoint to retrieve additional claims about the users, refer to 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 removed and left blank, PingFederate does not include any scope information in the self-contained token. If clients may use the UserInfo endpoint to retrieve additional claims about the users, refer to 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. (Omitted if left blank.)

    Additionally, you may extend the contract of the access tokens with an attribute named iss on the Access Token Attribute Contract screen. When mapping attribute values from authentication sources to the access tokens issued by this ATM instance, the value you specify on the Contract Fulfillment screen overrides the value here.

    Audience Claim Value The value of the Audience claim (aud) in the JWT. (Omitted if left blank.)

    When no value is specified, PingFederate does not validate the Audience claim (aud) value if any is included in the access token.

    Additionally, you may extend the contract of the access tokens with an attribute named aud on the Access Token Attribute Contract screen. When mapping attribute values from authentication sources to the access tokens issued by this ATM instance, the value you specify on the Contract Fulfillment screen overrides the value here.

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

    The default value is 0, which means no claim is included.

    Access Grant GUID Claim Name The name of the JWT claim used to carry the persistent access grant GUID. (Omitted if left blank.)

    If the claim is present during validation, PingFederate checks the grant database to ensure the grant is still valid.

    Note:

    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. The path, if specified, must begin with a forward slash; for example, /oauth/jwks.

    The resulting URL is https://<pf_host>:<pf.https.port>/ext/<JWKS Endpoint Path>.

    Furthermore, the path, if specified, must be unique across all plugin instances, including any child instances.

    JWKS Endpoint Cache Duration Informs the clients the amount of time 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 (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.