Repository navigation
fix(auth): per-server opt-out of the issuer metadata check for misconfigured authorization servers - #3020
Conversation
Microsoft Entra ID's multi-tenant endpoints publish authorization-server metadata whose `issuer` is the literal template `https://login.microsoftonline.com/{tenantid}/v2.0`, so the SDK's RFC 8414 §3.3 issuer check rejects discovery for `/organizations/v2.0` and the OAuth flow stops before authorization starts. The SDK ships a security-weakening opt-out for exactly this; `mcpAuth` already forwarded it but nothing set it. Add a per-server setting, "Skip issuer metadata validation" (`oauth.skipIssuerMetadataValidation` in mcp.json, `oauthSkipIssuerMetadataValidation` in settings). Off by default, never global and never automatic; only an explicit `true` is honored or written. It reaches every discovery the Inspector starts for that server: the four `mcpAuth` call sites in the OAuth manager, the CIMD pre-registration probe, and the SDK transports' own `auth()`. The RFC 9207 `iss` check and the callback's authorization-server binding are untouched. The metadata mismatch error now names the setting and what it costs, with the SDK's error kept as `cause`; an authorization-response mismatch gets no such hint. Plumbed through the config round-trip, the remote settings route, the CLI/mcpdo/TUI runner and the web connect path, with an end-to-end test that runs a real authorization-code flow against a metadata document shaped like Entra's. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Signed-off-by: cliffhall <cliff@futurescale.com>
There was a problem hiding this comment.
🟡 Changes recommended
Cached OAuth metadata can bypass issuer validation after the setting is disabled, while enterprise-managed resource-server discovery fails to honor the opt-out.
2 open issues
What changed in this PR
Adds a per-server workaround for authorization servers such as Microsoft Entra ID that publish mismatched metadata issuers, addressing #2983 across Inspector’s shared OAuth configuration and client surfaces.
Changes:
- Adds an explicit, default-off setting and forwards it through OAuth discovery and HTTP transports.
- Exposes the setting in web server settings, documents its security cost, and adds a targeted mismatch hint.
- Adds configuration, forwarding, UI, and authorization-flow regression coverage.
| File | Description |
|---|---|
| docs/mcp-server-configuration.md | Documents the opt-out, risks, and scope. |
| core/mcp/types.ts | Defines the setting across configuration interfaces. |
| core/mcp/serverList.ts | Reads and persists only explicit opt-in. |
| core/mcp/remote/node/server.ts | Validates and saves the setting through the API. |
| core/mcp/oauthManager.ts | Forwards the option into managed OAuth calls. |
| core/mcp/node/transport.ts | Passes the option to both HTTP transports. |
| core/mcp/inspectorClient.ts | Extends the public OAuth configuration interface. |
| core/client/runner.ts | Supplies the setting to command-line clients. |
| core/auth/mcpAuth.ts | Adds a security-aware metadata mismatch hint. |
| core/auth/discovery.ts | Supports opt-out during metadata discovery. |
| core/auth/cimd.ts | Forwards the option to pre-registration discovery. |
| clients/web/src/test/integration/mcp/remote/server-extra-coverage.test.ts | Tests API validation and persistence. |
| clients/web/src/test/integration/mcp/node/transport.test.ts | Tests option forwarding to HTTP transports. |
| clients/web/src/test/integration/auth/issuerMetadataMismatch.test.ts | Exercises strict and opted-in authorization flows. |
| clients/web/src/test/integration/auth/discovery.test.ts | Tests explicit opt-in forwarding. |
| clients/web/src/test/core/mcp/serverList.test.ts | Tests configuration defaults and round-trip behavior. |
| clients/web/src/test/core/mcp/oauthManager.test.ts | Tests forwarding through OAuth manager paths. |
| clients/web/src/test/core/client/runner.test.ts | Tests runner configuration forwarding. |
| clients/web/src/test/core/auth/mcpAuth.test.ts | Tests hint classification and cause preservation. |
| clients/web/src/test/core/auth/cimd.test.ts | Tests pre-registration with mismatched metadata. |
| clients/web/src/hooks/useConnectionLifecycle.ts | Reads the setting when creating web connections. |
| clients/web/src/hooks/useConnectionLifecycle.test.tsx | Tests connection settings propagation. |
| clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.tsx | Maps checkbox changes into persisted settings. |
| clients/web/src/components/groups/ServerSettingsModal/ServerSettingsModal.test.tsx | Tests enabling and clearing the opt-out. |
| clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.tsx | Adds the checkbox and security warning. |
| clients/web/src/components/groups/ServerSettingsForm/ServerSettingsForm.test.tsx | Tests checkbox defaults, saved state, and changes. |
Review effort: Balanced
| return this.oauthConfig.skipIssuerMetadataValidation === true | ||
| ? { skipIssuerMetadataValidation: true } | ||
| : {}; |
There was a problem hiding this comment.
Fixed in 3db4352. Confirmed first: an enabled → disabled regression test failed before the fix — the strict client authorized straight off the cached document. BaseOAuthClientProvider.discoveryState() now withholds cached authorizationServerMetadata that would not pass the SDK's own RFC 8414 §3.3 comparison whenever the setting is off. Only the metadata is withheld: the recorded authorizationServerUrl stays, so the SDK re-discovers that same server strictly (and reports the mismatch again) and the callback's authorization-server binding is unchanged. Because every path reads the cache through the provider, this covers manager-owned auth(), the transport's own auth() and the CIMD probe alike. Stored state is not rewritten, so re-enabling the setting finds it. Tests: the e2e regression in issuerMetadataMismatch.test.ts, plus unit cases in providers.test.ts (withheld when strict, returned when opted in, matching and trailing-slash issuers left alone).
) SDK `auth()` validates authorization-server metadata only when it discovers it; a cached document is reused as-is. So metadata accepted while `skipIssuerMetadataValidation` was on kept being used after the setting was turned off, and turning it off restored nothing. With the check on, `BaseOAuthClientProvider.discoveryState()` now withholds cached metadata that would not pass the SDK's own comparison. The recorded authorization-server URL is kept, so the SDK re-discovers that server strictly and the callback binding is unaffected; stored state is untouched. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Signed-off-by: cliffhall <cliff@futurescale.com>
|
Copilot review, round 1 — 2 findings, no suppressed comments.
Requesting another round for the pushed fix. |
|
Copilot review closed after round 2 — clean round. "Approval recommended", no inline comments, no new findings and no suppressed comments. The one item its summary still lists as open is the round-1 cached-metadata thread, fixed in 3db4352 and answered in that thread; it carries over only because the thread is unresolved. No further round requested. |


Closes #2983
The bug
Microsoft Entra ID's multi-tenant endpoints publish authorization-server metadata whose
issueris a literal template. Reproduced against the live endpoint with the SDK this repo pins:The check is the SDK's and it is correct to have. The SDK also ships a documented, security-weakening opt-out (
skipIssuerMetadataValidationonauth()and the transports,skipIssuerValidationon discovery).core/auth/mcpAuth.tsalready forwarded it, but nothing set it and no surface exposed it.The change
A per-server setting, Skip issuer metadata validation —
oauth.skipIssuerMetadataValidationinmcp.json,oauthSkipIssuerMetadataValidationin settings.trueis honored on read or written to disk, so a hand-edited non-boolean reads back as off.mcpAuthcall sites inOAuthManager(redirect leg, callback leg, challenge handling, forced step-up), the CIMD pre-registration probe, and the SDK transports' ownauth()on a 401.isscheck on the authorization response and the SEP-2352 callback binding still run.mcpAuthappends a hint naming the setting and its cost, keeping the SDK error ascause. An authorization-response (RFC 9207) mismatch — the mix-up signal — gets no hint.oauth.scopeOnRefresh(Opt-in scope on OAuth token refresh via the SDK's scopeForRefresh (Entra ID AADSTS90009) #2805): the config file round-trip, the/api/serverssettings route, the web Server Settings → OAuth Settings form, andbuildRunnerClientAuthOptions, which is what the CLI,mcpdoand the TUI read. No new flag or surface.docs/mcp-server-configuration.md.Not changed
--use-stored-auth(the CLI'srefreshStoredAuthToken) takes a bare--server-urland resolves no catalog entry, so it has no per-server setting to read; it also only discovers when the stored state carries no metadata, and then only against the MCP server URL itself. The docs say so. The enterprise-managed (EMA) IdP discovery paths are a different authorization server with their own configuration and are untouched.Tests
issuerMetadataMismatch.test.ts(new, integration): a real authorization-code flow through the real SDK against the in-repo OAuth server, with the metadata document rewritten in flight to Entra's shape (template issuer, noissadvertised). Default: refused, and the message carries both the SDK diagnosis and the hint. Opted in: authorizes and connects.mcpAuthhint (metadata kind, serialized-name fallback, no hint for the RFC 9207 kind),OAuthManagerforwarding, CIMD probe, discovery helper, both HTTP transports, config round-trip, settings route validation and persistence, runner and web connect path, form and modal.npm run local:gategreen.Screenshots
Web client, 1280×900. Default (off):
Checked — saving writes
"oauth": { "skipIssuerMetadataValidation": true }to the catalog entry:🤖 Generated with Claude Code