JWT claims to HTTP headers — verified-claim routing on kgateway and agentgateway

Step 1 Request arrives

The client sends a normal HTTPS request with Authorization: Bearer <jwt>. kgateway terminates TLS at the listener.

Step 2 Verify signature against the IdP's JWKS

kgateway fetches the public signing keys from remoteJwks.url (cached for cacheDuration: 300s), checks the JWT signature, and validates exp / iss / aud. Tampered, expired, or unsigned tokens get a 401 at this step — they never reach the backend.

Step 3 claimsToHeaders — lift verified claims into headers

Once the signature is valid, kgateway copies named claims out of the verified payload into request headers, in order:

claimsToHeaders:
- { claim: tenantId, header: x-tenant-id }
- { claim: sub,      header: x-user-id }

Result on the wire heading downstream:

GET /api/v1/orders HTTP/1.1
x-tenant-id: tnt_acme
x-user-id:   user_abc123

Step 4 Forward to the backend

kgateway forwards the request. The backend sees the verified-claim headers and can trust them — they only exist because the gateway wrote them after a successful signature check. The app never has to crack open a JWT itself, and the bearer token can be stripped before the hop.

Frontegg AuthConfig + EnterpriseKgatewayTrafficPolicy

Same two-CRD shape as section 4, just with Frontegg's JWKS URL pinned in. The Frontegg tenant subdomain goes in the remoteJwks.url; everything downstream (HTTPRoute matches, rate-limit descriptors, app code) continues to key off x-tenant-id and x-user-id without knowing which IdP minted the token.

apiVersion: extauth.solo.io/v1
kind: AuthConfig
metadata:
  name: frontegg
  namespace: kgateway-system
spec:
  configs:
  - oauth2:
      accessTokenValidation:
        jwt:
          remoteJwks:
            url: https://<tenant>.frontegg.com/.well-known/jwks.json
            cacheDuration: 300s
        claimsToHeaders:
        - { claim: tenantId, header: x-tenant-id }
        - { claim: sub,      header: x-user-id }
---
apiVersion: enterprisekgateway.solo.io/v1alpha1
kind: EnterpriseKgatewayTrafficPolicy
metadata:
  name: frontegg
  namespace: kgateway-system
spec:
  targetRefs:
  - { group: gateway.networking.k8s.io, kind: Gateway, name: http }
  entExtAuth:
    authConfigRef:
      name: frontegg
      namespace: kgateway-system

Pitfall The claim name is whatever the IdP says it is

RFC 7519 defines a handful of registered claims — iss / sub / aud / exp / nbf / iat / jti — and the OIDC Core 1.0 spec extends that with a fixed set of identity claims for ID tokens (email, preferred_username, name, etc.). Tenant identity is not in either spec — every IdP names and shapes it differently. Always decode a real token from the IdP (jwt.io, step crypto jwt inspect, or jq) and confirm the exact claim name and value shape before pinning it in claimsToHeaders:

Pitfall Don't trust client-supplied x-tenant-id

A client sending x-tenant-id: tnt_competitor on a request must not influence routing or authentication. kgateway has two documented mechanisms here — use both:

1 · Overwrite via claimsToHeaders default. Each claimsToHeaders entry has an append field that defaults to false. Per Solo's field reference: "If false (default), overwrite the header. Do not set to true on public-facing gateways as it trusts incoming headers." So as long as you leave append unset (or false), the verified-claim value clobbers anything the client sent.

2 · Strip before route selection and ext-auth with ListenerPolicy.earlyRequestHeaderModifier. This is kgateway's documented defence-in-depth pattern — the headers get removed at the listener, before route matching or authentication run, so they cannot influence either:

apiVersion: gateway.kgateway.dev/v1alpha1
kind: ListenerPolicy
metadata:
  name: strip-claim-headers
  namespace: kgateway-system
spec:
  targetRefs:
  - { group: gateway.networking.k8s.io, kind: Gateway, name: http }
  default:
    httpSettings:
      earlyRequestHeaderModifier:
        remove:
        - x-tenant-id
        - x-user-id

Either alone is sufficient for the smuggling case — the ListenerPolicy is the cleaner of the two because the header is gone by the time any other filter looks at it, and the intent is explicit in YAML rather than relying on a default. See Solo's Early Request Header Modification docs for the full filter-chain ordering.

Pitfall JWKS fetch is a hard dependency

If the IdP's JWKS endpoint is unreachable when kgateway boots and has no cached key, signature validation fails closed and every request gets a 401. cacheDuration: 300s gives you a five-minute survival window after a successful fetch — set it deliberately based on how often the IdP rotates keys and how long a JWKS outage you're willing to ride out.

Case 1 Missing token

No Authorization header at all. JWT validation refuses the request because there is nothing to verify.

$ curl -is https://gw.example.com/api/v1/orders | head -3
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer realm="http"
content-length: 14

Jwt is missing

Access log: response_code=401, response_code_details=jwt_authn_access_denied.

Case 2 Tampered signature

Use $TAMPERED_JWT from §7.0 — a valid token with one byte flipped in the signature segment. The JWKS key loads correctly; the signature no longer matches the header + payload digest, so verification fails.

$ curl -is -H "Authorization: Bearer $TAMPERED_JWT" \
    https://gw.example.com/api/v1/orders | head -4
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer realm="http"
content-length: 23

Jwt verification fails

The bytes never reach claimsToHeaders, so x-tenant-id is never written and the backend never sees the request.

Case 3 Expired token

Use $EXPIRED_JWT from §7.0 — same key, same audience, but exp is one hour in the past. Signature verifies; the time check rejects.

$ curl -is -H "Authorization: Bearer $EXPIRED_JWT" \
    https://gw.example.com/api/v1/orders | head -4
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer realm="http"
content-length: 14

Jwt is expired

Case 4 Wrong audience

$WRONG_AUD_JWT carries aud=api.other.com, which is not in the audiences list on the AuthConfig. Signature and time are both valid; the audience check still rejects.

$ curl -is -H "Authorization: Bearer $WRONG_AUD_JWT" \
    https://gw.example.com/api/v1/orders | head -4
HTTP/1.1 403 Forbidden
www-authenticate: Bearer realm="http", error="invalid_token"
content-length: 32

Audiences in Jwt are not allowed

The simplest defence against token replay across APIs. If the aud on the token does not name this gateway's audience, the gateway rejects it before claim mapping or routing happens.

Case 5 Wrong issuer

$WRONG_ISS_JWT claims iss=https://other-idp.example.com, which has no entry in the AuthConfig. The gateway has no JWKS configured for that issuer so the token cannot be verified.

$ curl -is -H "Authorization: Bearer $WRONG_ISS_JWT" \
    https://gw.example.com/api/v1/orders | head -4
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer realm="http"
content-length: 28

Jwt issuer is not configured

Case 6 Client tries to smuggle x-tenant-id

The client sends $VALID_JWT (which has tenantId=tnt_acme) and adds an x-tenant-id: tnt_competitor header on the same request, hoping to swap tenants after the auth check. With the defaults described in section 6 (or a ListenerPolicy stripping the header at the listener), the smuggled value never reaches routing or the backend.

$ curl -is \
    -H "Authorization: Bearer $VALID_JWT" \
    -H "x-tenant-id: tnt_competitor" \
    https://gw.example.com/headers
HTTP/1.1 200 OK
content-type: application/json

{
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJSUzI1NiIs...",
    "X-Tenant-Id": "tnt_acme",
    "X-User-Id":   "user_abc123"
  }
}

The proof is the X-Tenant-Id value at the backend. Use httpbin's /headers endpoint (or any echo backend) so you can read exactly what the upstream saw. tnt_competitor never appears.

Case 7 Token is valid but missing the tenant claim

$NO_TENANT_JWT is signed correctly and the audience matches, but the IdP omitted tenantId. JWT validation passes; claimsToHeaders has nothing to copy for that mapping.

$ curl -is -H "Authorization: Bearer $NO_TENANT_JWT" \
    https://gw.example.com/headers
HTTP/1.1 200 OK
content-type: application/json

{
  "headers": {
    "Authorization": "Bearer eyJhbGciOiJSUzI1NiIs...",
    "X-User-Id":     "user_abc123"
  }
}

The gateway lets the request through and the backend has to decide what to do with a missing tenant. The simplest backstop is a second HTTPRoute match that requires the header to exist and returns 400 if it does not, so a misconfigured IdP cannot silently bypass tenant scoping.