Derive the expected issuer before fetching authorization server metadata

Discovery now chooses its authorization server, and with it the issuer the
metadata must carry (RFC 8414 section 3.3), before any metadata is fetched:
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.
The issuer check runs on both paths instead of only when PRM was found; the
SEP-2352 credential binding is decided against that same value before the
fetch, so it also applies when no metadata is served and the default
endpoints are used; newly registered clients are bound to it when metadata
for it was found; and a pass replaces what an earlier pass discovered once
it has chosen a server and looked for its metadata, so nothing left over
from before feeds a later registration. The special case that re-checked the
binding against the served issuer goes away.

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), re-checks the binding either way, and then
re-authorizes with the SEP-2350 scope union, keeping the granted scope in
the union even when the server changed; metadata already discovered in this
process is reused as before, so for a server that publishes none each
step-up repeats the discovery requests. A 403 that is not a scope challenge
is handed back to the caller instead of being retried unchanged. This is the
shape IdentityAssertionOAuthProvider already uses.

Issuer strings are compared after parsing both sides the way the metadata
`issuer` is parsed (scheme and host case, default ports, IDNA), with one
tolerance beyond that: an origin with an empty path and the same origin
with a lone "/" are the same issuer, since servers commonly render a root
issuer with a trailing slash and both forms yield the same well-known URL.
validate_metadata_issuer, credentials_match_issuer and the new issuers_equal
share that rule. IdentityAssertionOAuthProvider passes the issuer as the
metadata states it to the assertion provider, so the ID-JAG audience is the
server's own spelling either way. docs/migration.md and the identity
assertion page describe the comparison as it now is.

This brings the no-PRM path in line with the TypeScript client, which
applies the section 3.3 check on every discovery path.

Author: maxisbey

docs/client/identity-assertion.md

@@ -49,13 +49,16 @@ Here is the inversion. `OAuthClientProvider` asks the resource server which auth
 The extension does not demand this; it is a deliberately stricter choice. This client carries two things worth stealing, a pre-registered secret and an audience-bound assertion, and a client that let a compromised MCP server steer it to an attacker's authorization server would post both to it. Pinning the issuer at construction deletes that conversation.
 
 !!! warning
-    The configured `issuer` is compared to the metadata document's `issuer` field by RFC 8414 §3.3
-    simple string comparison: character for character, trailing slash included, no normalization.
-    Do not guess it. Fetch `/.well-known/oauth-authorization-server` from your authorization server
-    and copy the `issuer` value it returns. For the authorization server on this page that is
-    `https://auth.example.com/`, with the slash, because its issuer was built from a pydantic URL
-    object. A mismatch stops the flow at `OAuthFlowError: Authorization server metadata issuer
-    mismatch` before a single credential or assertion is sent.
+    The configured `issuer` is compared to the metadata document's `issuer` field (RFC 8414 §3.3)
+    after both are parsed as URLs the way the SDK parses that field, so spellings of the same URL
+    (scheme and host case, an explicit default port) compare equal, and `https://auth.example.com`
+    and `https://auth.example.com/` count as the same issuer; a different path, port or host, or a
+    trailing slash on a path, is a mismatch. The
+    safest value is the one the server states: fetch `/.well-known/oauth-authorization-server`
+    from your authorization server and copy the `issuer` it returns. A mismatch stops the flow at
+    `OAuthFlowError: Authorization server metadata issuer mismatch` before a single credential or
+    assertion is sent. The `audience` your callback receives is the issuer exactly as the
+    metadata states it, so the ID-JAG's `aud` is always the server's own spelling.
 
 ### A confidential client
 
@@ -140,7 +143,7 @@ And notice what the returned `OAuthToken` does not carry: a refresh token. The I
 * [SEP-990](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/990) lets the enterprise identity provider, not the end user, decide which MCP servers a client may reach. The IdP signs that decision into an **ID-JAG**.
 * Obtaining the ID-JAG is an [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) token exchange against *your IdP*, and the SDK does not make it. Presenting it to the MCP authorization server is the [RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523) `jwt-bearer` grant, and the SDK does both sides of that.
 * `IdentityAssertionOAuthProvider` is another `httpx2.Auth`: a pre-registered confidential client, a pinned `issuer`, and one `assertion_provider(audience, resource)` callback. No browser, no registration, no refresh token.
-* The authorization server is never discovered from the resource server. Configure `issuer` to exactly the string its metadata document serves; the comparison is character for character.
+* The authorization server is never discovered from the resource server. Configure `issuer` to the string its metadata document serves; different spellings of the same URL (scheme and host case, a default port, `https://host` versus `https://host/`) are accepted, a different URL is not.
 * Server side, `identity_assertion_enabled=True` plus `exchange_identity_assertion`. The SDK authenticates the client and gates the grant; validating the ID-JAG is entirely yours, and the issued token is bound to the ID-JAG's `resource`, not the request's.
 
 The one party this page never touched is the MCP server. What it does with the token you just minted, it was already doing in **[Authorization](../run/authorization.md)**.

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

@@ -2495,11 +2495,16 @@ If you passed `timeout` to bound how long you wait for the user to complete auth
 ### Client rejects authorization server metadata with a mismatched `issuer`
 
 During OAuth discovery, `OAuthClientProvider` now validates that the authorization server
-metadata's `issuer` exactly matches the authorization server URL advertised in the protected
-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
+metadata's `issuer` is the authorization server it expected, 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 URL
+advertised in the protected resource metadata's `authorization_servers`, or, for an older
+server that publishes no protected resource metadata, the MCP server's own origin (where the
+2025-03-26 fallback looks for the metadata). The two values are compared after both are parsed
+as URLs the way the SDK parses the metadata field, so spellings of the same URL (scheme and host
+case, an explicit default port) compare equal, and `https://as.example.com` and
+`https://as.example.com/` count as the same issuer; a different path, port or host, or a
+trailing slash on a path, is a mismatch. 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
@@ -2508,16 +2513,17 @@ metadata advertises
 {"authorization_servers": ["https://as.example.com"]}
 ```
 
-while the authorization server's RFC 8414 metadata says `"issuer": "https://as.example.com/"`,
+while the authorization server's RFC 8414 metadata says `"issuer": "https://as.example.com/auth"`,
 v1 completes discovery and proceeds with the flow; v2 aborts with:
 
 ```text
-OAuthFlowError: Authorization server metadata issuer mismatch: https://as.example.com/ != https://as.example.com
+OAuthFlowError: Authorization server metadata issuer mismatch: https://as.example.com/auth != https://as.example.com
 ```
 
 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)
+`issuer` name the same server as the URL in the protected resource metadata's
+`authorization_servers` list (or, without protected resource metadata, as the MCP server's
+origin). 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/extensions/identity_assertion.py

@@ -14,9 +14,10 @@
 
 Obtaining the ID-JAG (logging into the IdP and the leg-1 token exchange against it) is
 deployment-specific and out of scope for the SDK. The caller supplies it through the
-`assertion_provider` callback, which receives the configured issuer (the `aud` the ID-JAG must
-carry) and the MCP server's resource identifier (the `resource` claim it must carry, per ext-auth
-section 4.3), and returns the ID-JAG.
+`assertion_provider` callback, which receives the authorization server's issuer as its metadata
+states it (the `aud` the ID-JAG must carry; it names the configured issuer) and the MCP server's
+resource identifier (the `resource` claim it must carry, per ext-auth section 4.3), and returns the
+ID-JAG.
 """
 
 import base64
@@ -67,7 +68,7 @@ class IdentityAssertionOAuthProvider(httpx2.Auth):
     Example:
         ```python
         async def fetch_id_jag(audience: str, resource: str) -> str:
-            # `audience` is the configured issuer (the ID-JAG `aud`); `resource` is the MCP
+            # `audience` is the authorization server's issuer (the ID-JAG `aud`); `resource` is the MCP
             # server's identifier (the ID-JAG `resource` claim). Obtaining the ID-JAG from the
             # enterprise IdP is deployment-specific and not handled by the SDK.
             return await my_idp.issue_id_jag(audience=audience, resource=resource)
@@ -107,8 +108,9 @@ def __init__(
             issuer: The issuer identifier of the MCP authorization server this client is provisioned
                 for. Authorization-server metadata is fetched from this issuer's well-known and the
                 ID-JAG and secret are sent only to its token endpoint.
-            assertion_provider: Async callback taking `(audience, resource)` - the configured issuer
-                and the MCP server's resource identifier - and returning the ID-JAG.
+            assertion_provider: Async callback taking `(audience, resource)` - the authorization
+                server's issuer exactly as its metadata states it (it names the same server as the
+                configured `issuer`) and the MCP server's resource identifier - and returning the ID-JAG.
             scope: Optional space-separated list of scopes to request.
             token_endpoint_auth_method: Confidential-client auth method, either `client_secret_post`
                 (default) or `client_secret_basic`.
@@ -131,6 +133,7 @@ def __init__(
             issuer=issuer,
         )
         self._token_endpoint: str | None = None
+        self._audience: str | None = None
         self._tokens: OAuthToken | None = None
         self._expiry: float | None = None
         self._lock = anyio.Lock()
@@ -193,11 +196,13 @@ async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx
                                 f"Token endpoint {token_endpoint} is not on the configured issuer origin {self._issuer}"
                             )
                         self._token_endpoint = token_endpoint
+                        self._audience = str(asm.issuer)
                         break
                 if self._token_endpoint is None:
                     raise OAuthFlowError(f"No authorization server metadata at configured issuer {self._issuer}")
 
-            assertion = await self._assertion_provider(self._issuer, self._resource)
+            assert self._audience is not None
+            assertion = await self._assertion_provider(self._audience, self._resource)
             token_response = yield self._build_token_request(scope_to_request, assertion)
             if token_response.status_code != 200:
                 body = (await token_response.aread()).decode(errors="replace")