[Automated] Draft docs (agentgateway): fix(jwt): select providers by issuer and kid

[github-actions]

agentgateway/agentgateway#3611 — fix(jwt): select providers by issuer and kid

Docs versions: standalone/main, kubernetes/main

What changes for users: JWT authentication now selects a provider by both the token's iss claim and kid header before validation. Multi-tenant deployments can use issuers that publish the same kid value without the gateway validating a token against the wrong issuer.

What the docs now say: The JWT overview, Kubernetes JWT setup guide, and standalone JWT authentication page now explain that provider selection uses iss and kid, and why that matters when multiple JWT providers are configured.

Not verified: No cluster commands were run in this sandbox; the configuration is unrun.

How agentgateway-3611 was drafted, and what was not verified

• Code PR: fix(jwt): select providers by issuer and kid agentgateway#3611
• Code issue: jwtAuthentication with multiple providers only ever validates against the first provider that has the token's kid agentgateway#3609
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main and kubernetes/main
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Document the multi-provider JWT selection behavior on the JWT pages named by the code-path rule.
• Learned: jwt-setup.md already has a Multiple JWT providers section, and jwt-authn.md carries the matching standalone claim semantics.
• Did: Added scoped notes to the Kubernetes shared JWT overview and setup content, added the standalone note in the main tree, and wrote a proposed release note.

Why a documentation change is necessary

The diff changes JWT validation so provider selection uses the unverified iss claim together with the kid header before signature and claim validation. The target pages already explain issuer, jwks, and multiple JWT providers, but they did not state that a kid is only unique within one issuer's JWKS. A reader configuring multiple identity providers with colliding kid values would not know that the new behavior selects the provider by issuer first.

What changed on disk

• assets/agw-docs/pages/security/jwt-about.md — Adds a gated overview note for main about provider selection by iss and kid.
• assets/agw-docs/pages/security/jwt-setup.md — Adds the same gated behavior note beside the Multiple JWT providers example.
• content/docs/standalone/main/documentation/configuration/security/jwt-authn.md — Adds the standalone main-tree note about provider selection by iss and kid.

How to verify this change

1. Configure two JWT providers with different issuer values whose JWKS documents publish the same kid, then protect a route with the JWT policy.
2. Send one request with each issuer's token:

   curl -i "${INGRESS_GW_ADDRESS}:80/headers" -H "host: www.example.com" -H "Authorization: Bearer ${ISSUER_A_TOKEN}"
   curl -i "${INGRESS_GW_ADDRESS}:80/headers" -H "host: www.example.com" -H "Authorization: Bearer ${ISSUER_B_TOKEN}"

   Both requests return 200.
3. Send a token whose iss matches one provider but whose aud is wrong:

   curl -i "${INGRESS_GW_ADDRESS}:80/headers" -H "host: www.example.com" -H "Authorization: Bearer ${WRONG_AUDIENCE_TOKEN}"

   The request returns 401, and the proxy log reports InvalidAudience for the matching issuer rather than validating against a provider that only shares the kid.

Proposed release note

The item is labelled fix, so placement may need reviewer handling if the release-note script does not map plain fixes to a section.

What was not verified

The configuration was not applied to a cluster, and no standalone runtime command was run. The cluster-facts.md file was used only as the Kubernetes API surface for field names and types; it is not a test result.

How the pages were chosen (triage report)

Draft a documentation change

agentgateway/agentgateway#3611 — fix(jwt): select providers by issuer and kid

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Code issue: jwtAuthentication with multiple providers only ever validates against the first provider that has the token's kid agentgateway#3609
• Summary (read from the body): - Implemented Issuer check alongside kid checking to ensure that the valid jwt provider is used in a multi-tenant scenario.
• Tested: a cluster was available — a kind cluster for agentgateway/upstream at kubernetes/main is provisioned in the drafting job, chosen automatically because the runnable-steps gate held this item

Warnings

• fix(jwt): select providers by issuer and kid agentgateway#3611: re-drafting because it was named on this run, though its earlier draft is issue. Nothing removes the earlier entry; the new draft replaces it in the ledger when it opens.

Draft branch: pr-tracker-draft-agentgateway-3611

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	e9cdb27
Status:	⚡️  Build in progress...

View logs