Generate JWT
Use the Generate JWT security policy in IBM® API Connect to generate a JSON Web Token (JWT).
Gateway support
Gateway | Policy version |
---|---|
DataPower® Gateway (v5 compatible) | 1.0.0 |
DataPower API Gateway | 2.1.0 |
This topic describes how to configure the policy in the assembly user interface; for details on how to configure the policy in your OpenAPI source, see jwt-generate.
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.
- 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
- If you are using one or more cryptographic objects, they must be located in the 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.
Property label | Required | Description | Data type |
---|---|---|---|
Title | No | The title of the policy. The default value is |
string |
Description | No | A description of the policy. | string |
JSON Web Token (JWT) | No | Runtime variable in which to place the JWT that is generated. The default value is: |
string |
JWT ID Claim | No | Indicates whether a JWT ID (jti) claim should be added to the JWT. If selected, the property is set to |
boolean |
Issuer 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: |
string |
Subject Claim | No | Runtime variable from which the Subject (sub) claim string can be retrieved. | string |
Audience 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 | 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 |
integer |
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 | No | Runtime variable that contains the JWK that is used to sign the JWT.1 | string |
Cryptographic Algorithm | No | The cryptographic algorithm to use. Valid values are:
|
string |
Sign Crypto Object | No | The cryptographic object to use to sign the JWT.1 | string |
Sign KID value | No | The customized kid value for JWT signing. |
string |
Encryption Algorithm | No | The encryption algorithm to use. Valid values are:
|
string |
Encrypt JWK variable name | No | Runtime variable that contains the JWK to use to encrypt the JWT. | string |
Key Encryption Algorithm | No | The key encryption algorithm to use. Valid values are:
|
string |
Encrypt Crypto Object | No | The cryptographic object to use to encrypt the claim. | string |
Encrypt KID value | No | The customized kid value for JWT encryption. |
string |
Example
- jwt-generate:
version: 2.1.0
title: jwt-generate
description: New jwt-generate v2.1.0 policy.
jwt: generated.jwt
jti-claim: true
iss-claim: iss.claim
sub-claim: sub.claim
aud-claim: aud.claim
exp-claim: 3600
private-claims: private.claims
jws-jwk: jws.jwk
jws-alg: HS256
jws-crypto: jwsCryptoObjectName
custom-kid-value-jws: jws.kid
jwe-enc: A128CBC-HS256
jwe-jwk: jwe.jwk
jwe-alg: RSA1_5
jwe-crypto: jweCryptoObjectName
custom-kid-value-jwe: jwe.kid
Errors
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.
Invalid-JWT-Generate
failure. The detailed error message from the underlying JOSE
module can be found in the system log.