Skip to content

fix(oauth): Match resource indicators that differ only by query or trailing slash - #2410

Merged
dcramer merged 1 commit into
mainfrom
fix/oauth-resource-query-mismatch
Nov 19, 2026
Merged

dcramer merged 1 commit into
mainfrom
fix/oauth-resource-query-mismatch

Conversation

@sentry-junior

@sentry-junior sentry-junior Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

MCP clients fail to sign in or refresh with invalid_target ("Requested resource was not included in the authorization request") when the RFC 8707 resource at login and at the token request differ only by a query string or a trailing slash. Tokens bound to one form also fail on /mcp with "Token audience does not match resource server".

Why it happens. Our protected resource metadata echoes the query of the URL the client dials (/mcp?utm_source=plugin → "resource": "https://mcp.sentry.dev/mcp?utm_source=plugin"). Clients disagree about whether that query belongs in the resource. For example, opencode now drops it on purpose so that a refresh "names the same resource the login did" (anomalyco/opencode packages/core/src/mcp/oauth.ts). workers-oauth-provider 0.10.3 compares the token-request resource to the grant with ===, and compares the token audience to the request URL including the query. So a grant from /mcp?utm_source=plugin rejects a refresh for /mcp, and the other way around.

Production impact (sentry/mcp-server logs, last 14 days):

  • About 7.5k invalid_target token responses. The baseline is 40–90 a day, rising to 72 and 88 on Nov 17–18.
  • About 2.1k "Token audience does not match resource server" 401s.
  • Most come from opencode, Claude Code plugin installs (?utm_source=plugin), Codex, and clients that send no user agent. The affected users dial /mcp with ?utm_source=plugin or ?codemode=false.
  • Grok CLI also loads the Claude plugin URL (grok-cli/* traffic on /mcp?utm_source=plugin), so it hits the same path.

Fix. The existing provider patch gets a resourceMatchCanonical option, enabled in index.ts. With it, the token endpoint's requested-vs-granted check and the /mcp audience check compare scheme, host, port, and path, ignoring the query and trailing slashes.

What stays the same. The org/project path binding is unchanged: a /mcp/sentry grant still rejects a /mcp/other token request, and its token still gets a 401 on /mcp/other. The query on /mcp (skills, codemode, utm_source) is not an authorization boundary for OAuth tokens, because granted skills come from the grant props. Anyone upgrading the provider has to port the patch; docs/cloudflare/oauth-architecture.md says how.

Related: #1247. This PR does not fix that issue: a percent-encoded query (/mcp%3Futm_source=plugin) is still rejected when the client starts authorization.

via @dcramer.

--

View Session [Sentry]

…ailing slash

Protected resource metadata echoes the query of the URL a client dials,
so clients disagree about whether `?utm_source=plugin`, `?codemode=false`,
or a trailing slash belongs in the RFC 8707 resource. A login in one form
followed by a code exchange or refresh in the other failed with
`invalid_target` ("Requested resource was not included in the
authorization request"), and tokens bound to one form failed on `/mcp`
with "Token audience does not match resource server".

Add a `resourceMatchCanonical` option to the workers-oauth-provider patch
that compares scheme, host, port, and path for both checks, and enable it.
The `/mcp/{org}/{project}` path binding is unchanged.

Co-Authored-By: David Cramer <23610+dcramer@users.noreply.github.com>
@vercel

vercel Bot commented Nov 19, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
cli Ready Ready Preview Nov 19, 2026 1:22am UTC
sentry-local Ready Ready Preview Nov 19, 2026 1:22am UTC

Request Review

@dcramer

dcramer commented Nov 19, 2026

Copy link
Copy Markdown
Member

Why is this an optional behavior? Help me understand what's broken today. Are we doing something wrong against the spec? Is it a problem with the upstream provider that we're supposed to be bumping because it fixes it?

@sentry-junior

sentry-junior Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Good questions. Here's what I found:

What's broken today

Production advertises the URL the client dialed, query included, as the resource identifier:

POST https://mcp.sentry.dev/mcp?utm_source=plugin  (no token)
→ WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource/mcp?utm_source=plugin"
GET  that metadata URL
→ "resource": "https://mcp.sentry.dev/mcp?utm_source=plugin"

The client stores the grant under whichever form it sends at /oauth/authorize. Some clients later send a different form at /oauth/token. opencode drops the query on purpose, for example, and other clients drop or add a trailing slash. workers-oauth-provider 0.10.3 compares the token request's resource to the grant with ===, so a grant stored as /mcp?utm_source=plugin rejects a refresh for /mcp with invalid_target. The /mcp audience check also requires the request's query to equal the audience's query. That's where the ~2.1k "Token audience does not match resource server" 401s come from.

Are we doing something wrong against the spec?

Partly, yes. RFC 8707 §2 says a resource "SHOULD NOT include a query component" unless the query is what scopes the resource. utm_source and codemode don't identify the resource: org/project scope lives in the path and in grant props, and granted skills come from props. RFC 9728 makes the metadata echo whatever URL the client derived the metadata URL from, so the mistake is earlier, in the challenge: our 401 points clients at a query-bearing metadata URL. Clients are also off-spec: the MCP spec says the same canonical URI goes in both the authorize and token requests, and opencode deliberately doesn't send the same one. Both sides contribute, but we're the side we can fix.

Would bumping the upstream provider fix it?

Not as a drop-in. We're on 0.10.3, and upstream is at 1.2.4. 1.x addresses this with a different model:

  • You must configure one canonical resourceMetadata.resource, and it becomes every token's audience.
  • Since 1.2.4, a requested resource that adds query parameters to the canonical one maps to it (findCoveringResource).
  • Query and trailing slash otherwise stay strict, and resourceMatchOriginOnly is removed.

So 1.x would fix the query variant for new sign-ins if we set resource: "https://mcp.sentry.dev/mcp". Costs:

  • Every existing grant bound to another form (/mcp?utm_source=plugin, /mcp/{org}/...) gets invalid_grant and has to sign in again. Their migration guide says the library intentionally won't widen stored resources.
  • Org/project binding would rest only on the props constraints in mcp-handler.ts, which already enforce it, rather than on the audience path.
  • We'd have to port our CIMD pre-registration patch and handle the other 1.x breaking changes.

Why is it an option?

Only so our patch keeps the library's default intact and the deviation shows up in our config, not buried in a diff of dist/. We're the only consumer, so it doesn't need to be configurable. I'm happy to make it unconditional in the patch if you'd rather.

My take: this PR stops the failures for existing sessions now, with no forced re-auth. The upgrade-aligned fix is a separate migration: bump to 1.2.4 with canonical /mcp, stop putting the query in our challenge and metadata, and accept one re-auth. I'd ship this, then do the 1.x upgrade as a follow-up. Tell me if you'd rather skip straight to the upgrade.

@dcramer
dcramer marked this pull request as ready for review November 19, 2026 02:09
@dcramer
dcramer requested a review from a team as a code owner November 19, 2026 02:09
@sentry-junior
sentry-junior Bot requested a review from dcramer November 19, 2026 02:09
@github-actions github-actions Bot added the risk: medium PR risk score: medium label Nov 19, 2026
@dcramer

dcramer commented Nov 19, 2026

Copy link
Copy Markdown
Member

So the idea is we'd basically no-op the query param and support both, or we'd stop using the query param, or what?

@sentry-junior

sentry-junior Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Both, in two steps:

  1. This PR: accept both forms. The query is ignored only when comparing resources: the token endpoint's resource check and the /mcp audience check. Nothing else changes for the query. utm_source, codemode, and skills still reach the handler on the request URL and keep working. The path still has to match. Existing grants stored as /mcp?utm_source=plugin, and clients that add or drop the query later, stop failing, and nobody has to sign in again.

  2. Follow-up: stop advertising the query as part of the resource. Today we put the request query into the resource we advertise:

    • the 401 challenge's resource_metadata URL (index.ts:120, ${url.pathname}${url.search})
    • the scoped AS metadata shim's resource= (authorization-server-metadata.ts:21)

    If both drop url.search, new grants bind to https://mcp.sentry.dev/mcp (or /mcp/{org}/{project}) no matter which URL the client dials. That's what RFC 8707 recommends, and it matches the single canonical resource that workers-oauth-provider 1.x expects, so the eventual upgrade wouldn't strand those grants.

We wouldn't stop using the query params themselves. utm_source is attribution in the plugin config, and codemode and skills change server behavior. They just aren't part of the resource identity.

Step 2 alone wouldn't fix things: grants that already carry the query, and clients that build the resource from their configured URL rather than from our metadata, still need step 1. One thing to check before step 2: whether any client rejects metadata whose resource differs from the URL it dialed. RFC 9728 has clients compare the two, but the 401 would then point at query-free metadata, so a client following the challenge should see a consistent pair. I'd test that against Claude Code, Codex, and opencode before shipping it.

I can open step 2 as a separate PR if you want it.

@dcramer
dcramer merged commit e701040 into main Nov 19, 2026
47 checks passed
@dcramer
dcramer deleted the fix/oauth-resource-query-mismatch branch November 19, 2026 02:14

This branch was successfully deployed

2 active deployments
Preview – sentry-local — bb2ed5ab Deployed Nov 19, 2026 by vercel[bot]
Preview – cli — bb2ed5ab Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk: medium PR risk score: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant