Implement SEP-985: OAuth Protected Resource Metadata discovery fallback #1548
+252
−30
Conversation
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
Add support for multiple discovery mechanisms when WWW-Authenticate header is absent, aligning with RFC 9728 requirements. Clients now try discovery URLs in order: WWW-Authenticate header resource_metadata parameter, path-based well-known URI, then root-based well-known URI. Changes: - Add discovery state tracking to OAuthContext (discovery_urls, discovery_index) - Implement _build_protected_resource_discovery_urls() to generate ordered URL list - Update _discover_protected_resource() to support multi-step discovery - Modify _handle_protected_resource_response() to return success/failure boolean - Update async_auth_flow() to loop through discovery URLs with fallback logic - Add comprehensive test coverage for all three discovery mechanisms This enables servers to choose between WWW-Authenticate headers and well-known URIs based on their deployment architecture, reducing integration complexity for large-scale, multi-tenant environments. Github-Issue: modelcontextprotocol#1341 Co-Authored-By: Claude <[email protected]>
|
thanks @cbcoutinho ! I added a few tweaks to be more similar to OAuth Authorization Server metadata discovery (step 3) and eliminate additions to context. |
maxisbey
approved these changes
Nov 5, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 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
Implements SEP-985 to align OAuth 2.0 Protected Resource Metadata discovery with RFC 9728. This update makes WWW-Authenticate headers optional and adds support for well-known URI fallback, enabling more flexible server deployment models.
Changes
discovery_urlsanddiscovery_indexfields toOAuthContextto track fallback URL attempts_build_protected_resource_discovery_urls()to generate ordered list of discovery URLs:resource_metadataparameter (if present)/.well-known/oauth-protected-resource/{path}/.well-known/oauth-protected-resourceasync_auth_flow()to loop through discovery URLs until one succeeds or all are exhausted_handle_protected_resource_response()to return boolean indicating success, enabling automatic fallback on 404 or validation errorsTest Coverage
Added comprehensive
TestSEP985Discoverytest class with three scenarios:All existing tests pass (92 passed, 1 xfailed as expected).
Motivation
SEP-985 addresses deployment challenges in large-scale, multi-tenant environments where injecting WWW-Authenticate headers from backend services is complex due to separation of concerns. By making headers optional and requiring well-known URI support, servers can choose the discovery mechanism that best fits their architecture.
Test Plan
pytest tests/client/test_auth.pypytest tests/server/auth/References