Use issuer_url for OAuth issuer identity (#4652)

* Use issuer_url for OAuth issuer identity, not base_url

* Apply ruff format to issuer identity tests

* Align ID-JAG audience docstring with issuer_url

* Make InMemoryOAuthProvider keyword-only like its parent

* Keep ID-JAG audience on base_url, out of scope for issuer identity

* Remove stray scratch script

* Make AuthorizationHandler keyword-only

* Bind ID-JAG audience to the issuer identifier

* Fix double slash in issuer_url well-known log hint

Author: jlowin

docs/deployment/http.mdx

@@ -544,7 +544,7 @@ base_url="http://localhost:8000/api"  # Includes mount prefix
 mcp_path="/mcp"  # Internal MCP path, NOT the mount prefix
 ```
 
-**`issuer_url`** (optional) controls the authorization server identity for OAuth discovery. Defaults to `base_url`.
+**`issuer_url`** (optional) controls the authorization server identity for OAuth discovery. Defaults to `base_url`. It sets the `issuer` advertised in the authorization server metadata and the `iss` on issued tokens, while the endpoints in that metadata continue to point at `base_url`.
 
 ```python
 # Usually not needed - just set base_url and it works

docs/servers/auth/oauth-proxy.mdx

@@ -135,6 +135,8 @@ mcp = FastMCP(name="My Server", auth=auth)
 <ParamField body="issuer_url" type="AnyHttpUrl | str | None">
   Issuer URL for OAuth authorization server metadata (defaults to `base_url`).
 
+  `issuer_url` is the server's OAuth identity: it is the `issuer` field of the authorization server metadata, the `iss` claim of the tokens the proxy mints, and the RFC 9207 `iss` parameter on authorization responses. `base_url` remains the location of the endpoints, so `authorization_endpoint`, `token_endpoint`, and the rest of the metadata still point at `base_url` where the routes are actually mounted.
+
   When `issuer_url` has a path component (either explicitly or by defaulting from `base_url`), FastMCP creates path-aware discovery routes per RFC 8414. For example, if `base_url` is `http://localhost:8000/api`, the authorization server metadata will be at `/.well-known/oauth-authorization-server/api`.
 
   **Default behavior (recommended for most cases):**
@@ -718,7 +720,7 @@ For each ID-JAG presented at the token endpoint, the proxy checks that:
 - the JOSE header `typ` is `oauth-id-jag+jwt`;
 - the `iss` claim is one of the configured `trusted_issuers`;
 - the signature verifies against the issuer's published keys;
-- the `aud` claim identifies this authorization server;
+- the `aud` claim identifies this authorization server — configure your identity provider to mint assertions whose `aud` is the `issuer` value published at `/.well-known/oauth-authorization-server`, which is your `issuer_url` when you set one and your `base_url` otherwise;
 - the signed `client_id` claim matches the client presenting the assertion — an assertion the IdP minted for one client cannot be redeemed by another;
 - the signed `resource` claim names this server — an assertion minted for a different MCP server behind the same IdP is rejected;
 - `exp` (and `iat`/`nbf`, when present) place the assertion within a short lifetime and its validity window; and

fastmcp_slim/fastmcp/server/auth/auth.py

@@ -4,6 +4,7 @@
 from typing import TYPE_CHECKING, Any
 from urllib.parse import urlparse
 
+from mcp.server.auth.handlers.metadata import MetadataHandler
 from mcp.server.auth.handlers.token import TokenErrorResponse
 from mcp.server.auth.handlers.token import TokenHandler as _SDKTokenHandler
 from mcp.server.auth.json_response import PydanticJSONResponse
@@ -30,6 +31,7 @@
     TokenVerifier as TokenVerifierProtocol,
 )
 from mcp.server.auth.routes import (
+    build_metadata,
     cors_middleware,
     create_auth_routes,
     create_protected_resource_routes,
@@ -837,7 +839,8 @@ def __init__(
         ):
             logger.info(
                 f"OAuth endpoints at {self.base_url}, issuer at {self.issuer_url}. "
-                f"Ensure well-known routes are accessible at root ({self.issuer_url}/.well-known/). "
+                f"Ensure well-known routes are accessible at root "
+                f"({str(self.issuer_url).rstrip('/')}/.well-known/). "
                 f"See: https://gofastmcp.com/deployment/http#mounting-authenticated-servers"
             )
 
@@ -892,10 +895,10 @@ def get_routes(
         # Configure resource URL before creating routes
         self.set_mcp_path(mcp_path)
 
-        # Create standard OAuth authorization server routes
-        # Pass base_url as issuer_url to ensure metadata declares endpoints where
-        # they're actually accessible (operational routes are mounted at
-        # base_url)
+        # Create standard OAuth authorization server routes. Pass base_url so
+        # the SDK mounts operational routes and declares endpoint URLs where
+        # they're actually accessible; the metadata route is replaced below so
+        # that the advertised `issuer` reports issuer_url instead.
         assert self.base_url is not None  # typing check
         assert (
             self.issuer_url is not None
@@ -914,6 +917,35 @@ def get_routes(
         oauth_routes: list[Route] = []
         for route in sdk_routes:
             if (
+                isinstance(route, Route)
+                and route.path == "/.well-known/oauth-authorization-server"
+            ):
+                # The SDK bakes the metadata into the handler when it builds the
+                # route, and derives both `issuer` and every endpoint URL from a
+                # single argument. Rebuild it here so the endpoints stay on
+                # base_url (where the routes are mounted) while `issuer`
+                # reports issuer_url — the identifier clients used for RFC 8414
+                # discovery, which §3.3 requires the metadata to match.
+                metadata = build_metadata(
+                    self.base_url,
+                    self.service_documentation_url,
+                    self.client_registration_options or ClientRegistrationOptions(),
+                    self.revocation_options or RevocationOptions(),
+                )
+                metadata.issuer = self.issuer_url
+                metadata_handler = MetadataHandler(metadata)
+                oauth_routes.append(
+                    Route(
+                        path=route.path,
+                        endpoint=cors_middleware(
+                            metadata_handler.handle, ["GET", "OPTIONS"]
+                        ),
+                        methods=route.methods or ["GET", "OPTIONS"],
+                        name=route.name,
+                        include_in_schema=route.include_in_schema,
+                    )
+                )
+            elif (
                 isinstance(route, Route)
                 and route.path == "/token"
                 and route.methods is not None

fastmcp_slim/fastmcp/server/auth/handlers/authorize.py

@@ -177,8 +177,10 @@ class AuthorizationHandler(SDKAuthorizationHandler):
 
     def __init__(
         self,
+        *,
         provider: OAuthAuthorizationServerProvider,
         base_url: AnyHttpUrl | str,
+        issuer_url: AnyHttpUrl | str | None = None,
         server_name: str | None = None,
         server_icon_url: str | None = None,
     ):
@@ -187,14 +189,17 @@ def __init__(
         Args:
             provider: OAuth authorization server provider
             base_url: Base URL of the server for constructing endpoint URLs
+            issuer_url: Authorization server issuer identifier. Defaults to
+                `base_url`, which is correct whenever the server's identity and
+                its endpoint locations are the same URL.
             server_name: Optional server name for branding
             server_icon_url: Optional server icon URL for branding
         """
         super().__init__(provider)
         # Unnormalized on purpose: this must match the discovery document's
         # `issuer` field byte-for-byte per RFC 9207, and that field is built
-        # from the same unmodified base_url (see OAuthProxy.get_routes()).
-        self._issuer = str(base_url)
+        # from the same unmodified issuer_url (see OAuthProxy.get_routes()).
+        self._issuer = str(issuer_url if issuer_url is not None else base_url)
         self._base_url = str(base_url).rstrip("/")
         self._server_name = server_name
         self._server_icon_url = server_icon_url

fastmcp_slim/fastmcp/server/auth/identity_assertion.py

@@ -99,10 +99,12 @@ class IdentityAssertion(BaseModel):
     audience: str | None = Field(
         default=None,
         description=(
-            "Expected `aud` value on the ID-JAG. When omitted, the audience is the "
-            "authorization server's own issuer URL (its base URL), which is where the "
-            "ID-JAG's `aud` must point per SEP-990. Override only when the IdP mints "
-            "assertions bound to a different audience identifier."
+            "Expected `aud` value on the ID-JAG. When omitted, the audience is this "
+            "server's issuer identifier — the `issuer` published in its authorization "
+            "server metadata, which is `issuer_url` when set and `base_url` otherwise "
+            "— and that is where the ID-JAG's `aud` must point per SEP-990. Override "
+            "only when the IdP mints assertions bound to a different audience "
+            "identifier."
         ),
     )
     required_scopes: list[str] | None = Field(

fastmcp_slim/fastmcp/server/auth/oauth_proxy/consent.py

@@ -357,7 +357,7 @@ async def _show_consent_page(
                         url=build_client_redirect(
                             txn["client_redirect_uri"],
                             callback_params,
-                            iss=str(self.base_url),
+                            iss=str(self.issuer_url),
                         ),
                         status_code=302,
                     )
@@ -532,7 +532,7 @@ async def _submit_consent(
                 "state": txn.get("client_state") or "",
             }
             client_callback_url = build_client_redirect(
-                txn["client_redirect_uri"], callback_params, iss=str(self.base_url)
+                txn["client_redirect_uri"], callback_params, iss=str(self.issuer_url)
             )
             response = RedirectResponse(url=client_callback_url, status_code=302)
 

fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py

@@ -688,14 +688,17 @@ def __init__(
                 allowed_redirect_uri_patterns=self._allowed_client_redirect_uris,
             )
 
-        # Identity assertion (SEP-990 ID-JAG): the audience the ID-JAG must be
-        # bound to is this authorization server's own issuer URL (base_url).
+        # Identity assertion (SEP-990 ID-JAG): per RFC 7523 §3 the `aud` must
+        # identify this authorization server, and an authorization server is
+        # identified by its issuer — the same value published as `issuer` in
+        # the authorization server metadata, which is `issuer_url` (defaulting
+        # to `base_url`).
         self._identity_assertion: IdentityAssertion | None = identity_assertion
         self._identity_assertion_validator: IdentityAssertionValidator | None = None
         if identity_assertion is not None:
             self._identity_assertion_validator = IdentityAssertionValidator(
                 config=identity_assertion,
-                audience=str(self.base_url),
+                audience=str(self.issuer_url),
             )
         # ID-JAG access tokens are self-contained (no upstream token or JTI
         # mapping to delete), so revocation tracks their jtis here until the
@@ -758,9 +761,11 @@ def set_mcp_path(self, mcp_path: str | None) -> None:
         super().set_mcp_path(mcp_path)
 
         # Create JWT issuer with correct audience based on actual MCP path
-        # This ensures tokens are bound to the specific resource URL
+        # This ensures tokens are bound to the specific resource URL. The `iss`
+        # claim is the authorization server's issuer identifier (`issuer_url`),
+        # which matches the `issuer` advertised in the metadata document.
         self._jwt_issuer = JWTIssuer(
-            issuer=str(self.base_url),
+            issuer=str(self.issuer_url),
             audience=str(self._resource_url),
             signing_key=self._jwt_signing_key,
         )
@@ -2380,6 +2385,7 @@ def get_routes(
                 authorize_handler = AuthorizationHandler(
                     provider=self,
                     base_url=self.base_url,  # ty: ignore[invalid-argument-type]
+                    issuer_url=self.issuer_url,
                     server_name=None,  # Could be extended to pass server metadata
                     server_icon_url=None,
                 )
@@ -2468,6 +2474,14 @@ def get_routes(
                     revocation_options,
                     supports_identity_assertion=self._identity_assertion is not None,
                 )
+                # `build_metadata` derives both the `issuer` field and every
+                # endpoint URL from a single argument. Endpoints must stay on
+                # `base_url` (that is where the routes are actually mounted),
+                # while the issuer identity is `issuer_url`. RFC 8414 §3.3
+                # requires `issuer` to match the URL the client used for
+                # discovery, which is the `issuer_url` advertised in the
+                # protected resource metadata.
+                metadata.issuer = self.issuer_url  # ty: ignore[invalid-assignment]
                 # RFC 9207: every authorization response we issue carries an
                 # `iss` matching this issuer byte-for-byte, so this route must
                 # always be overridden to advertise support — not just when
@@ -2585,7 +2599,7 @@ async def _handle_idp_callback(
                         url=build_client_redirect(
                             client_redirect_uri,
                             error_params,
-                            iss=str(self.base_url),
+                            iss=str(self.issuer_url),
                         ),
                         status_code=302,
                     )
@@ -2753,7 +2767,7 @@ async def _handle_idp_callback(
             }
 
             client_callback_url = build_client_redirect(
-                client_redirect_uri, callback_params, iss=str(self.base_url)
+                client_redirect_uri, callback_params, iss=str(self.issuer_url)
             )
 
             logger.debug(f"Forwarding to client callback for transaction {txn_id}")

fastmcp_slim/fastmcp/server/auth/providers/in_memory.py

@@ -36,8 +36,10 @@ class InMemoryOAuthProvider(OAuthProvider):
 
     def __init__(
         self,
+        *,
         base_url: AnyHttpUrl | str | None = None,
         resource_base_url: AnyHttpUrl | str | None = None,
+        issuer_url: AnyHttpUrl | str | None = None,
         service_documentation_url: AnyHttpUrl | str | None = None,
         client_registration_options: ClientRegistrationOptions | None = None,
         revocation_options: RevocationOptions | None = None,
@@ -46,6 +48,7 @@ def __init__(
         super().__init__(
             base_url=base_url or "http://fastmcp.example.com",
             resource_base_url=resource_base_url,
+            issuer_url=issuer_url,
             service_documentation_url=service_documentation_url,
             client_registration_options=client_registration_options,
             revocation_options=revocation_options,