Configuring JSON token management - PingFederate - 11.0

PingFederate Server

bundle
pingfederate-110
ft:publication_title
PingFederate Server
Product_Version_ce
PingFederate 11.0
category
Product
pf-110
pingfederate
ContentType_ce

JSON web token (JWT) 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.

In the Access Token Management window, configure an access token management instance. 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. This token data model is suitable for both standalone and clustered environments.

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

      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 and complete the task.
      Note:

      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.

      You are directed back to the Instance Configuration tab.
    3. Change or select the remaining field entries as needed.

      For more information about JSON web algorithms (JWAs), 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 JWT "exp" claim value.

      Use Centralized Signing Key

      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.

      Note:

      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.

      Note:

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

      Note:

      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.

      If the field value is empty, PingFederate will 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, 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 may 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 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.

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