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

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.