GenerateJWT policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

What

Generates a signed JWT or an encrypted JWT, with a configurable set of claims. The JWT can then be returned to clients, transmitted to backend targets, or used in other ways. See JWS and JWT policies overview for a detailed introduction.

This policy is an Extensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, see Policy types.

How

Whether the policy generates a signed or encrypted JWT depends on the element you use to specify the algorithm that generates the JWT:

• If you use the <Algorithm> element, the policy generates a signed JWT.
• If you use the <Algorithms> element, the policy generates an encrypted JWT.

Video

Watch a short video to learn how to generate a signed JWT.

Generate a Signed JWT

This section explains how to generate a signed JWT. For a signed JWT, use the <Algorithm> element to specify the algorithm for signing the key.

Samples for a signed JWT

The following samples illustrate how to generate a signed JWT.

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Type>Signed</Type>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

{
  "typ" : "JWT",
  "alg" : "HS256",
  "kid" : "1918290"
}

{
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-JWT-policy-test",
  "aud" : "fans",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

<GenerateJWT name="JWT-Generate-RS256">
    <Type>Signed</Type>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

The samples above use the <Algorithm> element, so they generate a signed JWT. The <PrivateKey> element specifies the cryptographic key used to sign the JWT. There are other key elements as well. Which one you use depends on the algorithm specified by the value of <Algorithm>, as described in the next section.

Setting the key elements for a signed JWT

Use exactly one of the following elements to specify the key used to generate a signed JWT:

• <SecretKey>
• <PrivateKey>

Which element you use depends on the chosen algorithm, as shown in the following table:

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id ref="secretkey-id">key-1918290</Id>
</SecretKey>

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="privatekey-id">key-1918290</Id>
</PrivateKey>

In the examples above, the <Password> and <Id> elements are optional.

For more on the key requirements, see About signature encryption algorithms.

Generate an encrypted JWT

This section explains how to generate an encrypted JWT. For an encrypted JWT, use the <Algorithms> element to specify the algorithms for signing the key and content.

Sample for an encrypted JWT

The following sample shows how to generate an encrypted JWT. The sample uses the <Algorithms> element, so it generates an encrypted JWT.

<GenerateJWT name="gjwt-1">
  <Type>Encrypted</Type>
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <PublicKey>
    <Value ref="rsa_publickey"/>
  </PublicKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

<GenerateJWT name='gjwt-2'>
  <Algorithms>
    <Key>A128KW</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <SecretKey>
    <Value ref='private.secretkey'/>
  </SecretKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

Setting the key elements for an encrypted JWT

Use exactly one of the following elements to specify the encryption key for GenerateJWT, when you want to generate an encrypted JWT:

• <PublicKey>
• <SecretKey>
• <PasswordKey>
• <DirectKey>

Which element you use depends on the chosen key encyryption algorithm, as shown in the following table:

<PublicKey>
  <Value ref="rsa_publickey"/>
</PublicKey>

<PublicKey>
  <Value ref="ec_publickey"/>
</PublicKey>

<SecretKey>
  <Id>optional key identifier here</Id>
  <Value ref="private.secretkey"/>
</SecretKey>

<PasswordKey>
  <Id>optional key identifier here</Id>
  <Value ref="private.passwordkey"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>

<DirectKey>
  <Id>optional key identifier here</Id>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

For more on the key requirements, see About signature encryption algorithms.

Element reference for Generate JWT

The policy reference describes the elements and attributes of the Generate JWT policy.

Note: Configuration will differ somewhat depending on the encryption algorithm you use. Refer to Samples for a signed JWT or Sample for an encrypted JWT for examples that demonstrate configurations for specific use cases.

Attributes that apply to the top-level element

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

The following attributes are common to all policy parent elements.

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

Use in addition to the name attribute to label the policy in the Apigee UI proxy editor with a different, natural-language name.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Specifies the cryptographic algorithm used to sign the token. Use the <Algorithm> element to generate a signed JWT.

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithm>

Specifies the cryptographic algorithms for the key and content encryption. Use the <Algorithms> element to generate an encrypted JWT.

Child elements of <Algorithms>

The following table provides a high-level description of the child elements of <Algorithms>:

Key encryption algorithms

The following table lists the available algorithms for key encryption.

See Generate an encrypted JWT for an example in which the key encryption algorithm is RSA-OAEP-256, so you use the <PublicKey> element with value that resolves to an RSA Public key.

Content encryption algorithms

The following algorithms (symmetric, AES-based) are available for content encryption:

• A128CBC-HS256
• A192CBC-HS384
• A256CBC-HS512
• A128GCM
• A192GCM
• A256GCM

For more information on all of these algorithms, see RFC7518.

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

The policy generates a JWT containing an aud claim set to the specified value. This claim identifies the recipients that the JWT is intended for. This is one of the registered claims mentioned in RFC7519.

<AdditionalClaims/Claim>

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Lets you specify additional claim name/value pair(s) in the payload of the JWT. You can specify the claim explicitly as string, a number, a boolean, a map, or an array. A map is simply a set of name/value pairs.

The <Claim> element takes these attributes:

• name - (Required) The name of the claim.
• ref - (Optional) The name of a flow variable. If present, the policy will use the value of this variable as the claim. If both a ref attribute and an explicit claim value are specified, the explicit value is the default, and is used if the referenced flow variable is unresolved.
• type - (Optional) One of: string (default), number, boolean, or map
• array - (Optional) Set to true to indicate if the value is an array of types. Default: false.

When you include the <Claim> element, the claim names are set statically when you configure the policy. Alternatively, you can pass a JSON object to specify the claim names. Because the JSON object is passed as a variable, the claim names in the generated JWT are determined at runtime.

For example:

<AdditionalClaims ref='json_claims'/>

Where the variable json_claims contains a JSON object in the form:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

The generated JWT includes all of the claims in the JSON object.

<AdditionalHeaders/Claim>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Puts the additional claim name/value pair(s) in the header for the JWT.

The <Claim> element takes these attributes:

• name - (Required) The name of the claim.
• ref - (Optional) The name of a flow variable. If present, the policy will use the value of this variable as the claim. If both a ref attribute and an explicit claim value are specified, the explicit value is the default, and is used if the referenced flow variable is unresolved.
• type - (Optional) One of: string (default), number, boolean, or map
• array - (Optional) Set to true to indicate if the value is an array of types. Default: false.

<Compress>

<Compress>true</Compress>

Specifies whether text is compressed before encrypting. This element is valid only when generating an encrypted JWT.

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Adds the critical header, crit, to the JWT header. The crit header is an array of header names that must be known and recognized by the JWT receiver. For example:

{
  "typ": "...",
  "alg" : "...",
  "crit" : [ "a", "b", "c" ],
}

According to the specification, verifying parties must examine the crit header and verify that each of those headers is understood. For example, the VerifyJWT policy examines the crit header. For each item listed in the crit header, it checks that the <KnownHeaders> element of the VerifyJWT policy also lists that header. Any header that the VerifyJWT policy finds in crit that is not also listed in <KnownHeaders> causes the VerifyJWT policy to fail.

<CustomClaims>

Note: Currently, a CustomClaims element is inserted when you add a new GenerateJWT policy through the UI. This element is not functional and is ignored. The correct element to use instead is <AdditionalClaims>. The UI will be updated to insert the correct elements at a later time.

<DirectKey>

<DirectKey>
  <Id>A12345</Id>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

Specifies a direct key for encrypting a JWT when the encryption algorithm is dir ("direct encryption").

Child elements of <DirectKey>

The following table provides a high-level description of the child elements of <DirectKey>:

With direct key encryption, you can directly supply a series of bytes that will act as the content encryption key (CEK). You must specify the byte array as an encoded string. The required length of the byte array depends on the strength of the content encryption algorithm selected. For example, for A256CBC-HS512, you must supply a key of exactly 512 bits, or 64 bytes.

The contents of the variable private.directkey must be a string that is encoded, either via hex (base16), base64, or base64url. For example, here is a hex-encoded 32-byte key:

96 4b e1 71 15 71 5f 87 11 0e 13 52 4c ec 1e ba df 47 62 1a 9d 3b f5 ad d2 7b b2 35 e7 d6 17 11

For the hex encoding, whitespace is accepted but not required, and upper or lowercase is accepted (B7 is the same as b7).

The base64url-encoded equivalent of the above is:

lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE

For the base64* variants, whitespace is not accepted, and case matters. If you don't specify an encoding, the policy assumes the encoding is base64.

The following describes the length of keys required:

Note: The content-encryption key provided via the <DirectKey> element must be exactly the right length for the specified content-encryption algorithm. For any key-encryption algorithm other than dir, the policy generates a random CEK that is the right length, but for dir, the configuration needs to supply a key with the right size explicitly.

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

or:

<ExpiresIn ref='time-value-here'/>

Specifies the lifespan of the JWT in milliseconds, seconds, minutes, hours, or days. Specify the expiration using either the XML element or the ref attribute, but not both.

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Generates a JWT with the specific jti claim. When the text value and ref attribute are both empty, the policy will generate a jti containing a random UUID. The JWT ID (jti) claim is a unique identifier for the JWT. For more information on jti, refer to RFC7519.

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

Set to false if you want the policy to throw an error when any referenced variable specified in the policy is unresolvable. Set to true to treat any unresolvable variable as an empty string (null).

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

The policy generates a JWT containing a claim with name iss, with a value set to the specified value. A claim that identifies the issuer of the JWT. This is one of the registered set of claims mentioned in RFC7519.

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Specifies the time when the token becomes valid. The token is invalid until the specified time. You can specify either an absolute time value, or a time relative to when the token is generated.

Valid time values for the NotBefore element for absolute time values

For relative time values, specify an integer and a time period, for example:

• 10s
• 60m
• 12h

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

Specifies where to place the JWT generated by this policy. By default it is placed into the flow variable jwt.POLICYNAME.generated_jwt.

<PasswordKey>

<PasswordKey>
  <Id>abcdefg</Id>
  <Value ref="private.password"/>
  <SaltLength>8</SaltLength>
  <PBKDF2Iterations>10000</PBKDF2>
</PasswordKey>

Specifies a key for encrypting a JWT when the encryption algorithm is one of the following:

• PBES2-HS256+A128KW
• PBES2-HS384+A192KW
• PBES2-HS512+A256KW

For each of these key algorithms, you must supply a password from which the key encryption key is derived, via the variable private.password in the element <Value ref="private.password"/>.

Child elements of <PasswordKey>

The following table provides a high-level description of the child elements of <PasswordKey>:

<PrivateKey>

<PrivateKey>
  <Id ref="privatekey-id"/>
  <Value ref="private.pem-encoded-privatekey"/>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Specifies the private key to use when generating a signed JWT, and the Algorithm is an RSA or elliptic curve (EC) variant - one of RS256/RS384/RS512, PS256/PS384/PS512, or ES256/ES384/ES512.

Child elements of <PrivateKey>

The following table provides a description of the child elements of <PrivateKey>:

<PublicKey>

<PublicKey>
  <!-- specify exactly one of the following -->
  <Value ref="variable-containing-encoded-publickey"/>
  <Value>PEM encoded public key</Value>
  <Certificate ref="variable-containing-encoded-x509-certificate"/>
  <Certificate>PEM encoded X509 certificate</Certificate>
  <JWKS>jwks-content</JWKS>
  <JWKS ref="variable-containing-jwks-content"/>
  <JWKS uri="variable-containing-jwks-content"/>
  <JWKS uriRef="variable-containing-uri"/>
</PublicKey>

Specifies the public key to use when generating an encrypted JWT, and the Key algorithm is an RSA or elliptic curve (EC) variant - RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, or ECDH-ES+A256KW.

Child elements of <PublicKey>

Provide exactly one of Value, Certificate, or JWKS. If you specify JWKS, you must also specify Id. The following table provides a description of these child elements of <PublicKey>:

<PublicKey>
  <Value ref="public.publickey"/>
</PublicKey>

<PublicKey>
  <Value>
   -----BEGIN PUBLIC KEY-----
   MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
   2F73IyN....your key will vary....1jC0dwUD1lHV8MfUyRXmpmnNxJHACof
   C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
   ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
   DQIDAQAB
   -----END PUBLIC KEY-----
  </Value>
</PublicKey>

<PublicKey>
 <Certificate ref="public.pem-encoded-certificate"/>
</PublicKey>

<PublicKey>
  <Certificate>
  -----BEGIN CERTIFICATE-----
  MIIDqDCCApACCQCG/xVb7Yzw3zANBgkqhkiG9w0BAQUFADCBlTELMAkGA1UEBhMC
  2F73IyN....your certificate data will vary....1jC0dwUD1lHV8MfUyR
  VQQKDAZHb29nbGUxDzANBgNVBAsMBkFwaWdlZTEaMBgGA1UEAwwRYXBpZ2VlLmdv
  ...
  YjBaZuNUDVLGvbTSRgWG5lwm85Jar2zeCBcxFDwqyZFvVNV9SfoWF/LgVVpK54n8
  rknZ17USb0ob51ckxPTENmF2DUHBzgptiw10Yw==
  -----END CERTIFICATE-----
  </Certificate>
</PublicKey>

<PublicKey>
  <JWKS uri="uri-that-returns-a-jwks"/>
  <Id ref="variable-containing-a-kid">literal-value-here</Id>
</PublicKey>

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
 <Id ref="variable-containing-key-id-here">secret-key-id</Id>
 <Value ref="private.variable-here"/>
</SecretKey>

The SecretKey element is optional. It specifies the secret key to use when generating a signed JWT that uses a symmetric (HS*) algorithm or when generating an encrypted JWT that uses a symmetric (AES) algorithm for key encryption.

Children of <SecretKey>

The following table provides a description of the child elements and attributes of <SecretKey>:

<SecretKey encoding="VALUE_HERE" >
 <Id ref="variable-containing-key-id-here">secret-key-id</Id>
 <Value ref="private.secretkey"/>
</SecretKey>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
 <Value ref="private.variable-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
 <Value ref="private.variable-here"/>
</SecretKey>

<SecretKey>
 <Id ref="flow-variable-name-here"/>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

<Subject>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

For example:

<Subject ref="apigee.developer.email"/>

The policy generates a JWT containing a sub claim, set to the specified value.This claim identifies or makes a statement about the subject of the JWT. This is one of the standard set of claims mentioned in IETF RFC 7519.

<Type>

<Type>type-string-here</Type>

Describes whether the policy generates a signed JWT or an encrypted JWT. The <Type> element is optional. You can use it to inform readers of the configuration whether the policy generates a signed or an encrypted JWT.

• If the <Type> element is present:
  • If the value of <Type> is Signed, the policy generates a signed JWT, and the <Algorithm> element must be present.
  • If the value of <Type> is Encrypted, the policy will generate an encrypted JWT, and the <Algorithms> element must be present.
• If the <Type> element is absent:
  • If the <Algorithm> element is present, the policy assumes <Type> is Signed.
  • If the <Algorithms> element is present, the policy assumes <Type> is Encrypted.
• If neither <Algorithm> nor <Algorithms> is present, the configuration is invalid.

Flow variables

The Generate JWT policy does not set flow variables.

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>