Creating a generation JSON Web Token profile

Create a generation JSON Web Token (JWT) profile to specify how Pega Platform generates a given JWT.

Before you begin: Configure cryptographic components in instances of an existing keystore. Pega Platform can then generate the JWT form this profile using these components to calculate the token’s signature as well as encrypt the token. For details, see Creating a keystore.

To generate a JWT, Pega Platform processes this generation JWT profile with the pxGenerateJWT activity. The generation JWT profile data instance consists of one or more headers, claims and a security configuration specifying no security, a signed token, an encrypted token, or a combination that uses both signing and encryption. The profile can specify a token lifetime and timeout option as well as if the profile should also include a processing JWT profile.

You can use JWTs to exchange information securely between Pega Platform and another party and to encrypt the data to be transmitted. Common uses for JWTs in Pega Platform include:

  • Authentication – The JWT holds user information that can be used by another party to authenticate the identity of the user presenting the token.
  • Session management – The JWT ensures the secure exchange of information during user authenticated sessions.

By default Pega Platform automatically adds the following parameters to the JWT header when it generates the token:

  • alg – The configured JWS algorithm, if you added one, in the Security section, on the Generation tab.
  • typ – The type is always JWT.
  • kid – The Key ID is a unique ID generated by the JWT run time process for each token generated.
  • crit – Headers that are marked as critical on the Generation tab.

After you create a generation JWT profile, you can view the details of the token that the profile will generate by clicking Preview.

  1. In the navigation panel, click Records > Security > Token Profile.
  2. Click Create.
  3. In the Token Type field, select JSON Web Token.
  4. In the Purpose field, select Generation to create a token profile for generating a new JWT.
  5. Enter a token profile name and short description.
  6. Click Create and open.
  7. In the Headers section, you can supplement the default JWT header parameters with additional parameters by clicking the Add icon and completing the Name, Description, Map from fields.
    • If you selected Constant in the Map from field, then enter a text string in the Map from key field.
    • If you selected Clipboard in the Map from field, then enter a property name on the clipboard in the Map from key field.
  8. In the Claims section, add a set of Registered claims to the payload of the token.
    1. Click the Add icon.
    2. In the Name field, press the Down arrow key, and select one of the available claims:
      • Issuer (iss) – Specifies the principal that issued the JWT.
      • Audience (aud) – Specifies the intended recipients of the JWT.
      • Subject (sub) – Specifies the principal that is the subject of the JWT.
        Note: Each claim must have a different name.
    3. In the Map from field, select whether to map the claim value to text or to a clipboard property:
    • If you selected Constant in the Map from field, then enter a text string in the Map from key field.
    • If you selected Clipboard in the Map from field, then enter a property name on the clipboard in the Map from key field.
  9. In the Claims section, add a set of Custom claims to the payload of the token to share information between parties that agree to use these claims.
    1. Click the Add icon.
    2. Complete the Name and Description fields
    3. In the Map from field, select whether to map the claim value to text or to a clipboard property:
    • If you selected Constant in the Map from field, then enter a text string in the Map from key field.
    • If you selected Clipboard in the Map from field, then enter a property name on the clipboard in the Map from key field.
  10. In the Security configuration field, specify whether to generate a signed JWT for a signature, or JSON Web Encryption (JWE) token for content encryption.

    • Signature – Configure the JWT signature for validation purposes by a recipient by completing step 11.

    • Encryption – Configure the JWT encryption in order to obscure its content by completing step 12.

    • Signature & encryption – Use this token for both signature and data encryption configurations by completing steps 11 and 12.

    • None – Disable security by skipping steps 11 and 12.

  11. For JWT signature configuration, in the JSON Web Signature (JWS) section, complete the following steps.
    1. In the Signature type list, select either Asymmetric or Symmetric.
    2. In the Signature algorithm list, press the Down arrow key, and select an algorithm for signing the token.
    3. In the Keystore field, press the Down arrow key, and select an existing keystore name.
    4. In the Alias field, press the Down arrow key, and select the alias name of the private key in this keystore used to sign the JWT generated from this JWT profile.
    5. In the Password field, enter the keystore password.
      Note: After you save a token rule for decrypting tokens that use asymmetric encryption, the JSON web key set URI field exposes the public key endpoint for retrieving the public key.
    6. For Asymmetric signatures only: To suppress the key ID header, select the Suppress generation of Key ID (kid) header check box.
  12. For JWE content encryption, in the JSON Web Encryption (JWE) section, select either Asymmetric or Symmetric
    Choices Actions

    For asymmetric encryption
    1. In the Key Encryption algorithm field, press the Down arrow key, and select an algorithm for encrypting the secret key.
    2. In the Truststore field, press the Down arrow key, and select the truststore name.
    3. In the Alias field, enter the alias name of the private key in this keystore used to encrypt the JWT generated from this JWT profile.
    4. In the Content encryption algorithm field, press the Down arrow key, and select an algorithm for encrypting the content.
    5. To suppress the key ID header, select the Suppress generation of Key ID (kid) header check box.
    .
    For symmetric encryption
    1. In the Key Encryption algorithm field, press the Down arrow key, and select an algorithm for encrypting the secret key.
    2. In the Keystore field, press the Down arrow key, and select an existing keystore name.
    3. In the Alias field, press the Down arrow key, and select the alias name of the private key in this keystore used to encrypt the JWT generated from this JWT profile.
    4. In the Password field, enter the keystore password.
    5. In the Content encryption algorithm field, press the Down arrow key, and select an algorithm for encrypting the content.
  13. In the Token lifetime section, complete the following steps.
    1. In the Valid till (in seconds) field, specify the number of seconds that the token remains valid after the token is issued. The default value is 900 seconds.
    2. In the Processed not before (in seconds) field, enter the time before which the receiver of the JWT cannot use the token. The default coded in value for this field is 0 seconds.
  14. Click Save.
  15. If you want to add a processing profile to this generation JWT profile, in the Advanced section, select Process generated token.
  16. Click the Processing tab.
    Based on the token generation profile configuration, some sections and fields automatically fill.
    To complete the remaining fields, go to Processing a JSON Web Token, and begin at step 7.