Document gateway JWT for upstream MCP server authentication#623
Open
dshoen619 wants to merge 7 commits into
Open
Document gateway JWT for upstream MCP server authentication#623dshoen619 wants to merge 7 commits into
dshoen619 wants to merge 7 commits into
Conversation
Add a new "Upstream Authentication (Gateway JWT)" section to the MCP Gateway architecture page covering the X-Gateway-Auth header, JWKS endpoint, JWT claims, verification snippet, and key rotation. Update the System Architecture Overview and Data Flow table to show the signed JWT attached to upstream requests and the optional JWKS verification path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Correct the earlier "ephemeral per-pod" framing now that the signing key is cached in Redis (encrypted at rest) and shared across all gateway replicas. Note that keys survive restarts, the JWKS endpoint is consistent across replicas, and keys rotate on roughly a 90-day cadence so users can reason about JWKS cache lifetimes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for permitio-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
zeevmoney
requested changes
Apr 30, 2026
Fixes 8 inaccuracies vs. the implementation in agent-security main: - Sequence diagram now shows shared-key load (not ephemeral generation) - aud row documents canonicalization (lowercase host, strip trailing slashes) - iat/nbf rows show 30s leeway; adds clock-tolerance note for verifiers - Drops misleading "enables replay detection" from jti row; adds opt-in replay-protection guidance in the verifier section - Verifier snippet now guards missing/non-string headers and the Bearer prefix, and sets clockTolerance: 30 - Key rotation callout: encryption-at-rest is conditional on vault; 90-day cadence is a warning, not automatic rotation - Configuration table adds GATEWAY_JWT_REQUIRE_VAULT and TTL bounds Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
zeevmoney
reviewed
Jun 2, 2026
Contributor
zeevmoney
left a comment
zeevmoney
left a comment
There was a problem hiding this comment.
Automated Review - the PR looks clean, found nothing.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds documentation to the MCP Gateway architecture page describing how the gateway authenticates itself to upstream MCP servers using a short-lived, gateway-signed JWT (X-Gateway-Auth) and how upstreams can verify it via the gateway’s JWKS endpoint.
Changes:
- Updated the System Architecture Overview diagram to label the Gateway → Upstream edge with
X-Gateway-Authand show an optional upstream verification flow to the gateway JWKS endpoint. - Updated the Data Flow table to mention the signed
X-Gateway-AuthJWT and link to the new section. - Added a new “Upstream Authentication (Gateway JWT)” section with flow explanation, claims table, verification snippet, key rotation notes, and configuration.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
zeevmoney
requested changes
Jun 2, 2026
- Data Flow diagram edge now mentions the signed X-Gateway-Auth JWT, matching the table row (Copilot, Zeev)
- Sequence-diagram claim list includes nbf (Zeev)
- Reworded "JWT signing (per-request)" note to reflect lazy caching/re-sign-near-expiry (Copilot)
- Use {...} placeholders instead of angle brackets in the sequence diagram so they don't render as HTML (Copilot)
- Use ASCII hyphen instead of Unicode minus in the iat/nbf claim rows (Copilot)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
zeevmoney
reviewed
Jun 4, 2026
Contributor
zeevmoney
left a comment
zeevmoney
left a comment
There was a problem hiding this comment.
Automated Review - the PR looks clean, found nothing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the gateway JWT feature added in agent-security#162 and the Redis-backed shared-key follow-up in agent-security#172.
Adds a new Upstream Authentication (Gateway JWT) section to the MCP Gateway architecture page so users understand how the gateway proves request origin to upstream MCP servers, and gives them everything they need to verify on their side.
What's documented
X-Gateway-Authheader lets upstream MCP servers reject traffic that didn't flow through the gateway (preventing bypass of authN/authZ/consent)iss,sub,aud,exp,iat,nbf,jti,tenantAuthorization: Bearer(upstream OAuth) vsX-Gateway-Auth: Bearer(gateway identity proof)joseexample for upstream servers, usingcreateRemoteJWKSetso JWKS caching and key rotation are handled automaticallyGATEWAY_JWT_TTL_SECONDSenv var (default 300) and pointer to the platform Settings > Upstream Authentication (JWT) panelAlso updated:
Proxy MCP + X-Gateway-Auth JWT, plus a dashed optional verification arrow back to the gateway's JWKS endpointX-Gateway-AuthJWT with an anchor link to the new sectionScope decisions
SET NXcoordination, AES-256-GCM / KMS internals, and replica-count details — implementation specifics with no troubleshooting value for end usersTest plan
#upstream-authentication-gateway-jwt) resolves correctly🤖 Generated with Claude Code