Skip to content

Conversation

LucaButBoring
Copy link
Contributor

Implements basic OIDC support for working with authorization servers that don't expose OAuth metadata, following the semantics described in RFC 8414 Section 5.

As part of this change, I modified the internal fallback behavior from a simple boolean flag to instead represent discovery as a stack of methods, which are consumed sequentially until one fallback method succeeds. This also helps clean up the duplicated code from working with AsyncGenerator.

Motivation and Context

Enables falling back to OIDC 1.0 metadata when a server does not support OAuth metadata according to RFC 8414.

How Has This Been Tested?

Added/updated unit tests.

Breaking Changes

None

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

#976

@ihrpr
Copy link
Contributor

ihrpr commented Jul 7, 2025

Thank you! Sorry, we had back and forth with this spec changes. For now it's on hold until modelcontextprotocol/modelcontextprotocol#797 is merged

@ihrpr ihrpr added this to the auth milestone Jul 7, 2025
Copy link
Member

@dsp-ant dsp-ant left a comment

Choose a reason for hiding this comment

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

I'll add a claude generated review in addition, since I reviewed it and found it quite useful.

@dsp-ant
Copy link
Member

dsp-ant commented Jul 15, 2025

Here is Claude's take, which in this instance, I found helpful:

Thank you for implementing RFC 9728 support with OIDC fallback functionality. While the implementation works, I have concerns about the complexity of the approach, particularly around the callback-based discovery stack pattern.

Main Concerns

1. Over-engineered Discovery Stack Pattern

The current implementation uses a callback-based stack with function references:

OAuthDiscoveryStack = list[Callable[[], Awaitable[httpx.Request]]]

This pattern, combined with stack reversal and while-loop popping, adds unnecessary complexity:

  • The callbacks don't encapsulate varying behavior - they just generate URLs
  • The stack reversal (discovery_attempts.reverse()) followed by pop() is non-idiomatic
  • while len(oauth_discovery_stack) > 0: should be while oauth_discovery_stack:

2. Scattered URL Building Logic

The implementation has four separate methods for URL construction:

  • _build_well_known_path()
  • _build_well_known_fallback_url()
  • _build_oidc_fallback_path()
  • _build_oidc_fallback_url()

This fragmentation makes it harder to understand the discovery order and URL patterns.

3. Unnecessary State Management

The code stores intermediate state as instance variables:

self.context.discovery_base_url = base_url
self.context.discovery_pathname = parsed.path

These are only used for fallback logic and could be handled more cleanly.

Suggested Simplification

Replace the callback stack with a straightforward URL list approach:

def _get_discovery_urls(self) -> list[tuple[str, str]]:
    """Generate ordered list of (url, type) tuples for discovery attempts."""
    urls = []
    auth_server_url = self.context.auth_server_url or self.context.server_url
    parsed = urlparse(auth_server_url)
    base_url = f"{parsed.scheme}://{parsed.netloc}"
    
    # RFC 8414: Path-aware OAuth discovery
    if parsed.path and parsed.path != "/":
        oauth_path = f"/.well-known/oauth-authorization-server{parsed.path.rstrip('/')}"
        urls.append((urljoin(base_url, oauth_path), "oauth"))
    
    # OAuth root fallback
    urls.append((urljoin(base_url, "/.well-known/oauth-authorization-server"), "oauth"))
    
    # RFC 8414 section 5: Path-aware OIDC discovery  
    if parsed.path and parsed.path != "/":
        oidc_path = f"/.well-known/openid-configuration{parsed.path.rstrip('/')}"
        urls.append((urljoin(base_url, oidc_path), "oidc"))
    
    # OIDC 1.0 fallback (appends to full URL per spec)
    oidc_fallback = urljoin(auth_server_url.rstrip("/"), "/.well-known/openid-configuration")
    urls.append((oidc_fallback, "oidc"))
    
    return urls

Then in async_auth_flow():

# Step 2: Discover OAuth metadata (with fallback for legacy servers)
discovery_urls = self._get_discovery_urls()
for url, discovery_type in discovery_urls:
    request = httpx.Request("GET", url, headers={MCP_PROTOCOL_VERSION: LATEST_PROTOCOL_VERSION})
    response = yield request
    
    if response.status_code == 200:
        try:
            content = await response.aread()
            metadata = OAuthMetadata.model_validate_json(content)
            self.context.oauth_metadata = metadata
            # Apply default scope if needed
            if self.context.client_metadata.scope is None and metadata.scopes_supported is not None:
                self.context.client_metadata.scope = " ".join(metadata.scopes_supported)
            break
        except ValidationError:
            continue
    elif response.status_code != 404:
        break  # Non-404 error, stop trying

Benefits of This Approach

  1. Explicit discovery order: All URLs are visible in one place
  2. No callbacks: Direct, simple URL generation
  3. Pythonic iteration: Standard for-loop instead of while/pop
  4. Less state: No instance variables for intermediate values
  5. Easier testing: URL generation can be unit tested separately
  6. Clearer intent: The fallback chain is immediately apparent

Minor Issues

  • Line 295: Use return response_status == 404 and discovery_stack instead of len(discovery_stack) > 0
  • The comment on line 577-578 about declaring the stack backwards is a code smell

Overall

The implementation is functionally correct and follows the RFCs properly. My suggestions are about reducing complexity and making the code more Pythonic. The callback pattern might make sense in other contexts, but here it adds unnecessary abstraction for what is essentially "try these URLs in order until one works."

Would you consider simplifying the approach? Happy to discuss further or help with the refactoring.

@dsp-ant
Copy link
Member

dsp-ant commented Jul 15, 2025

@ihrpr how do you want to sequence this? My suggestion is waiting for this PR to be in an acceptable state, then merge the spec change and the python sdk pr at the same time.

@LucaButBoring
Copy link
Contributor Author

Will make the changes by EOD tomorrow (juggling other things as well) - I agree with what you called out in general.


For context, the reason I did it like this originally was because the entire OAuth flow was duplicated in the async_auth_flow function due to generator syntax limitations, so I was attempting to avoid explicitly writing the entire fallback sequence twice. #1071 was merged earlier today which was able to remove the duplicated OAuth flow, so the discovery stack thing doesn't make sense anymore.

@ihrpr ihrpr linked an issue Jul 16, 2025 that may be closed by this pull request
@ihrpr
Copy link
Contributor

ihrpr commented Jul 16, 2025

@ihrpr how do you want to sequence this? My suggestion is waiting for this PR to be in an acceptable state, then merge the spec change and the python sdk pr at the same time.

yes, that works, adding tracking for this as well

@LucaButBoring LucaButBoring requested a review from dsp-ant July 16, 2025 19:09
Copy link
Member

@dsp-ant dsp-ant left a comment

Choose a reason for hiding this comment

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

LGTM

@dsp-ant dsp-ant merged commit 99c4f3c into modelcontextprotocol:main Jul 17, 2025
10 checks passed
@LucaButBoring LucaButBoring deleted the feat/oidc-fallback branch August 1, 2025 16:12
saqadri pushed a commit to saqadri/stdio-fixes that referenced this pull request Aug 6, 2025
rbehal pushed a commit to gumloop/gumloop-mcp that referenced this pull request Sep 25, 2025
* Add regression test for stateless request memory cleanup (modelcontextprotocol#1140)

* Implement RFC9728 - Support WWW-Authenticate header by MCP client (modelcontextprotocol#1071)

* Add streamable HTTP starlette example to Python SDK docs (modelcontextprotocol#1111)

* fix markdown error in README in main (modelcontextprotocol#1147)

* README - replace code snippets with examples - add lowlevel to snippets (modelcontextprotocol#1150)

* README - replace code snippets with examples - streamable http (modelcontextprotocol#1155)

* chore: don't allow users to create issues outside the templates (modelcontextprotocol#1163)

* Tests(cli): Add coverage for helper functions (modelcontextprotocol#635)

* Docs: Update CallToolResult parsing in README (modelcontextprotocol#812)

Co-authored-by: Felix Weinberger <[email protected]>

* docs: add pre-commit install guide on CONTRIBUTING.md (modelcontextprotocol#995)

Co-authored-by: Felix Weinberger <[email protected]>

* fix flaky fix-test_streamablehttp_client_resumption test (modelcontextprotocol#1166)

* README - replace code snippets with examples -- auth examples (modelcontextprotocol#1164)

* Support falling back to OIDC metadata for auth (modelcontextprotocol#1061)

* Add CODEOWNERS file for sdk (modelcontextprotocol#1169)

* fix flaky test test_88_random_error (modelcontextprotocol#1171)

* Make sure `RequestId` is not coerced as `int` (modelcontextprotocol#1178)

* Fix: Replace threading.Lock with anyio.Lock for Ray deployment compatibility (modelcontextprotocol#1151)

* fix: fix OAuth flow request object handling (modelcontextprotocol#1174)

* update codeowners group (modelcontextprotocol#1191)

* fix: perform auth server metadata discovery fallbacks on any 4xx (modelcontextprotocol#1193)

* server: skip duplicate response on CancelledError (modelcontextprotocol#1153)

Co-authored-by: ihrpr <[email protected]>

* Unpack settings in FastMCP (modelcontextprotocol#1198)

* chore: Remove unused prompt_manager.py file (modelcontextprotocol#1229)

Co-authored-by: Tapan Chugh <[email protected]>

* Improved supported for ProtectedResourceMetadata (modelcontextprotocol#1235)

Co-authored-by: Paul Carleton <[email protected]>

* chore: Remove unused variable notification_options (modelcontextprotocol#1238)

* Improve README around the Context object (modelcontextprotocol#1203)

* fix: allow to pass `list[str]` to `token_endpoint_auth_signing_alg_values_supported` (modelcontextprotocol#1226)

* Remove strict validation on `response_modes_supported` member of `OAuthMetadata` (modelcontextprotocol#1243)

* Add pyright strict mode on the whole project (modelcontextprotocol#1254)

* Consistent casing for default headers Accept and Content-Type (modelcontextprotocol#1263)

* Update dependencies and fix type issues (modelcontextprotocol#1268)

Co-authored-by: Marcelo Trylesinski <[email protected]>

* fix: prevent async generator cleanup errors in StreamableHTTP transport (modelcontextprotocol#1271)

Co-authored-by: David Soria Parra <[email protected]>

* chore: uncomment .idea/ in .gitignore (modelcontextprotocol#1287)

Co-authored-by: Claude <[email protected]>

* docs: clarify streamable_http_path configuration when mounting servers (modelcontextprotocol#1172)

* feat: Add CORS configuration for browser-based MCP clients (modelcontextprotocol#1059)

Co-authored-by: Marcelo Trylesinski <[email protected]>
Co-authored-by: Felix Weinberger <[email protected]>

* Added Audio to FastMCP (modelcontextprotocol#1130)

* fix: avoid uncessary retries in OAuth authenticated requests (modelcontextprotocol#1206)

Co-authored-by: Felix Weinberger <[email protected]>

* Add PATHEXT to default STDIO env vars in windows (modelcontextprotocol#1256)

* fix: error too many values to unpack (expected 2) (modelcontextprotocol#1279)

Signed-off-by: San Nguyen <[email protected]>
Co-authored-by: Felix Weinberger <[email protected]>
Co-authored-by: Felix Weinberger <[email protected]>

* SDK Parity: Avoid Parsing Server Response for non-JsonRPCMessage Requests (modelcontextprotocol#1290)

* types: Setting default value for method: Literal (modelcontextprotocol#1292)

* changes structured temperature to not deadly (modelcontextprotocol#1328)

* Update simple-resource example to use non-deprecated read_resource return type (modelcontextprotocol#1331)

Co-authored-by: Claude <[email protected]>

* docs: Update README to include link to API docs for modelcontextprotocol#1329 (modelcontextprotocol#1330)

* Allow ping requests before initialization (modelcontextprotocol#1312)

* Python lint: Ruff rules for pylint and code complexity (modelcontextprotocol#525)

* Fix context injection for resources and prompts (modelcontextprotocol#1336)

* fix(fastmcp): propagate mimeType in resource template list (modelcontextprotocol#1186)

Co-authored-by: Felix Weinberger <[email protected]>

* fix: allow elicitations accepted without content (modelcontextprotocol#1285)

Co-authored-by: Olivier Schiavo <[email protected]>

* Use --frozen in pre-commit config (modelcontextprotocol#1375)

* Return HTTP 403 for invalid Origin headers (modelcontextprotocol#1353)

* Add test for ProtectedResourceMetadataParsing (modelcontextprotocol#1236)

Co-authored-by: Paul Carleton <[email protected]>
Co-authored-by: Marcelo Trylesinski <[email protected]>
Co-authored-by: Felix Weinberger <[email protected]>

* Fastmcp logging progress example (modelcontextprotocol#1270)

Co-authored-by: Felix Weinberger <[email protected]>

* feat: add paginated list decorators for prompts, resources, and tools (modelcontextprotocol#1286)

Co-authored-by: Claude <[email protected]>

* Remove "unconditionally" from conditional description (modelcontextprotocol#1289)

* Use streamable-http consistently in examples (modelcontextprotocol#1389)

* feat: Add SDK support for SEP-1034 default values in elicitation schemas (modelcontextprotocol#1337)

Co-authored-by: Tapan Chugh <[email protected]>
Co-authored-by: Felix Weinberger <[email protected]>

* Implementation of SEP 973 - Additional metadata + icons support (modelcontextprotocol#1357)

* Merge upstream/main with custom filtering

---------

Signed-off-by: San Nguyen <[email protected]>
Co-authored-by: Felix Weinberger <[email protected]>
Co-authored-by: yurikunash <[email protected]>
Co-authored-by: Pamela Fox <[email protected]>
Co-authored-by: Inna Harper <[email protected]>
Co-authored-by: Marcelo Trylesinski <[email protected]>
Co-authored-by: Ian Davenport <[email protected]>
Co-authored-by: Dagang Wei <[email protected]>
Co-authored-by: Felix Weinberger <[email protected]>
Co-authored-by: Stanley Law <[email protected]>
Co-authored-by: Luca Chang <[email protected]>
Co-authored-by: leweng <[email protected]>
Co-authored-by: Clare Liguori <[email protected]>
Co-authored-by: lukacf <[email protected]>
Co-authored-by: ihrpr <[email protected]>
Co-authored-by: Tapan Chugh <[email protected]>
Co-authored-by: Tapan Chugh <[email protected]>
Co-authored-by: Yann Jouanin <[email protected]>
Co-authored-by: Paul Carleton <[email protected]>
Co-authored-by: Sreenath Somarajapuram <[email protected]>
Co-authored-by: Omer Korner <[email protected]>
Co-authored-by: joesavage-silabs <[email protected]>
Co-authored-by: Gregory L <[email protected]>
Co-authored-by: David Soria Parra <[email protected]>
Co-authored-by: Moustapha Ebnou <[email protected]>
Co-authored-by: Max Isbey <[email protected]>
Co-authored-by: Claude <[email protected]>
Co-authored-by: Jerome <[email protected]>
Co-authored-by: xavier <[email protected]>
Co-authored-by: keurcien <[email protected]>
Co-authored-by: Tim Esler <[email protected]>
Co-authored-by: San Nguyen <[email protected]>
Co-authored-by: Justin Wang <[email protected]>
Co-authored-by: jess <[email protected]>
Co-authored-by: Peter Alexander <[email protected]>
Co-authored-by: Reid Geyer <[email protected]>
Co-authored-by: Eleftheria Stein-Kousathana <[email protected]>
Co-authored-by: Christian Clauss <[email protected]>
Co-authored-by: pchoudhury22 <[email protected]>
Co-authored-by: owengo <[email protected]>
Co-authored-by: Olivier Schiavo <[email protected]>
Co-authored-by: Steve Billings <[email protected]>
Co-authored-by: Mike Salvatore <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

enhance auth server discovery with OAuth2 and OIDC metadata support
3 participants