RFC 8707 Resource Indicators Implementation #638

ochafik · 2025-06-16T18:35:19Z

Implements Resource Indicators validation for OAuth 2.0 (RFC 8707; spec change).

Fixes #592, Fixes #635

set the resource parameter in OAuth authorization and token exchange flows to bind tokens to the MCP server.
updated simpleStreamableHttp.ts to show how to perform strict verification (disabled by default, run with --oauth --oauth-strict to enable)
strict validation of resource returned by the PRM

Note: Inspector is being updated in pcarleton/auth-debugger-resource

Motivation and Context

Facilitate prevention of token theft/confusion attacks where a malicious MCP server steals tokens meant for other services by explicitly binding tokens to their intended resources and showing how a server can do strict checks of this binding.

This security vulnerability was identified in modelcontextprotocol/modelcontextprotocol#544.

How Has This Been Tested?

Test coverage has been added, and MCP inspector's auth flows (quick & guided) were tested manually (w/ pending modelcontextprotocol/inspector#526 changes applied)

Breaking Changes

While the change is breaking at a protocol level, it should not require code changes from SDK users (just SDK version bumping).

Client developers: No code changes required. The SDK automatically extracts and includes the resource parameter from the server URL
Server developers:
- Resource validation is left to implementors (see demoInMemoryOAuthProvider.ts and simpleStreamableHttp.ts).
- Note that before an MCP server can fail on missing or mismatching resource param, the Authorization Server (if external) needs to support / relay the resource param, and enough of the clients need to update their SDK to start setting the resource param in their auth requests. This is why simpleStreamableHttp.ts only validates the resource if --oauth-strict is set.
- Each server should ideally treat each MCP server as a distinct resource in their PRM. If they host many servers under the same domain, the resource should be specific to a single server, not be domain-wide (otherwise any "bad apple" server might be able to benefit from resource confusion w/ its siblings). This may be facilitated in follow up changes to the SDK.
Auth providers: should be updated to accept and relay resource parameter.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Implementation Approach

Resource URIs are used as-is with only fragment removal. This allows having different MCP servers under different subpaths (even w/ different query URLs) w/o sharing spilling their resource authorization to each other (to allow a variety of MCP server federation use cases).

Key Components Added

Shared utilities (auth-utils.ts): Resource URI handling and validation
Client auth modifications: Resource parameter support in authorization/token flows
Transport layers: Automatic resource extraction from server URLs
Server handlers: Resource parameter acceptance and forwarding
Demo provider
Error handling: New InvalidTargetError for RFC 8707 compliance

References

RFC 8707 - Resource Indicators for OAuth 2.0
Fixes Pass a resource parameter in the authorization URL when using oauth-protected-resource during OAuth #592: OAuth token confusion vulnerability
Fixes update typescript auth example to demonstrate RFC 8707 resource parameter validation #635: Server-side RFC 8707 support request

Co-Authored-By: Claude <[email protected]>

…emo provider - Clarify that core server handlers only pass through resource parameter - Emphasize that server URL validation is demonstrated in the demo provider - Update issue references to show #592 is fixed, #635 is related - Update examples to show DemoOAuthProviderConfig usage 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

pcarleton

The plumbing looks good, but a few thoughts on the demo implementation:

The RFC 8707 is intending to make audience restricted tokens , so a key thing is that if we get a token with a different resource we reject it. So far, it looks like the demo is focused on preventing a token from ever being created with a bad resource, but doesn't exercise the token rejection flow that would happen during e.g. the bearerAuth.ts middleware.

So, e.g. if I got a token for resource=https://foo.example.com/mcp, and I used that on https://bar.example.com/mcp we should reject it.

I think it's useful to prevent invalid tokens from being created, but I think it's important we demonstrate that the AS needs to either store the resource with the token (and check it), or it needs to encode the resource data into the token itself (and check it).

pcarleton · 2025-06-16T20:08:15Z

src/shared/auth-utils.ts

+ * RFC 8707 section 2 states that resource URIs "MUST NOT include a fragment component".
+ * Keeps everything else unchanged (scheme, domain, port, path, query).
+ */
+export function resourceUrlFromServerUrl(url: string): string {


optional: setting url.hash = "" will remove the hash too, so you could keep it as a URL

https://developer.mozilla.org/en-US/docs/Web/API/URL/hash

Hah cool, thanks!

pcarleton · 2025-06-16T20:29:16Z

src/examples/server/demoInMemoryOAuthProvider.ts

@@ -28,18 +43,28 @@ export class DemoInMemoryClientsStore implements OAuthRegisteredClientsStore {
 * - Persistent token storage
 * - Rate limiting
 */
+interface ExtendedAuthInfo extends AuthInfo {


I think it makes sense to add this to the base AuthInfo

Done, thanks

pcarleton · 2025-06-16T20:35:25Z

src/examples/server/demoInMemoryOAuthProvider.ts

+    if (resource) {
+      await this.validateResource(client, resource);
+    }
+    throw new Error('Refresh tokens not implemented for example demo');
  }

  async verifyAccessToken(token: string): Promise<AuthInfo> {


i think we want to change this method as well, and test it.

Implementations that decode / parse the token probably would check the resource, but here we just lookup the tokenData we've validated in exchangeAuthorizationCode, and the resource expectations haven't changed since (same mcpServerUrl).

Co-Authored-By: Claude <[email protected]>

ochafik

Simplified the code a bit :-)

ochafik · 2025-06-16T22:43:27Z

src/examples/server/demoInMemoryOAuthProvider.ts

@@ -28,18 +43,28 @@ export class DemoInMemoryClientsStore implements OAuthRegisteredClientsStore {
 * - Persistent token storage
 * - Rate limiting
 */
+interface ExtendedAuthInfo extends AuthInfo {


Done, thanks

ochafik · 2025-06-16T22:46:38Z

src/examples/server/demoInMemoryOAuthProvider.ts

+    if (resource) {
+      await this.validateResource(client, resource);
+    }
+    throw new Error('Refresh tokens not implemented for example demo');
  }

  async verifyAccessToken(token: string): Promise<AuthInfo> {


Implementations that decode / parse the token probably would check the resource, but here we just lookup the tokenData we've validated in exchangeAuthorizationCode, and the resource expectations haven't changed since (same mcpServerUrl).

ochafik · 2025-06-16T22:46:56Z

src/shared/auth-utils.ts

+ * RFC 8707 section 2 states that resource URIs "MUST NOT include a fragment component".
+ * Keeps everything else unchanged (scheme, domain, port, path, query).
+ */
+export function resourceUrlFromServerUrl(url: string): string {


Hah cool, thanks!

…eware - Tests that when mcp-protocol-version header is missing, the middleware uses DEFAULT_NEGOTIATED_PROTOCOL_VERSION when calling verifyAccessToken - Ensures proper fallback behavior for protocol version negotiation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

src/client/auth.test.ts

Fixed 5 instances of hardcoded "https://resource.example.com" in OAuth protected resource metadata mocks to use the actual resourceBaseUrl.href. This resolves test failures where the auth validation was rejecting requests because the resource URL in the metadata didn't match the actual test server URL. The failing tests were: - attempts auth flow on 401 during SSE connection - attempts auth flow on 401 during POST request - refreshes expired token during SSE connection - refreshes expired token during POST request - redirects to authorization if refresh token flow fails All SSE tests now pass (17/17). 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

…edResourceMetadata

ihrpr

LGTM

ochafik and others added 5 commits June 16, 2025 19:29

implementation of RFC 8707 Resource Indicators (Fixes #592, Fixes #635)

7b5bfce

cleanup auth-utils and remove example files

1f4e42c

Co-Authored-By: Claude <[email protected]>

Update authorize.config.test.ts

cba6a6e

Co-Authored-By: Claude <[email protected]>

simplify PR / only keep verification in demo inmemory oauth provider

ccccb4b

Co-Authored-By: Claude <[email protected]>

pcarleton requested changes Jun 16, 2025

View reviewed changes

ochafik and others added 9 commits June 16, 2025 22:56

Simplify demo in-memory oauth provider

6656d23

Co-Authored-By: Claude <[email protected]>

simplify diff

02ce81b

Update demoInMemoryOAuthProvider.ts

36f338a

update resource to be a url

224a2e2

use URL for resource throughout

551a439

Update demoInMemoryOAuthProvider.test.ts

6e4fc52

rm noise

ec0c504

cleanups

b16a415

fix tests

badb5dc

ochafik commented Jun 17, 2025

View reviewed changes

ochafik and others added 3 commits June 17, 2025 11:53

fix lints

515abb4

show how to enable strict resource checking in mcp server

40f61d8

github-advanced-security bot found potential problems Jun 17, 2025

View reviewed changes

src/client/auth.test.ts Fixed Show fixed Hide fixed

src/client/auth.test.ts Fixed Show fixed Hide fixed

ochafik requested a review from pcarleton June 17, 2025 17:45

Update README.md

c2150f0

ochafik force-pushed the ochafik/auth-resource branch from 7b073bf to c2150f0 Compare June 17, 2025 18:19

ochafik added 7 commits June 18, 2025 11:23

cleanups

bf72f87

Update simpleStreamableHttp.ts

4a88cac

Update simpleStreamableHttp.ts

d58c2eb

Update simpleStreamableHttp.ts

aebb2ab

minimize diff

049170d

Update streamableHttp.ts

b77361b

drop redundant resource canonicalization tests

8475e43

ochafik and others added 11 commits June 18, 2025 11:50

fix simpleStreamableHttp.ts

e5b2a5b

verify PRM resource

4fcbb68

simplify changes

68424ef

minimize changes

9e2a565

shrink token.test.ts

6a01d0d

shrink diff

5c60c77

auth: don't fail the prm if the resource doesn't match

354318f

simplify tests

bac384f

Update auth.test.ts

f0ea31c

shrink tests

3f07bdb

pcarleton mentioned this pull request Jun 18, 2025

[auth] Add resource compatibility to debugger (RFC 8707) modelcontextprotocol/inspector#526

Open

9 tasks

ochafik and others added 4 commits June 18, 2025 15:06

stricter PRM check overridable w/ OAuthClientProvider.validateProtect…

4b3db9b

…edResourceMetadata

test validateProtectedResourceMetadata override

f854b58

wip helper func

dada5f6

fix tests

4c51230

ochafik marked this pull request as ready for review June 18, 2025 15:02

adjust comment

86bed6a

pcarleton approved these changes Jun 18, 2025

View reviewed changes

ihrpr approved these changes Jun 18, 2025

View reviewed changes

ihrpr merged commit 90569d8 into main Jun 18, 2025
5 checks passed

ihrpr deleted the ochafik/auth-resource branch June 18, 2025 16:34

ochafik mentioned this pull request Jun 18, 2025

simpleStreamableHttp: fix example code #660

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

RFC 8707 Resource Indicators Implementation #638

RFC 8707 Resource Indicators Implementation #638

ochafik commented Jun 16, 2025 •

edited

Loading

Uh oh!

pcarleton left a comment

Uh oh!

pcarleton Jun 16, 2025

Uh oh!

ochafik Jun 16, 2025

Uh oh!

pcarleton Jun 16, 2025

Uh oh!

ochafik Jun 16, 2025

Uh oh!

pcarleton Jun 16, 2025

Uh oh!

ochafik Jun 16, 2025

Uh oh!

ochafik left a comment

Uh oh!

ochafik Jun 16, 2025

Uh oh!

ochafik Jun 16, 2025

Uh oh!

ochafik Jun 16, 2025

Uh oh!

Uh oh!

Uh oh!

ihrpr left a comment

Uh oh!

Uh oh!

Uh oh!

RFC 8707 Resource Indicators Implementation #638

RFC 8707 Resource Indicators Implementation #638

Conversation

ochafik commented Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Implementation Approach

Key Components Added

References

Uh oh!

pcarleton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ihrpr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ochafik commented Jun 16, 2025 •

edited

Loading