jwt-generate

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

Gateway support

Table 1. Table showing which gateways support this policy, and the corresponding policy version
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 your OpenAPI source; for details on how to configure the policy in the assembly user interface, see Generate JWT.

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.

About

The jwt-generate policy has the following structure:
- jwt-generate:
  version: version
  title: title
  description: description
  jwt: json_web_token
  jti-claim: jwt_id_claim
  iss-claim: issuer_claim
  exp-claim: validity_period
  sub-claim: subject_claim
  aud-claim: audience_claim
  jws-jwk: sign_jwk_variable_name
  jws-alg: cryptographic_algorithm
  jws-crypto: sign_crypto_object
  custom-kid-value-jws: jws.kid
  jwe-enc: encryption_algorithm
  jwe-jwk: encrypt_jwk_variable_name
  jwe-alg: key_encryption_algorithm
  jwe-crypto: encrypt_crypto_object
  custom-kid-value-jwe: jwe.kid

Properties

The following table describes the policy properties:
Table 2. Generate JWT policy properties
Property Required Description Data type
version Yes The policy version number string
title No The title of the policy. string
description No A description of the policy. string
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
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
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
sub-claim No Runtime variable from which the Subject (sub) claim string can be retrieved. string
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
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 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
jws-jwk No Runtime variable that contains the JWK that is used to sign the JWT. 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. string
jws-alg No The cryptographic algorithm to use. Valid values are:
  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
  • ES256
  • ES384
  • ES512
  • PS256
  • PS384
  • PS512
 string
jws-crypto No The cryptographic object to use to sign the JWT. 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. string
custom-kid-value-jws No The customized kid value for JWT signing. string
jwe-enc No The encryption algorithm to use. Valid values are:
  • A128CBC-HS256
  • A192CBC-HS384
  • A256CBC-HS512
 string
jwe-jwk No Runtime variable that contains the JWK to use to encrypt the JWT. string
jwe-alg No The key encryption algorithm to use. Valid values are:
  • RSA1_5
  • RSA-OAEP
  • RSA-OAEP-256
  • dir
  • A128KW
  • A192KW
  • A256KW
 string
jwe-crypto No The cryptographic object to use to encrypt the claim. string
custom-kid-value-jwe No The customized kid value for JWT encryption. string

Example

The following is an example of a jwt-generate policy:
      - 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

For more information about how to use a jwt-generate security policy, see Generate JWT in the built-in policies section.