Generate JWT (jwt-generate)
Use the Generate JWT security policy in IBM® API Connect to generate a JSON Web Token (JWT).
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.
- 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.
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||Property name||Required||Description||Data type|
|Title||title||No||The title of the policy.
The default value is
|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:
|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
|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:
|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
|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:
Note: The following algorithms are not available in the drop-down list and must be added to the OpenAPI source manually:
For more information on specifying the OpenAPI source for the Generate JWT policy, see jwt-generate.
|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:
|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:
|Encrypt Crypto Object||jwe-crypto||No||The cryptographic object to use to encrypt the claim.||string|
- 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
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-Generatefailure. The detailed error message from the underlying JOSE module can be found in the system log.