Derive the expected issuer before fetching authorization server metadata

The discovery step now knows which issuer the authorization server
metadata must carry before fetching it: the PRM-advertised server, or on
the 2025-03-26 no-PRM fallback the resource server's origin, which is
what that well-known URL is built from (RFC 8414 section 3.3). The
metadata issuer check runs on both paths instead of only when PRM was
found (on the no-PRM path a root issuer rendered with its trailing slash
still names the origin, and the origin is written the way metadata
issuers are, so host case or an explicit default port in `server_url`
do not matter). The SEP-2352 stored-credential binding is evaluated once
against that same value before metadata discovery, so it also applies
when no metadata is served and the default endpoints are used, and the
special case that re-evaluated it against the served issuer goes away;
newly registered clients are bound to it when metadata for it was found.

A 403 insufficient_scope step-up takes the same path as a 401. Until now
it re-authorized with whatever metadata was in memory, and with none
after a restart, in which case it used the 2025-03-26 default endpoints
on the resource server's origin regardless of what the server advertises
and never consulted the binding. It now discovers first when no metadata
is held (extract_resource_metadata_from_www_auth also reads the
`resource_metadata` hint from a 403 challenge), then re-authorizes with
the SEP-2350 scope union, keeping the granted scope in the union even if
discovery dropped the old token; metadata already discovered in this
process is reused as before. A 403 that is not a scope challenge is
handed back to the caller instead of being retried unchanged, as
IdentityAssertionOAuthProvider already does.

credentials_match_issuer treats a root issuer recorded with and without
its trailing slash as the same server, so records stamped in either form
keep matching on both paths.

This brings the no-PRM path in line with the TypeScript client, which
applies the section 3.3 check on every discovery path (that client also
offers an opt-out; this one does not, as on the PRM path since 2.0).

Author: maxisbey

docs/client/oauth-clients.md

@@ -76,7 +76,7 @@ Look at `main()`. The provider goes on the **httpx2 client**, the httpx2 client
 
 The first time `Client` sends a request, the server answers `401`. The provider takes over:
 
-1. **Discovery.** It reads the `WWW-Authenticate` header, fetches the server's Protected Resource Metadata from `/.well-known/oauth-protected-resource`, learns which authorization server protects this resource, and fetches *that* server's metadata.
+1. **Discovery.** It reads the `WWW-Authenticate` header, fetches the server's Protected Resource Metadata from `/.well-known/oauth-protected-resource`, learns which authorization server protects this resource, and fetches *that* server's metadata. (An older server that publishes no resource metadata is asked for authorization server metadata at its own origin instead.) Either way the metadata must name, as its `issuer`, the server it was fetched for; anything else is refused.
 2. **Registration.** Nothing in storage? It registers you dynamically with your `OAuthClientMetadata` and stores the result.
 3. **Authorization.** It generates the PKCE pair and a `state`, builds the authorization URL, awaits your `redirect_handler`, then awaits your `callback_handler` for the code.
 4. **Exchange.** It trades the code for an `OAuthToken`, stores it, and replays your original request with `Authorization: Bearer ...`.

docs/migration.md

@@ -2499,7 +2499,9 @@ metadata's `issuer` exactly matches the authorization server URL advertised in t
 resource metadata, as required by [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)
 section 3.3 ([SEP-2468](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2468)).
 The comparison is a simple string comparison ([RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
-section 6.2.1), so even a trailing-slash disagreement counts as a mismatch. v1 accepted the
+section 6.2.1), so even a trailing-slash disagreement counts as a mismatch. (For an older server
+that publishes no protected resource metadata the expected value is the MCP server's own origin,
+and there a root issuer with a trailing slash is accepted too.) v1 accepted the
 metadata without checking, so a server pairing whose two values disagree authenticated fine
 under v1 and now fails the entire flow. For example, when the MCP server's protected resource
 metadata advertises
@@ -2517,7 +2519,7 @@ OAuthFlowError: Authorization server metadata issuer mismatch: https://as.exampl
 
 There is no client-side override. Fix the deployment instead: make the authorization server's
 `issuer` string-equal the URL in the protected resource metadata's `authorization_servers`
-list. See [OAuth metadata URLs no longer gain a trailing slash](#oauth-metadata-urls-no-longer-gain-a-trailing-slash)
+list (or the MCP server's origin, without protected resource metadata). See [OAuth metadata URLs no longer gain a trailing slash](#oauth-metadata-urls-no-longer-gain-a-trailing-slash)
 for how v2 preserves the exact string form of these URLs.
 
 ### OAuth client requests `offline_access` and adds `prompt=consent` when the authorization server supports it ([SEP-2207](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2207))

src/mcp/client/auth/oauth2.py

@@ -17,7 +17,7 @@
 import anyio
 import httpx2
 from mcp_types.version import is_version_at_least
-from pydantic import BaseModel, Field, ValidationError
+from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
 
 from mcp.client.auth.exceptions import OAuthFlowError, OAuthRegistrationError, OAuthTokenError
 from mcp.client.auth.utils import (
@@ -276,6 +276,16 @@ def prepare_token_auth(
         return data, headers
 
 
+_ORIGIN_URL = TypeAdapter(AnyHttpUrl, config=ConfigDict(url_preserve_empty_path=True))
+
+
+def _origin_issuer(server_url: str) -> str:
+    """The resource server's origin as an issuer identifier: `scheme://authority`, rendered the way
+    `OAuthMetadata.issuer` renders URLs (host case, default ports) so the two compare as strings."""
+    parsed = urlparse(server_url)
+    return str(_ORIGIN_URL.validate_python(f"{parsed.scheme}://{parsed.netloc}"))
+
+
 class OAuthClientProvider(httpx2.Auth):
     """OAuth2 authentication for httpx2.
 
@@ -577,6 +587,12 @@ async def _validate_resource_match(self, prm: ProtectedResourceMetadata) -> None
         if not check_resource_allowed(requested_resource=default_resource, configured_resource=prm_resource):
             raise OAuthFlowError(f"Protected resource {prm_resource} does not match expected {default_resource}")
 
+    def _expected_issuer(self) -> str:
+        """The issuer that authorization server metadata and client credentials must belong to: the
+        PRM-advertised server, or on the legacy no-PRM path the resource server's origin, which is what
+        the 2025-03-26 well-known URL is built from (RFC 8414 §3.3)."""
+        return self.context.auth_server_url or _origin_issuer(self.context.server_url)
+
     async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
         """httpx2 auth flow integration."""
         async with self.context.lock:
@@ -600,107 +616,113 @@ async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx
 
             response = yield request
 
-            if response.status_code == 401:
+            step_up = (
+                response.status_code == 403 and extract_field_from_www_auth(response, "error") == "insufficient_scope"
+            )
+
+            if response.status_code == 401 or step_up:
                 # Perform full OAuth flow
                 try:
-                    # OAuth flow must be inline due to generator constraints
-                    www_auth_resource_metadata_url = extract_resource_metadata_from_www_auth(response)
+                    # Read before discovery, which may clear the tokens: on a restart the stored
+                    # token's scope is the only record of what was granted (see Step 3).
+                    granted_scope = self.context.current_tokens.scope if self.context.current_tokens else None
+
+                    # OAuth flow must be inline due to generator constraints.
+                    # Steps 1-2 run on every 401. A scope step-up reuses the metadata discovered earlier
+                    # in this process, and discovers it first when none is held yet (for example when
+                    # tokens were loaded from storage), so re-authorization targets the right server.
+                    if response.status_code == 401 or self.context.oauth_metadata is None:
+                        www_auth_resource_metadata_url = extract_resource_metadata_from_www_auth(response)
+
+                        # Step 1: Discover protected resource metadata (SEP-985 with fallback support)
+                        prm_discovery_urls = build_protected_resource_metadata_discovery_urls(
+                            www_auth_resource_metadata_url, self.context.server_url
+                        )
 
-                    # Step 1: Discover protected resource metadata (SEP-985 with fallback support)
-                    prm_discovery_urls = build_protected_resource_metadata_discovery_urls(
-                        www_auth_resource_metadata_url, self.context.server_url
-                    )
+                        for url in prm_discovery_urls:  # pragma: no branch
+                            discovery_request = create_oauth_metadata_request(url)
 
-                    for url in prm_discovery_urls:  # pragma: no branch
-                        discovery_request = create_oauth_metadata_request(url)
+                            discovery_response = yield discovery_request  # sending request
 
-                        discovery_response = yield discovery_request  # sending request
+                            prm = await handle_protected_resource_response(discovery_response)
+                            if prm:
+                                # Validate PRM resource matches server URL (RFC 8707)
+                                await self._validate_resource_match(prm)
+                                self.context.protected_resource_metadata = prm
 
-                        prm = await handle_protected_resource_response(discovery_response)
-                        if prm:
-                            # Validate PRM resource matches server URL (RFC 8707)
-                            await self._validate_resource_match(prm)
-                            self.context.protected_resource_metadata = prm
+                                # todo: try all authorization_servers to find the OASM
+                                assert (
+                                    len(prm.authorization_servers) > 0
+                                )  # this is always true as authorization_servers has a min length of 1
 
-                            # todo: try all authorization_servers to find the OASM
-                            assert (
-                                len(prm.authorization_servers) > 0
-                            )  # this is always true as authorization_servers has a min length of 1
+                                self.context.auth_server_url = str(prm.authorization_servers[0])
+                                break
+                            else:
+                                logger.debug(f"Protected resource metadata discovery failed: {url}")
 
-                            self.context.auth_server_url = str(prm.authorization_servers[0])
-                            break
-                        else:
-                            logger.debug(f"Protected resource metadata discovery failed: {url}")
-
-                    # SEP-2352: stored credentials are bound to the issuer that registered them.
-                    # If the authorization server changed, drop them (and the old tokens) so the
-                    # flow re-registers instead of presenting another server's credentials.
-                    if (
-                        self.context.client_info is not None
-                        and self.context.auth_server_url is not None
-                        and not credentials_match_issuer(
-                            self.context.client_info, self.context.auth_server_url, self.context.client_metadata_url
-                        )
-                    ):
-                        logger.debug("Authorization server changed; discarding bound credentials and re-registering")
-                        self.context.client_info = None
-                        self.context.clear_tokens()
-                        # Any cached AS metadata is for the old server; drop it so a failed
-                        # rediscovery cannot leak the old registration/token endpoints into Step 4.
-                        self.context.oauth_metadata = None
-
-                    asm_discovery_urls = build_oauth_authorization_server_metadata_discovery_urls(
-                        self.context.auth_server_url, self.context.server_url
-                    )
+                        expected_issuer = self._expected_issuer()
 
-                    # Step 2: Discover OAuth Authorization Server Metadata (OASM) (with fallback for legacy servers)
-                    for url in asm_discovery_urls:  # pragma: no branch
-                        oauth_metadata_request = create_oauth_metadata_request(url)
-                        oauth_metadata_response = yield oauth_metadata_request
-
-                        ok, asm = await handle_auth_metadata_response(oauth_metadata_response)
-                        if not ok:
-                            break
-                        if ok and asm:
-                            # SEP-2468: metadata issuer must match the discovery issuer
-                            if self.context.auth_server_url is not None:
-                                validate_metadata_issuer(asm, self.context.auth_server_url)
-                            self.context.oauth_metadata = asm
-                            break
-                        else:
-                            logger.debug(f"OAuth metadata discovery failed: {url}")
-
-                    # SEP-2352: on the legacy no-PRM path the issuer is only known after ASM
-                    # discovery, so re-evaluate the binding here using the discovered metadata
-                    # issuer (mirroring the bound_issuer fallback in Step 4).
-                    if (
-                        self.context.client_info is not None
-                        and self.context.auth_server_url is None
-                        and self.context.oauth_metadata is not None
-                        and not credentials_match_issuer(
-                            self.context.client_info,
-                            str(self.context.oauth_metadata.issuer),
-                            self.context.client_metadata_url,
+                        # SEP-2352: stored credentials are bound to the issuer that registered them.
+                        # Decided before any metadata is fetched: if the expected issuer is a different
+                        # server, drop them (and the old tokens) so the flow re-registers instead of
+                        # presenting another server's credentials.
+                        if self.context.client_info is not None and not credentials_match_issuer(
+                            self.context.client_info, expected_issuer, self.context.client_metadata_url
+                        ):
+                            logger.debug(
+                                "Authorization server changed; discarding bound credentials and re-registering"
+                            )
+                            self.context.client_info = None
+                            self.context.clear_tokens()
+                            # Any cached AS metadata is for the old server; drop it so a failed
+                            # rediscovery cannot leak the old registration/token endpoints into Step 4.
+                            self.context.oauth_metadata = None
+
+                        asm_discovery_urls = build_oauth_authorization_server_metadata_discovery_urls(
+                            self.context.auth_server_url, self.context.server_url
                         )
-                    ):
-                        logger.debug("Authorization server changed; discarding bound credentials and re-registering")
-                        self.context.client_info = None
-                        self.context.clear_tokens()
+
+                        # Step 2: Discover OAuth Authorization Server Metadata (OASM) (with fallback for legacy servers)
+                        for url in asm_discovery_urls:  # pragma: no branch
+                            oauth_metadata_request = create_oauth_metadata_request(url)
+                            oauth_metadata_response = yield oauth_metadata_request
+
+                            ok, asm = await handle_auth_metadata_response(oauth_metadata_response)
+                            if not ok:
+                                break
+                            if ok and asm:
+                                # SEP-2468 / RFC 8414 §3.3: the metadata must name the expected issuer.
+                                # On the legacy path a root issuer rendered with its trailing slash
+                                # names the same origin.
+                                if self.context.auth_server_url is None and str(asm.issuer) == f"{expected_issuer}/":
+                                    expected_issuer = str(asm.issuer)
+                                validate_metadata_issuer(asm, expected_issuer)
+                                self.context.oauth_metadata = asm
+                                break
+                            else:
+                                logger.debug(f"OAuth metadata discovery failed: {url}")
 
                     # Step 3: Apply scope selection strategy
-                    self.context.client_metadata.scope = get_client_metadata_scopes(
+                    challenged_scope = get_client_metadata_scopes(
                         extract_scope_from_www_auth(response),
                         self.context.protected_resource_metadata,
                         self.context.oauth_metadata,
                         self.context.client_metadata.grant_types,
                     )
+                    if step_up:
+                        # SEP-2350: union previously requested scopes with the newly challenged ones so
+                        # escalating one operation keeps the others' grants, folding in the granted
+                        # scope read above since client_metadata.scope is not reloaded on a restart.
+                        prior_scope = union_scopes(self.context.client_metadata.scope, granted_scope)
+                        self.context.client_metadata.scope = union_scopes(prior_scope, challenged_scope)
+                    else:
+                        self.context.client_metadata.scope = challenged_scope
 
                     # Step 4: Register client or use URL-based client ID (CIMD)
                     if not self.context.client_info:
-                        # SEP-2352: the issuer to bind these credentials to, when known.
-                        discovered_issuer: str | None = None
-                        if self.context.oauth_metadata is not None:
-                            discovered_issuer = self.context.auth_server_url or str(self.context.oauth_metadata.issuer)
+                        # SEP-2352: the issuer to bind these credentials to, once metadata for it
+                        # was actually found.
+                        discovered_issuer = self._expected_issuer() if self.context.oauth_metadata is not None else None
 
                         if should_use_client_metadata_url(
                             self.context.oauth_metadata, self.context.client_metadata_url
@@ -752,34 +774,3 @@ async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx
                 # Retry with new tokens
                 self._add_auth_header(request)
                 yield request
-            elif response.status_code == 403:
-                # Step 1: Extract error field from WWW-Authenticate header
-                error = extract_field_from_www_auth(response, "error")
-
-                # Step 2: Check if we need to step-up authorization
-                if error == "insufficient_scope":  # pragma: no branch
-                    try:
-                        # Step 2a: Union previously requested scopes with the newly challenged
-                        # scopes (SEP-2350) so escalating one operation keeps the others' grants.
-                        # Fold in the stored token's scope too: on a restart the token is reloaded
-                        # but client_metadata.scope is not, so it would otherwise be the only basis.
-                        challenged_scope = get_client_metadata_scopes(
-                            extract_scope_from_www_auth(response),
-                            self.context.protected_resource_metadata,
-                            self.context.oauth_metadata,
-                            self.context.client_metadata.grant_types,
-                        )
-                        granted_scope = self.context.current_tokens.scope if self.context.current_tokens else None
-                        prior_scope = union_scopes(self.context.client_metadata.scope, granted_scope)
-                        self.context.client_metadata.scope = union_scopes(prior_scope, challenged_scope)
-
-                        # Step 2b: Perform (re-)authorization and token exchange
-                        token_response = yield await self._perform_authorization()
-                        await self._handle_token_response(token_response)
-                    except Exception:  # pragma: no cover
-                        logger.exception("OAuth flow error")
-                        raise
-
-                # Retry with new tokens
-                self._add_auth_header(request)
-                yield request