Creating a processing JSON Web Token profile

Create a processing JSON Web Token (JWT) profile to specify how Pega Platform validates and decrypts each JSON Web Token it receives.

Before you begin: Configure cryptographic components in instances of an existing keystore. Pega Platform can then use the keystore components to validate the token’s signature as well as decrypt the token when Pega Platform receives it from an external source. For details, see Creating a keystore for application data encryption.

The processing JWT profile data instance consists of one or more claims validations, claims mappings, and a security configuration specifying no security, signing, decryption, or a combination that uses both signing and decryption. The profile can also specify a token lifetime and timeout option.

You can use JWTs to exchange information securely between Pega Platform and another party and to decrypt 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.
  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 Processing, to create a token profile for processing JWTs.
  5. Enter a token name and short description.
  6. Click Create and open.
  7. On the Processing tab, in the Claims validation section, click the Add icon to configure validations that are applied to the expected claims.
    1. 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.
    2. In the Map from field, select Constant or Clipboard to indicated if the claim is mapped from a text string you enter or a property name on the clipboard.
    3. In the Compare with field, enter the constant or clipboard property with which the claim should be compared.
  8. In the Claims mapping section, click the Add icon to configure mapping for custom claims to clipboard properties.
    1. In the Claim name field, enter the custom claim name.
    2. In the Property field, press the Down arrow key, and select the property name to which this custom claim is mapped.
  9. In the Security > Security configuration field, specify whether to process JSON Web Encryption (JWE) token for content decryption, or a signed JWT for a signature.
    • Signature verification – Specify how to use signature verification of the token by completing step 10.
    • Decryption – Specify how to decrypt the token by completing step 11.
    • Decryption and signature verification – Specify details for processing a token that has been signed and encrypted by completing step 10 and step 11.
    • None – Disable security by skipping steps 10 and 11.
  10. For JWT signature verification, in the JSON Web Signature (JWS) section, do the following steps. If you previously entered values on the Generation tab, some of these fields might be already populated.
    Choices Actions
    For asymmetric signature verification In the Truststore field, press the Down arrow key, and select the Truststore that is used for the JWT signature validation.
    For symmetric signature verification
    1. In the Keystore field, press the Down arrow key, and select an existing keystore name.
    2. In the Alias field, press the Down arrow key, and select the alias name of the private key in this keystore used to decrypt the JWT.
    3. In the Password field, enter the keystore password
  11. For JWE content decryption, in the JSON Web Decryption (JWE) section, do the following steps. If you previously entered values on the Generation tab, some of these fields might be already populated.
    1. In the Encryption type list, select either Asymmetric or Symmetric.
    2. In the Key encryption algorithm list, select an algorithm for decrypting the metadata.
    3. In the Keystore field, press the Down arrow key, and select the 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 decrypt the JWT.
    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.
  12. In the Token lifetime section, in the Allowed time to account for clock skew (in seconds) field, enter the time difference between two different servers that are out of sync.
  13. In the Advanced mapping section, in the Header as JSON string field, enter the clipboard property that the decoded header is assigned to and that can be used for any user-defined JWT processing logic.
  14. In the Payload as JSON string field, enter the clipboard property the decoded payload is assigned to and can be used for any user-defined JWT processing logic.
  15. Click Save.