Skip to content

fix(auth): per-server opt-out of the issuer metadata check for misconfigured authorization servers - #3020

Merged
cliffhall merged 2 commits into
v2/mainfrom
v2/fix/2983-skip-issuer-metadata-validation
Nov 18, 2026
Merged

cliffhall merged 2 commits into
v2/mainfrom
v2/fix/2983-skip-issuer-metadata-validation

Conversation

@cliffhall

Copy link
Copy Markdown
Member

Closes #2983

The bug

Microsoft Entra ID's multi-tenant endpoints publish authorization-server metadata whose issuer is a literal template. Reproduced against the live endpoint with the SDK this repo pins:

discoverAuthorizationServerMetadata(new URL("https://login.microsoftonline.com/organizations/v2.0"))
→ IssuerMismatchError (kind: metadata): Issuer mismatch in authorization server metadata (RFC 8414 §3.3):
  expected "https://login.microsoftonline.com/organizations/v2.0",
  received "https://login.microsoftonline.com/{tenantid}/v2.0"

The check is the SDK's and it is correct to have. The SDK also ships a documented, security-weakening opt-out (skipIssuerMetadataValidation on auth() and the transports, skipIssuerValidation on discovery). core/auth/mcpAuth.ts already forwarded it, but nothing set it and no surface exposed it.

The change

A per-server setting, Skip issuer metadata validation — oauth.skipIssuerMetadataValidation in mcp.json, oauthSkipIssuerMetadataValidation in settings.

  • Off by default, never global, never automatic. Only an explicit true is honored on read or written to disk, so a hand-edited non-boolean reads back as off.
  • It reaches every discovery the Inspector starts for that server: the four mcpAuth call sites in OAuthManager (redirect leg, callback leg, challenge handling, forced step-up), the CIMD pre-registration probe, and the SDK transports' own auth() on a 401.
  • It relaxes metadata discovery only. The RFC 9207 iss check on the authorization response and the SEP-2352 callback binding still run.
  • The mismatch error now says what to do. mcpAuth appends a hint naming the setting and its cost, keeping the SDK error as cause. An authorization-response (RFC 9207) mismatch — the mix-up signal — gets no hint.
  • Exposed where per-server OAuth settings already are, following 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/servers settings route, the web Server Settings → OAuth Settings form, and buildRunnerClientAuthOptions, which is what the CLI, mcpdo and the TUI read. No new flag or surface.
  • Documented in docs/mcp-server-configuration.md.

Not changed

--use-stored-auth (the CLI's refreshStoredAuthToken) takes a bare --server-url and 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, no iss advertised). Default: refused, and the message carries both the SDK diagnosis and the hint. Opted in: authorizes and connects.
  • Unit coverage for each hop: mcpAuth hint (metadata kind, serialized-name fallback, no hint for the RFC 9207 kind), OAuthManager forwarding, 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:gate green.

Screenshots

Web client, 1280×900. Default (off):

Skip issuer metadata validation, unchecked by default

Checked — saving writes "oauth": { "skipIssuerMetadataValidation": true } to the catalog entry:

Skip issuer metadata validation, checked

🤖 Generated with Claude Code

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>
@cliffhall cliffhall added the v2 Issues and PRs for v2 label Nov 18, 2026
@cliffhall
cliffhall requested a balanced review from Copilot November 18, 2026 20:28

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread core/mcp/oauthManager.ts
Comment on lines +144 to +146
return this.oauthConfig.skipIssuerMetadataValidation === true
? { skipIssuerMetadataValidation: true }
: {};

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Comment thread core/mcp/oauthManager.ts Resolved
)

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>
@cliffhall

Copy link
Copy Markdown
Member Author

Copilot review, round 1 — 2 findings, no suppressed comments.

  • Cached metadata bypasses the check after the setting is turned off — fixed in 3db4352. Reproduced with a failing enabled → disabled test first. With the check on, the provider withholds cached metadata that would not pass the SDK's comparison, keeping the recorded authorization-server URL so the SDK re-discovers strictly and the callback binding is unchanged.
  • Apply the opt-out to EMA resource discovery — declined as scope expansion beyond Inspector OAuth discovery rejects tenant-specific issuer for Microsoft Fabric Data Agent MCP #2983 (a new capability on a separate flow). The docs now say enterprise-managed authorization is unaffected.

Requesting another round for the pushed fix.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the per-server OAuth metadata issuer-validation workaround.

1 open issue
1 resolved since last review

Review effort: Balanced

@cliffhall

Copy link
Copy Markdown
Member Author

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.

@cliffhall
cliffhall merged commit 7df76f6 into v2/main Nov 18, 2026
12 checks passed
@cliffhall
cliffhall deleted the v2/fix/2983-skip-issuer-metadata-validation branch November 18, 2026 21:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

v2 Issues and PRs for v2

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Inspector OAuth discovery rejects tenant-specific issuer for Microsoft Fabric Data Agent MCP

2 participants