Implementing Backend JWT Policy

[DDH13]

Requirement

When the Gateway receives a request we perform authentication, strip the token and pass the request onto the backend. Therefore, it is not possible for the backend to uniquely identify the client that is making the request.

Solution

When the backend-jwt policy is applied, upon an incoming request, the Gateway generates a new token retaining the information present in the incoming jwt, signs it and then passes it to the backend in a header, thereby enabling the backend to uniquely identify the client making the request

---

Implementation

The policy creates a newly signed JWT representing an already-authenticated user and injects it into a request header (e.g., x-jwt-assertion) so backend services can securely identify the caller.

4-Step Execution Flow

1. Resolve: Evaluates the request context to resolve any custom or mapped claims.
2. Look Up: Creates a token key (implementation pending) to check the in-memory cache for an existing token.
3. Generate & Sign: If no cached token exists, it creates a new JWT with standard and custom claims, signing it via the configured cryptographic key (RSA/ECDSA/None).
4. Inject: Attaches the signed JWT to the upstream request header.

Key Optimizations & Safeguards

• Half-Life Caching: Tokens are cached for exactly 50% of their lifespan (minimum 30s) to guarantee they survive network transit to the backend. A background sweeper clears expired tokens every 5 minutes to prevent memory leaks.
• Key Caching: Private keys are read from disk and parsed into memory only once, bypassing expensive file I/O on subsequent requests.
• Claim Protection: The policy strictly blocks configurations from overwriting reserved JWT protocol claims (like iss, sub, exp, or iat).

---

[DDH13]

Discussed Concerns 11/06/2026

Requiring a way to uniquely identify the client based on the incoming JWT

Application IDs are not present in the API Platform, we circumvent this by providing a claim mapping feature. We offer a claim mapping feature that allows the renaming of claims present in the incoming jwt and adding them to the generated jwt. A unique client-id that is passed down as a claim can then be renamed as required by the backend and included in the new token

[DDH13]

Discussed Concerns 12/06/2026

Prerequisites for the backend-jwt policy

Earlier implementation was dependent on there being a jwt-auth policy. We decided to move forward with an auth agnostic approach where the jwt would be generated for any auth type (including no-auth) with whatever information is passed down. If there is no auth enabled multiple clients may received the same token

Handling multiple Auth contexts

Currently there exists a limitation where auth failure will occur if multiple auth policies exist and the header does not match the latest applied auth policy. To accommodate for that when generating the backend-jwt we only take the latest auth context into account.

Requiring a unique key for the token cacheing

When a jwt is processed by the jwt-auth policy, the jti is not stored in the AuthContext. Similarly for API keys, the ID is not stored. This makes it difficult to cache the generated tokens efficiently since multiple fields need to be parsed, concatenated and hashed. We decided to solve this by modifying the AuthContext to include a TokenId field, and releasing a modified jwt-auth and api-key-auth policy where the TokenId is populated. This TokenId can then be used in combination with the path to create a unique key for the cache

[DDH13]

Discussed Concerns 15/06/20206

Optimal Token Cache Key Generation Method

We concatenate the TokenID along with path, method and operation to form a unique token. We create the TokenId for the following auth methods as follows. The TokenId creation must be implemented within each auth policy and passed into the Auth Context

1. jwt-auth -> JTI
2. api-key-auth -> Sha256(Api-key)
3. basic-auth -> Sha256(username, password)

Token-Cache-Key -> TokenID + path + method + operation

[DDH13]

Discussed Concerns 16/06/2026

Token Cache Key

If custom claims are defined by accessing the request context via $ctx, the above approach fails. We generate the key by considering whether claims exist or not. If they don't we concatenate TokenID + api Name + path + operation into a single string and use it as a key. If custom claims exist we concatenate the resolvedClaims to the above string and carry out a sha256 hash and use the result as the key

Adding Optional Dialects to prefix claims