feat: prefer upstream credentials over JWT propagation for JWKS auth#3061
Draft
joeyorlando wants to merge 3 commits intomainfrom
Draft
feat: prefer upstream credentials over JWT propagation for JWKS auth#3061joeyorlando wants to merge 3 commits intomainfrom
joeyorlando wants to merge 3 commits intomainfrom
Conversation
When a user authenticates via external IdP JWKS, the gateway previously always propagated the IdP JWT to upstream MCP servers. This meant upstream servers like GitHub or Jira (which need their own service-specific tokens) couldn't be used with JWKS auth. This flips the credential resolution priority so that upstream server credentials (OAuth tokens, PATs) take precedence when available. JWT propagation remains as a fallback for end-to-end JWKS patterns where the upstream server validates the same JWT. This enables a powerful workflow: admins install MCP servers with service credentials once, users authenticate via their org's IdP (Keycloak, Okta, etc.), and the gateway automatically resolves the right upstream token.
Collaborator
📊 Reputation Summary
How is the score calculated? Read about it in the Reputation Bot repository 🤖 |
Contributor
Playwright test results
Details
Failed testsapi › api/llm-proxy/virtual-api-keys.spec.ts › Virtual API Keys - LLM Proxy › virtual key with per-key base URL routes to custom endpoint Flaky testsapi › api/chat-settings.spec.ts › Chat API Keys Access Control › member should be able to read chat API keys |
Add 6 unit tests covering credential resolution when using External IdP JWKS authentication: - Upstream access_token takes priority over JWT propagation (remote) - Falls back to JWT propagation when no upstream credentials (remote) - raw_access_token takes priority over JWT propagation (remote) - Non-JWKS auth (OAuth/Bearer) continues to use upstream credentials - Dynamic credentials resolve and use server credentials with JWKS - Local streamable-http servers use credentials over JWT propagation Also update mcp-authentication.md to document the credential resolution priority: upstream server credentials are preferred, with JWT propagation as a fallback for the end-to-end JWKS pattern.
Add WireMock stubs (echo_auth tool) and two Playwright e2e tests that verify credential resolution when authenticating via External IdP JWKS: 1. When upstream server has credentials configured, they should be preferred over the caller's JWT — the WireMock echo confirms the static token is forwarded, not the Keycloak JWT. 2. When no upstream credentials exist, the JWT should be propagated as a fallback (end-to-end JWKS pattern) — the WireMock echo confirms a JWT-shaped token is forwarded.
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
2 participants
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
Motivation
When a user authenticates via external IdP JWKS (e.g., Keycloak, Okta), the gateway previously always forwarded the IdP JWT to upstream MCP servers. This blocked a key use case: using JWKS auth with upstream servers that require their own service-specific tokens (GitHub PATs, Jira API tokens, etc.).
With this change, an admin can:
What Changed
In
mcp-client.tsgetTransportWithKind(), the token resolution priority is now:secrets.access_token/secrets.raw_access_token) — highest prioritytokenAuth.rawToken) — fallback when no upstream credentials existPreviously the order was reversed (JWT always took priority).
Backward Compatibility
isExternalIdpStandalone Example
See the
mcp-gateway-token-exchangeexample for a self-contained demo of the token exchange concept using Keycloak + mock GitHub MCP server.Test plan
mcp-gateway-jwt-propagation.ee.spec.tsstill passes (JWT propagation when no upstream credentials)