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.^¹	string
Cryptographic Algorithm	jws-alg	No	The cryptographic algorithm to use. Valid values are: HS256 HS384 HS512 RS256 RS384 RS512 ES256 ES384 ES512 PS256 PS384 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.^¹	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.

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