Fix OAuth discovery fallback and URL ordering #1624
Merged
+319
−41
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
This commit addresses two related OAuth discovery issues: 1. Enable fallback to March 2025 spec for legacy servers (issue #1495) - Remove exception when PRM discovery fails completely - Fall back to root-level OAuth discovery for backward compatibility - When PRM unavailable, only check /.well-known/oauth-authorization-server - Maintains compatibility with legacy servers like Linear and Atlassian 2. Fix OAuth discovery URL ordering (issue #1623) - Only check path-based URLs when auth server URL contains a path - Prevents incorrectly discovering root AS when tenant-specific AS exists - Follows RFC 8414 priority: path-aware OAuth, then path-aware OIDC, then root - Fixes issue where root URLs were tried before path-based OIDC URLs Changes: - Renamed build_protected_resource_discovery_urls to build_protected_resource_metadata_discovery_urls - Renamed get_discovery_urls to build_oauth_authorization_server_metadata_discovery_urls - New function signature accepts optional auth_server_url and required server_url - Legacy behavior: when auth_server_url is None, only try root URL - Path-aware behavior: when auth_server_url has path, only try path-based URLs - Root behavior: when auth_server_url has no path, only try root URLs Breaking changes: - Some invalid server configurations will no longer work: - No PRM available and OASM at a path other than root - PRM returns auth server URL with path, but OASM only at root These configurations violate RFC specifications and are not expected to exist. Github-Issue: #1495 Github-Issue: #1623
This commit adds and updates tests to properly cover the new OAuth discovery logic for legacy server compatibility and path-aware discovery. New tests: - test_oauth_discovery_legacy_fallback_when_no_prm: Verifies that when PRM discovery fails, only root OAuth URL is tried (March 2025 spec) - test_oauth_discovery_path_aware_when_auth_server_has_path: Ensures path-based URLs are tried when auth server URL has a path - test_oauth_discovery_root_when_auth_server_has_no_path: Ensures root URLs are tried when auth server URL has no path - test_oauth_discovery_root_when_auth_server_has_only_slash: Handles trailing slash edge case - test_legacy_server_no_prm_falls_back_to_root_oauth_discovery: End-to-end test simulating Linear-style legacy servers - test_legacy_server_with_different_prm_and_root_urls: Tests fallback with custom WWW-Authenticate PRM URLs Updated tests: - test_oauth_discovery_fallback_conditions: Updated to reflect new path-aware discovery behavior (no root URLs when auth server has path) - test_oauth_discovery_fallback_order: Simplified to focus on path-aware case All tests pass with proper linting and type checking. Github-Issue: #1495 Github-Issue: #1623
LucaButBoring
pushed a commit
to LucaButBoring/mcp-python-sdk
that referenced
this pull request
Nov 17, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Motivation and Context
This PR addresses two related OAuth discovery issues that affect backward compatibility and correctness:
Issue #1495: Legacy Server Compatibility
Version 1.18.0 broke compatibility with legacy MCP servers (like Linear and Atlassian) that don't yet support Protected Resource Metadata (PRM) endpoints. The implementation raised an exception when PRM discovery failed, preventing fallback to the March 2025 spec behavior.
Issue #1623: Incorrect OAuth Discovery URL Priority
The OAuth discovery URL ordering was incorrect, causing the system to try root-level URLs before path-based OIDC URLs. This broke authentication with services like Jira MCP where tenant-specific authorization servers should take precedence over root-level servers.
Changes
1. Enable Fallback to March 2025 Spec (Issue #1495)
/.well-known/oauth-authorization-serverat the roothttps://mcp.linear.app/sse) and Atlassian (https://mcp.atlassian.com/v1/sse)2. Fix OAuth Discovery URL Ordering (Issue #1623)
Implementation Details
Function Renaming:
build_protected_resource_discovery_urls→build_protected_resource_metadata_discovery_urlsget_discovery_urls→build_oauth_authorization_server_metadata_discovery_urlsNew Behavior:
build_oauth_authorization_server_metadata_discovery_urls(auth_server_url: str | None, server_url: str)auth_server_urlisNone): Only try{root}/.well-known/oauth-authorization-serverauth_server_urlhas path like/tenant1): Only try path-based URLs in priority orderauth_server_urlis root likehttps://auth.example.com): Only try root URLsExamples
Example 1: Legacy Server (No PRM)
Example 2: Path-Aware Discovery
Example 3: Root Authorization Server
Breaking Changes
Some invalid server configurations will no longer work (these violate RFC specifications):
These configurations are not expected to exist in practice.
Testing
Additional Context
Related Issues
Fixes #1495
Fixes #1623