DataPower Gateway only[V5.0.1 or later]

Generate JWT (jwt-generate)

Use the Generate JWT security policy in IBM® API Connect to generate a JSON Web Token (JWT).

Restriction: The Generate JWT policy can be used only with the DataPower® Gateway.

About

JSON Web Token (JWT) is a compact, URL-safe way of representing claims that are to be transferred between two parties. The Generate JWT policy enables you to generate claims and configure whether they are to be used as the payload of a JSON Web Signature (JWS) structure, or as the plain text of a JSON Web Encryption (JWE) structure. Specifying the cryptographic material for both the JWS and the JWE produces a nested JWT that is both digitally signed and encrypted. The JWT is then assigned to the Authorization header as a Bearer token (the default option), or to the runtime variable in the JSON Web Token (JWT) property, if specified.

You can attach this policy to the following API flows:
  • REST
  • SOAP
Note:
  • For algorithm types HS256, HS384, and HS512 the cryptographic objects referenced must be a Shared Secret Key.
  • For algorithm types RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 the cryptographic objects referenced must be a Crypto Key (private key).
  • The cryptographic material can be provided through a JSON Web Key (JWK).
  • If both a cryptographic object and a JWK are specified, the cryptographic object is used to sign the JWT.

Prerequisites

The following prerequisites apply:
  • IBM API Connect Version 5.0.1 or later.
  • IBM DataPower V7.5 with the Application Optimization (AO) option.
  • If you are using one or more cryptographic objects, they must be located in the IBM API Connect domain on the DataPower appliance. The cryptographic objects must reference the Shared Secret Key or certificate that is needed to encrypt or sign the JWT contents.
  • If a JSON Web Key (JWK) is being used, it must be referenced by a runtime variable.

Properties

The following table lists the policy properties, indicates whether a property is required, specifies the valid and default values for input, and specifies the data type of the values.

Table 1. Generate JWT policy properties
Property label Property name Required Description Data type
Title title No The title of the policy.

The default value is jwt-generate.

string
Description description No A description of the policy. string
JSON Web Token (JWT) jwt No Runtime variable in which to place the JWT that is generated.

The default value is: generated.jwt. However, if not set, the JWT that is generated is written to the Authorization Header as a Bearer token.

string
JWT ID Claim jti-claim No Indicates whether a JWT ID (jti) claim should be added to the JWT.

If selected, the property is set to true, and a UUID is generated and set as the JTI claim value.

boolean
Issuer Claim iss-claim Yes Runtime variable from which the Issuer (iss) claim string can be retrieved. This claim represents the Principal that issued the JWT.

The default value is: iss.claim

string
Subject Claim sub-claim No Runtime variable from which the Subject (sub) claim string can be retrieved. string
Audience Claim aud-claim No Runtime variable from which the Audience (aud) claim string can be retrieved. Multiple variables are set by using a comma-separated string. string
Validity Period exp-claim Yes The length of time (in seconds), that is added to the current date and time, in which the JWT is considered valid.

The default value is 3600.

integer
Private Claims private-claims No Runtime variable from which a valid set of JSON claims can be retrieved. These claims are added to any set of claims specified previously. string
Sign JWK variable name jws-jwk No Runtime variable that contains the JWK that is used to sign the JWT.1 string
Cryptographic Algorithm jws-alg No The cryptographic algorithm to use. Valid values are:
  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
  • ES256
  • ES384
  • ES512
  • [V5.0.8 or later]PS256
  • [V5.0.8 or later]PS384
  • [V5.0.8 or later]PS512
Note: The following algorithms are not available in the drop-down list and must be added to the OpenAPI source manually:
  • PS256
  • PS384
  • PS512
For example:
- jwt-generate:
    title: jwt-generate
    iss-claim: iss.claim
    exp-claim: 3600
    version: 1.0.0
    jws-alg: PS256
For more information on specifying the OpenAPI source for the Generate JWT policy, see jwt-generate.
string
Sign Crypto Object jws-crypto No The cryptographic object to use to sign the JWT.1 string
Encryption Algorithm jwe-enc No The encryption algorithm to use. Valid values are:
  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
string
Encrypt JWK variable name jwe-jwk No Runtime variable that contains the JWK to use to encrypt the JWT. string
Key Encryption Algorithm jwe-alg No The key encryption algorithm to use. Valid values are:
  • RSA1_5
  • RSA-OAEP
  • RSA-OAEP-256
  • dir
  • A128KW
  • A192KW
  • A256KW
string
Encrypt Crypto Object jwe-crypto No The cryptographic object to use to encrypt the claim. string

Example

- jwt-generate:
    title: jwt-generate
    iss-claim: iss.claim
    exp-claim: 3600
    jwt: generated.jwt
    jti-claim: true
    sub-claim: sub.claim
    aud-claim: aud.claim
    private-claims: private.claims
    jws-jwk: jws.jwk
    jws-alg: HS256
    jws-crypto: jwsCryptoObjectName
    jwe-enc: A128CBC-HS256
    jwe-jwk: jwe.jwk
    jwe-alg: A128KW
    jwe-crypto: jweCryptoObjectName

Errors

The following error can be thrown while the policy is being executed:
  • RuntimeError - a generic error that captures all errors that occur during the execution of the policy. Upon failure, the detailed error message that is received from the underlying JOSE module is written to the default system log as an error message. This detailed error message is also assigned to the runtime variable jwt-generate.error-message, so it can be retrieved via catch.
If a catch is not configured, in the case of a failure the Generate JWT policy returns an HTTP code 500 Invalid-JWT-Generate failure. The detailed error message from the underlying JOSE module can be found in the system log.
Attention: If you are an API developer who is troubleshooting a failure that one of your customers had with your API, consider the security risks before sending a customer the exact content of the log message. You can avoid the possibility of someone launching an attack based on the information that they receive from the log message by sending the customer only general information about the message.
1 A JWK and a Crypto Object are both valid ways of providing the cryptographic data necessary to sign the JWT. However, if both data types are specified, only the Crypto Object is used.