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

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
  jwe-enc: encryption_algorithm
  jwe-jwk: encrypt_jwk_variable_name
  jwe-alg: key_encryption_algorithm
  jwe-crypto: encrypt_crypto_object

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

Example

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

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