*This page
applies to **Apigee** and **Apigee hybrid**.*


*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*
![](https://fonts.gstatic.com/s/i/googlematerialicons/help/v13/gm_grey-24dp/1x/gm_help_gm_grey_24dp.png)

This topic provides general information about JWT (JSON Web
Token) and JWS (JSON Web Signature) and the Apigee JWS/JWT policies.

Both JWS and JWT are commonly used to share claims or assertions between connected
applications. The JWS/JWT policies enable Apigee API proxies to:

- **Generate** [a signed JWT](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/generate-jwt-policy.md.txt#generate-a-signed-jwt) or [a JWS](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/generate-jws-policy.md.txt), or [an encrypted JWT](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/generate-jwt-policy.md.txt#generate-an-encrypted-jwt).
- **Verify** [a signed JWT](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/verify-jwt-policy.md.txt#verify-a-signed-jwt) or [a JWS](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/verify-jws-policy.md.txt), or [an encrypted JWT](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/verify-jwt-policy.md.txt#verify-an-encrypted-jwt), and verify selected claims within the JWS/JWT.
- **Decode** [a signed or encrypted JWT](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/decode-jwt-policy.md.txt) or [a JWS](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/decode-jws-policy.md.txt) without validating the signature or decrypting the encrypted JWT or JWS. In the case of a JWS, the DecodeJWS policy can decode only the claims in the header of the JWS. In the case of an encrypted JWT, the DecodeJWT policy can decode only the unencrypted header.

In the latter two cases, the policy also sets [flow variables](https://docs.cloud.google.com/apigee/docs/api-platform/fundamentals/introduction-flow-variables.md.txt).
This allows subsequent policies in the Apigee flow to inspect the claims in the JWT or JWS, and to make decisions based on
those claims, or to propagate that information to the backend services.

When using the VerifyJWS or VerifyJWT policies, an invalid JWS/JWT will be rejected and will result in an error
condition. Similarly, when using the DecodeJWS or DecodeJWT policies, a malformed JWS/JWT will result in an error
condition.

> [!NOTE]
> **Note:** As stated in [IETF RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-1), JWTs are always represented using either the JWS Compact Serialization or the JWE Compact Serialization format, and the Apigee policies for handling JWTs support only those formats. As stated in [IETF RFC 7515](https://datatracker.ietf.org/doc/html/rfc7515#section-3.1), JWS can be represented in either Compact Serialization format or JSON Serialization format. The Apigee policies for handling JWS support only the Compact Serialization format.

## Use cases

You can use the JWS/JWT policies to:

- Generate a new JWS/JWT on either the proxy or target endpoint sides of an Apigee proxy. For example, you might create a proxy request flow that generates a JWS/JWT and returns it to a client. Or, you might design a proxy so that it generates a JWS/JWT on the target request flow, and attaches it to the request sent to the target. The JWS/JWT and its claims would then be available to enable backend services to apply further security processing.
- Verify and extract claims from a JWS/JWT obtained from inbound client requests, from target service responses, from Service Callout policy responses, or from other sources. For a signed JWS/JWT, Apigee will use one of the RSA, ECDSA, or HMAC algorithms to verify the signature, whether the JWS/JWT was generated by Apigee or a third party. For an encrypted JWT, Apigee will decrypt the JWT, using one of any of the supported JWA encryption algorithms (see [IETF RFC 7518](https://datatracker.ietf.org/doc/html/rfc7518)).
- Decode a JWS/JWT. Decoding is most useful when used in concert with the [Verify JWS/JWT
  policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/verify-jws-policy), in cases where the value of a claim (JWT) or header (JWS/JWT) within the JWS/JWT must be known before verifying a signed JWS/JWT or decrypting an encrypted JWT.

## Parts of a JWS/JWT

A signed JWS/JWT encodes information in three parts separated by dots:

```
Header.Payload.Signature
```

- The Generate JWS/JWT policy creates all three parts.
- The Verify JWS/JWT policy examines all three parts.
- The DecodeJWS policy examines the header only. The DecodeJWT policy examines the header and payload only.

A JWS also supports a *detached* form that omits the payload from the JWS:

```
Header..Signature
```

With a detached JWS, the payload is sent separately from the JWS. You use the
`<DetachedContent>` element of the Verify JWS policy to specify the raw, unencoded JWS payload.
The Verify JWS policy then verifies the JWS by using the header and signature in the JWS and the payload
specified by the `<DetachedContent>` element.

An encrypted JWT encodes information in five parts separated by dots:

```
Header.Key.InitializationVector.Payload.AuthenticationTag
```

The GenerateJWT and VerifyJWT policies will create or examine all of those parts.
The DecodeJWT can examine only the un-encrpted header.

To learn more about tokens and how they are encoded, and signed or encrypted, see the relevant
standards documents:

- **JWT** : [IETF RFC7519](https://tools.ietf.org/html/rfc7519)
- **JWS** : [IETF RFC7515](https://tools.ietf.org/html/rfc7515)

## Differences between JWS and JWT

You can use either a JWT or JWS to share claims or assertions between connected applications.
The major difference between the two is the representation of the payload:

- **JWT**
  - The payload is always a JSON object.
  - The payload is always attached to the JWT.
  - The `typ` header of the token is always set to `JWT`.
  - The payload may be either signed or encrypted.
- **JWS**
  - The payload can be represented by any format, such as a JSON object, byte stream, octet stream, and others.
  - The payload does not have to be attached to the JWS.
  - The header and payload are always signed. JWS does not support encryption.

Because the JWT format always uses a JSON object to represent the payload, the Apigee
GenerateJWT and VerifyJWT policies have built in support to handle common Registered Claim
Names, such as **aud** , **iss** , **sub** , and
others. That means you can use elements of the GenerateJWT policy to set these claims in the
payload, and elements of the VerifyJWT policy to verify their values. See the [Registered Claim
Names](https://tools.ietf.org/html/rfc7519#section-4.1) section of the JWT specification for more.

Along with supporting certain Registered Claim Names, the GenerateJWT policy directly
supports adding claims with arbitrary names to the payload or header of the JWT. Each claim is
a simple name/value pair, where the value can be of type `number`,
`boolean`, `string`, `map`, or `array`.

When using GenerateJWS, you supply a context variable that represents the payload. Because a
JWS can use any data representation for the payload, there is no concept of "payload claim" in
a JWS, and the GenerateJWS policy does not support adding claims with arbitrary names to the
payload. It is possible to use the GenerateJWS policy to add claims with arbitrary names to
the *header* of the JWS. Also, the JWS policies support a detached payload, where the
JWS omits the payload. A detached payload lets you send the JWS and payload separately. Using
a detached payload can be more space efficient especially for large payloads, and is required
by several security standards.

## Prevent template injection when using JWS and JWT

To prevent unauthorized data disclosure, follow these guidelines when using the GenerateJWT or
GenerateJWS policies:

- **Avoid direct references to user input:** Never use untrusted input (such as `request.queryparam.*` or `request.header.*`) directly in a `ref` attribute that supports templating.
- **Sanitize input:** If you must use external data in a JWT/JWS claim, first use an [AssignMessage policy](https://docs.cloud.google.com/apigee/docs/api-platform/reference/policies/assign-message-policy.md.txt) to strip any curly braces (`{ }`) or other template characters from the input before referencing it.
- **Use explicit claims for strings:** For simple string claims, avoid `type="map"`. Using the default `type="string"` prevents implicit templating of the referenced value.
- **Note the behavioral inconsistency between the verify and generate policies:** JWS and JWT generation policies behave differently than verify policies regarding templating.

  > [!WARNING]
  > **Important:** While the VerifyJWS and VerifyJWT policies do not apply message templating when resolving a variable via the `ref` attribute, the GenerateJWT and GenerateJWS policies do apply templating in specific configurations. Ensure your proxy logic accounts for this difference to avoid security vulnerabilities.

## Signing versus Encryption

Apigee can generate signed or encrypted JWT. Choose signed JWT when the payload need not be
secret, but it's important to provide integrity and non-repudiation guarantees to readers.
A signed JWT assures readers that the payload is has not changed since the JWT was signed and
that the JWT was signed by the holder of the private key. Choose encrypted JWT when the payload should be
secret. An encrypted JWT provides confidentiality for the payload, as only the appropriate key
holder can decrypt it.

It's possible to use both encrypted and signed JWT together, especially when the encrypted
JWT uses an asymmetric cryptography algorithm (RSA, ECDSA). In that case, the identity of
the producer of that JWT cannot be determined, because the encryption key is public.
To address that problem, combine signing with encryption. A typical pattern is as follows:

- Sign a payload to produce a JWS or signed JWT.
- Encrypt the signed result to produce an encrypted JWT.

Embedding a signed payload within an encrypted JWT using this approach provides both
non-repudiation and confidentiality guarantees. Apigee policies can produce
and decode \& verify such combinations.

## Signature algorithms

For signed JWT, the JWS/JWT Verification and JWS/JWT Generation policies support RSA,
RSASSA-PSS, ECDSA, and HMAC algorithms, using SHA2 checksums of bit strength 256, 384, or
512. The DecodeJWS and DecodeJWT policies work regardless of the algorithm that was used to
sign the JWS/JWT.

> [!NOTE]
> **Note:** All algorithms used by JWS/JWT, and the keys they require, are described in the JWA spec, [RFC 7518](https://tools.ietf.org/html/rfc7518).

### HMAC algorithms

The HMAC algorithms relies on a shared secret, known as the secret key, for creating the
signature (also known as signing the JWS/JWT) and for verifying the signature.

The minimum length of the secret key depends on the bit strength of the algorithm:

- HS256: 32 bytes minimum key length
- HS384: 48 bytes minimum key length
- HS512: 64 bytes minimum key length

### RSA algorithms

The RSA algorithms use a public/private key pair for the cryptographic signature. The JWA
specification uses the monikers RS256, RS384, and RS512 to represent these options. With RSA
signatures, the signing party uses an RSA private key to sign the JWS/JWT, and the verifying
party uses the matching RSA public key to verify the signature on the JWS/JWT. There are no
size requirements on the keys.

### RSASSA-PSS algorithms

The RSASSA-PSS algorithms are an update to the RSA algorithms, and use the monikers PS256,
PS384, and PS512. Like the RS\* variants, RSASSA-PSS uses an RSA public/private key pair for
the cryptographic signature. The format, mechanism, and size limits of the key is the same as
for the RS\* algorithms.

### ECDSA algorithms

The Elliptic Curve Digital Signature Algorithm (ECDSA) set of algorithms are
elliptic-curve cryptography algorithms with a P-256, P-384, or P-521 curve. When you use ECDSA
algorithms, the algorithm determines the type of public and private key you must specify:

| Algorithm | Curve | Key requirement |
|---|---|---|
| ES256 | P-256 | A key generated from the P-256 curve (also known as *secp256r1* or *prime256v1*) |
| ES384 | P-384 | A key generated from the P-384 curve (also known as *secp384r1*) |
| ES512 | P-521 | A key generated from P-521 curve (also known as secp521r1) |

## Encryption algorithms

When using GenerateJWT and VerifyJWT to handle encrypted JWT, the policies support these
algorithms:

- dir
- RSA-OAEP-256
- A128KW, A192KW, A256KW
- A128GCMKW, A192GCMKW, A256GCMKW
- PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW
- ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW

## Keys and Key Representations

The JOSE standards, covering JWS, signed and encrypted JWT, and more, describe how to use
cryptographic keys to sign or encrypt information. The foundational elements for any
cryptographic operation include the algorithm, and the key. Different algorithms
require different key types, and in some cases, different key sizes.

Symmetric algorithms, such as the HS\* family for signing, or the A128KW algorithm for
encryption, require symmetric or *shared* keys: the same key is used for signing and
verifying, or the same key is used for encrypting and decrypting. Asymmetric algorithms,
such as the RS\*, PS\*, and ES\* algorithms for signing, or the ECDH\* algorithms for
encrypting, use *key pairs* - there is a public key and a private key, and they are
matched. In signing, the signer uses the private key to sign, and any party can use the
public key to verify the signature. In encrypting, the encrypter uses the public key to
encrypt, and the decrypter uses the private key to decrypt. Public keys, as the name
suggests, are publicly shareable, and need not be kept secret.

There are different ways to serialize cryptographic keys into text format. Apigee policies
accept keys serialized in various forms: PEM encoded-form, JWKS form, or for shared keys,
UTF-8 encoded or base64 encoded form.

### PEM Format

For public or private keys, it is common to use PEM encoding, which is defined in [IETF RFC 7468](https://datatracker.ietf.org/doc/html/rfc7468). Here is an example
of a private key represented in PEM format:

    ---BEGIN PRIVATE KEY---
    MIGEAgEAMBAGByqGSM49AgEGBSuBBAAKBG0wawIBAQQgVcB/UNPxalR9zDYAjQIf
    jojUDiQuGnSJrFEEzZPT/92hRANCAASc7UJtgnF/abqWM60T3XNJEzBv5ez9TdwK
    H0M6xpM2q+53wmsN/eYLdgtjgBd3DBmHtPilCkiFICXyaA8z9LkJ
    ---END PRIVATE KEY---

There are similar PEM formats for public keys, or encrypted private keys.

### JWKS Format

A JSON Web Key (JWK) is a JSON data structure that represents a single cryptographic key. A
JSON Web Key Set (JWKS) is a JSON structure that represents a set of JWKs. JWK and JWKS are
described in [RFC7517](https://tools.ietf.org/html/rfc7517). See
JWKS examples at [Appendix A. Example JSON Web Key
Sets](https://tools.ietf.org/html/rfc7517#appendix-A.1).

JWKS is intended to allow any party to represent a set of keys in a standard format. A key
use-case is sharing public keys in a standard manner, via an HTTP endpoint that delivers
data in JWKS format. When a company or system that generates signed JWS or JWT, such as an
Identity Provider, publishes their public keys, any system or application that can read the
public keys, can verify signatures generated by the signing party. Conversely, any system or
app that wants to encrypt data that should be read only by a particular party or company,
can retrieve the public keys belonging to that party or company, and generate an encrypted
JWT for that purpose.

[RFC7517](https://tools.ietf.org/html/rfc7517) describes the JWKS
key elements for each key type, such as `RSA` or `EC`. These elements
should always be present:

- **kty** - The key type, such as `RSA` or `EC`.
- **kid** - the key ID. This can be any arbitrary unique string value; there should be no duplicates within a single key set. If the inbound JWT bears a key ID which is present in the set of JWKS, then the VerifyJWS or VerifyJWT policy will use the correct public key to verify the JWS/JWT signature.

Following are examples of optional elements and their values:

- **alg**: The key algorithm. It must match the signing algorithm in the JWS/JWT.
- **use**: The intended use of the key. Typical values are "sig" for signing and verification, or "enc" for encryption and decryption.

The following JWKS (originally retrieved from <https://www.googleapis.com/oauth2/v3/certs>, but out of date now) includes
the required elements and values, and would be usable by Apigee:

```
{
     "keys":[
        {
           "kty":"RSA",
           "alg":"RS256",
           "use":"sig",
           "kid":"ca04df587b5a7cead80abee9ea8dcf7586a78e01",
           "n":"iXn-WmrwLLBa-QDiToBozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt7-V7KDjCq0_Nkd-X9rMRV5LKgCa0_F8YgI30QS3bUm9orFryrdOc65PUIVFVxIwMZuGDY1hj6HEJVWIr0CZdcgNIll06BasclckkUK4O-Eh7MaQrqb646ghFlG3zlgk9b2duHbDOq3s39ICPinRQWC6NqTYfqg7E8GN_NLY9srUCc_MswuUfMJ2cKT6edrhLuIwIj_74YGkpOwilr2VswKsvJ7dcoiJxheKYvKDKtZFkbKrWETTJSGX2Xeh0DFB0lqbKLVvqkM2lFU2Qx1OgtTnrw",
           "e":"AQAB"
        },
        {
            "kty":"EC",
            "alg":"ES256",
            "use":"enc",
            "kid":"k05TUSt7-V7KDjCq0_N"
            "crv":"P-256",
            "x":"Xej56MungXuFZwmk_xccvsMpCtXmqhvEEMCmHyAmKF0",
            "y":"Bozpu4Y4ThKdwORWFXQa9I75pKOvPUjUjE2Bk05TUSt",
        }
     ]
  }
  
```

### Specifying keys to the JWS and JWT policies

Whether you are generating or verifying JWS or JWT, you need to provide a key for use within
the cryptographic operations.

When generating a signed JWT, you need to provide a key that can *produce* the
signature.

- In the case of an RS\*, PS\*, or ES\* signing algorithm, all of which use asymmetric keys, you must provide the private key to generate the signature.
- In the case of an HS\* algorithm, you need to provide the symmetric key that will be used when generating the signature.

When you verify a signed JWS/JWT, you need to provide a key that can *verify* the
signature.

- In the case of an RS\*, PS\*, or ES\* signing algorithm, you must provide the public key that is associated with the private key that was originally used to sign the token.
- In the case of an HS\* algorithm, you need to provide the same symmetric key that was used to sign the JWS or JWT.

You have two options for
providing the keys to the JWS and JWT policies:

- Provide the key value directly (typically via a context variable), or
- Provide the key indirectly, via a `kid` and a JWKS. You can specify the JWKS directly, or indirectly via an http URL at which Apigee can retrieve the JWKS.

The JWKS URL option is typically used only as a source of public keys that are usable with
asymmetric algorithms, because JWKS URLs will typically be public.

The following examples illustrate ways you can supply keys directly in various scenarios.

- Generate a JWT signed with the HS256 algorithm. The required
  key in this case is a symmetric key. This policy provides a context variable that contains
  the base64url-encoded secret key.

  ```xml
  <GenerateJWT name='gen-138'>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding='base64url'>
      <Value ref='private.secretkey'/>
      <Id ref='variable-containing-desired-keyid'/>
    </SecretKey>
    . . .
    <OutputVariable>output_variable_name</OutputVariable>
  </GenerateJWT>
  ```
- Verify a JWT signed with the HS256 algorithm. The required key in this case is a symmetric
  key. As in the above example, this policy provides a context variable that contains
  the base64url-encoded secret key.

  ```xml
  <VerifyJWT name='verify-138'>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding='base64url'>
      <Value ref='private.secretkey'/>
    </SecretKey>
    . . .
    <OutputVariable>output_variable_name</OutputVariable>
  </VerifyJWT>
  ```
- Verify a JWT that has been signed with the PS256 algorithm. The required key in this case
  is a public RSA key. This policy provides a context variable that contains the PEM-encoded
  public key.

  ```xml
  <VerifyJWT name='JWT-001'>
    <Algorithm>PS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
      <Value ref='variable-containing-pem-encoded-public-key'/>
    </PublicKey>
    . . .
  </VerifyJWT>
  ```
- Generate a JWT signed with the PS256 algorithm. The required key in this case is a private
  RSA key. This policy provides a context variable that contains the PEM-encoded private key.

  ```xml
  <GenerateJWT name='JWT-002'>
    <Algorithm>PS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
      <Value ref='private.variable-containing-pem-encoded-private-key'/>
    </PrivateKey>
     . . .
  </GenerateJWT>
  ```

### JWKS as a key source when verifying a JWS or signed JWT

When a system or app generates a JWS/JWT, typically the system or app inserts a Key
Identifier (the `kid` claim) into the JWS/JWT header. The key tells any reader
of the JWS/JWT which key is required to verify the signature on the signed JWS/JWT, or decrypt
the encrypted JWT.

As an example, suppose an issuer signs a JWT with a private key. The "Key ID" identifies the
matching public key that must be used to verify the JWT. The list of public keys is typically
available at some well-known endpoint, such as the
[Google Identity endpoint](https://www.googleapis.com/oauth2/v3/certs)
or the [Firebase Authentication endpoint](https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com).
Other providers will have their own public endpoints that publish keys in JWKS format.

When using Apigee to verify a JWS or signed JWT with public keys that are shared via a JWKS
endpoint, you have some options:

- **Option 1** : In the policy configuration, specify the JWKS endpoint uri in
  the `<PublicKey/JWKS>` element. For example, for the VerifyJWT policy:

  ```xml
  <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <JWKS uri="https://www.googleapis.com/oauth2/v3/certs"/>
    </PublicKey>
    . . .
  </VerifyJWT>
  ```

  In this case, Apigee will:
  1. Examine the JWS/JWT header to find the signing algorithm (alg), such as RS256, and reject the inbound JWT if that algorithm does not match the algorithm configured in the policy.
  2. Retrieve the list of keys with their IDs from the specified JWKS endpoint, or from an internal cache if this JWKS endpoint has been used before.
  3. Examine the JWS/JWT header to find the Key ID (kid). If the inbound JWT does not include a key ID (kid) in the header, then the mapping of kid to verification-key is not possible, and Apigee will throw a fault.
  4. Extract from the JWKS, the JWK with the key ID noted in the JWS/JWT header. Throw a fault if a key with that key ID is not present.
  5. Check that the algorithm for the JWK matches the algorithm specified in the policy configuration. Reject the verification and throw a fault if the algorithms do not match.
  6. Use that public key to verify the signature on the JWS/JWT. Reject the verification and throw a fault if the signature does not verify.
- **Option 2** : In the policy configuration, specify a variable that holds the
  JWKS endpoint uri in the `<PublicKey/JWKS>` element.

  For example, for the VerifyJWT policy:

  ```xml
  <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
      <JWKS uriRef="variable-containing-a-uri"/>
    </PublicKey>
    . . .
  </VerifyJWT>
  ```

  In this case, Apigee will perform the same steps as above, except that Apigee will retrieve
  the JWKS not from a hard-coded URI, but from the uri specified in the variable referenced
  by the `uriRef` attribute. Caching still applies.

  > [!NOTE]
  > **Note:** Take care when using the `uriRef` attribute. As the proxy designer, you are responsible for insuring that you do not configure your verification policies to trust unvetted URIs. For example, it would be an insecure practice if you were to decode the inbound JWS or JWT, retrieve a JWKS URI from the header, and then verify the JWS or JWT from that URI, without first verifying that the URI is on a trusted list.

- **Option 3** : In the policy configuration, specify a variable that holds the
  hard-coded JWKS data in the `<PublicKey/JWKS>` element.

  For example, for the VerifyJWT policy:

  ```xml
  <VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>json.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
      <JWKS ref="variable-that-holds-a-jwks"/>
    </PublicKey>
    . . .
  </VerifyJWT>
  ```

  In this case, Apigee will perform the same steps as above, except that Apigee will retrieve
  the JWKS not from a URI, but from the context variable that you specify in
  the `ref` attribute. Typically you would have loaded this context variable
  from a ServiceCallout, a KVM, or a properties file associated to the proxy.

  > [!NOTE]
  > **Note:**If you use a ServiceCallout to retrieve the JWKS, it's a good practice to cache the JWKS to avoid executing the ServiceCallout on every request.

### JWKS as a key source when generating an encrypted JWT

When you generate an encrypted JWT via an asymmetric algorithm (RSA-OAEP-256 or any of the
ECDH-\* variants) you use the public key to encrypt. You have options for
providing the key to the GenerateJWT policy

A typical approach is to specify in the policy configuration the JWKS endpoint uri in the
`<PublicKey/JWKS>` element. For example:

```xml
<GenerateJWT name="GJWT-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS uri='https://www.example.com/.well-known/jwks.json'/>
    <Id ref='variable-containing-desired-keyid'/>
  </PublicKey>
    . . .
</GenerateJWT>
```

In this case, Apigee will:

1. Assemble the un-encoded payload and header for the JWT based on the policy configuration.
2. Retrieve the list of keys with their IDs from the specified JWKS endpoint, or from an internal cache if this JWKS endpoint has been used before. Currently the cache TTL is 5 minutes.
3. Extract the JWK with the key ID noted in the `PublicKey/Id` element from the JWKS. Throw a fault if a key with that key ID is not present.
4. Check that the algorithm for the JWK matches the algorithm specified in the policy configuration. Throw a fault if the algorithms do not match.
5. Generate a random sequence to be used as the content-encryption key.
6. Use the selected public key to encrypt the content encryption key.
7. Use the content encryption key to encrypt the payload.
8. Finally, assemble all the parts into a serialized encrypted JWT.

An alternative is to use the `uriRef` attribute to specify a variable that
holds the URI of a JWKS endpoint. For example:

```xml
<GenerateJWT name="GJWT-1">
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <PublicKey>
    <JWKS uriRef='variable-containing-jwks-uri'/>
    <Id ref='variable-containing-desired-keyid'/>
  </PublicKey>
  . . .
</GenerateJWT>
```

In this case, Apigee will perform the same steps as above, except that Apigee will retrieve the
JWKS from the uri specified in the variable referenced by the `uriRef` attribute,
instead of a hard-coded URI. Apigee will read the JWKS from an internal
cache if this JWKS endpoint has been used before.