fastmcp 2.12.1__py3-none-any.whl → 2.13.2__py3-none-any.whl

fastmcp/server/auth/auth.py

@@ -1,13 +1,9 @@
 from __future__ import annotations
 
-from typing import Any
-from urllib.parse import urljoin
+from typing import Any, cast
 
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
-from mcp.server.auth.middleware.bearer_auth import (
-    BearerAuthBackend,
-    RequireAuthMiddleware,
-)
+from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend
 from mcp.server.auth.provider import (
     AccessToken as _SDKAccessToken,
 )
@@ -27,16 +23,20 @@ from mcp.server.auth.settings import (
     ClientRegistrationOptions,
     RevocationOptions,
 )
-from pydantic import AnyHttpUrl
+from pydantic import AnyHttpUrl, Field
 from starlette.middleware import Middleware
 from starlette.middleware.authentication import AuthenticationMiddleware
 from starlette.routing import Route
 
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
 
 class AccessToken(_SDKAccessToken):
     """AccessToken that includes all JWT claims."""
 
-    claims: dict[str, Any] = {}
+    claims: dict[str, Any] = Field(default_factory=dict)
 
 
 class AuthProvider(TokenVerifierProtocol):
@@ -82,10 +82,10 @@ class AuthProvider(TokenVerifierProtocol):
     def get_routes(
         self,
         mcp_path: str | None = None,
-        mcp_endpoint: Any | None = None,
     ) -> list[Route]:
-        """Get the routes for this authentication provider.
+        """Get all routes for this authentication provider.
 
+        This includes both well-known discovery routes and operational routes.
         Each provider is responsible for creating whatever routes it needs:
         - TokenVerifier: typically no routes (default implementation)
         - RemoteAuthProvider: protected resource metadata routes
@@ -94,30 +94,45 @@ class AuthProvider(TokenVerifierProtocol):
 
         Args:
             mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
-            mcp_endpoint: The MCP endpoint handler to protect with auth
+                This is used to advertise the resource URL in metadata, but the
+                provider does not create the actual MCP endpoint route.
 
         Returns:
-            List of routes for this provider, including protected MCP endpoints if provided
+            List of all routes for this provider (excluding the MCP endpoint itself)
         """
+        return []
 
-        routes = []
+    def get_well_known_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get well-known discovery routes for this authentication provider.
 
-        # Add protected MCP endpoint if provided
-        if mcp_path and mcp_endpoint:
-            resource_metadata_url = self._get_resource_url(
-                "/.well-known/oauth-protected-resource"
-            )
+        This is a utility method that filters get_routes() to return only
+        well-known discovery routes (those starting with /.well-known/).
 
-            routes.append(
-                Route(
-                    mcp_path,
-                    endpoint=RequireAuthMiddleware(
-                        mcp_endpoint, self.required_scopes, resource_metadata_url
-                    ),
-                )
-            )
+        Well-known routes provide OAuth metadata and discovery endpoints that
+        clients use to discover authentication capabilities. These routes should
+        be mounted at the root level of the application to comply with RFC 8414
+        and RFC 9728.
 
-        return routes
+        Common well-known routes:
+        - /.well-known/oauth-authorization-server (authorization server metadata)
+        - /.well-known/oauth-protected-resource/* (protected resource metadata)
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to construct path-scoped well-known URLs.
+
+        Returns:
+            List of well-known discovery routes (typically mounted at root level)
+        """
+        all_routes = self.get_routes(mcp_path)
+        return [
+            route
+            for route in all_routes
+            if isinstance(route, Route) and route.path.startswith("/.well-known/")
+        ]
 
     def get_middleware(self) -> list:
         """Get HTTP application-level middleware for this auth provider.
@@ -146,8 +161,9 @@ class AuthProvider(TokenVerifierProtocol):
             return None
 
         if path:
-            return AnyHttpUrl(urljoin(str(self.base_url), path))
-
+            prefix = str(self.base_url).rstrip("/")
+            suffix = path.lstrip("/")
+            return AnyHttpUrl(f"{prefix}/{suffix}")
         return self.base_url
 
 
@@ -225,14 +241,12 @@ class RemoteAuthProvider(AuthProvider):
     def get_routes(
         self,
         mcp_path: str | None = None,
-        mcp_endpoint: Any | None = None,
     ) -> list[Route]:
-        """Get OAuth routes for this provider.
+        """Get routes for this provider.
 
-        Creates protected resource metadata routes and optionally wraps MCP endpoints with auth.
+        Creates protected resource metadata routes (RFC 9728).
         """
-        # Start with base routes (protected MCP endpoint)
-        routes = super().get_routes(mcp_path, mcp_endpoint)
+        routes = []
 
         # Get the resource URL based on the MCP path
         resource_url = self._get_resource_url(mcp_path)
@@ -284,20 +298,27 @@ class OAuthProvider(
             required_scopes: Scopes that are required for all requests.
         """
 
-        # Convert URLs to proper types
-        if isinstance(base_url, str):
-            base_url = AnyHttpUrl(base_url)
-
         super().__init__(base_url=base_url, required_scopes=required_scopes)
-        self.base_url = base_url
 
         if issuer_url is None:
-            self.issuer_url = base_url
+            self.issuer_url = self.base_url
         elif isinstance(issuer_url, str):
             self.issuer_url = AnyHttpUrl(issuer_url)
         else:
             self.issuer_url = issuer_url
 
+        # Log if issuer_url and base_url differ (requires additional setup)
+        if (
+            self.base_url is not None
+            and self.issuer_url is not None
+            and str(self.base_url) != str(self.issuer_url)
+        ):
+            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"See: https://gofastmcp.com/deployment/http#mounting-authenticated-servers"
+            )
+
         # Initialize OAuth Authorization Server Provider
         OAuthAuthorizationServerProvider.__init__(self)
 
@@ -326,23 +347,29 @@ class OAuthProvider(
     def get_routes(
         self,
         mcp_path: str | None = None,
-        mcp_endpoint: Any | None = None,
     ) -> list[Route]:
         """Get OAuth authorization server routes and optional protected resource routes.
 
         This method creates the full set of OAuth routes including:
         - Standard OAuth authorization server routes (/.well-known/oauth-authorization-server, /authorize, /token, etc.)
         - Optional protected resource routes
-        - Protected MCP endpoints if provided
 
         Returns:
             List of OAuth routes
         """
 
         # 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)
+        assert self.base_url is not None  # typing check
+        assert (
+            self.issuer_url is not None
+        )  # typing check (issuer_url defaults to base_url)
+
         oauth_routes = create_auth_routes(
             provider=self,
-            issuer_url=self.issuer_url,
+            issuer_url=self.base_url,
             service_documentation_url=self.service_documentation_url,
             client_registration_options=self.client_registration_options,
             revocation_options=self.revocation_options,
@@ -353,14 +380,20 @@ class OAuthProvider(
 
         # Add protected resource routes if this server is also acting as a resource server
         if resource_url:
+            supported_scopes = (
+                self.client_registration_options.valid_scopes
+                if self.client_registration_options
+                and self.client_registration_options.valid_scopes
+                else self.required_scopes
+            )
             protected_routes = create_protected_resource_routes(
                 resource_url=resource_url,
-                authorization_servers=[self.issuer_url],
-                scopes_supported=self.required_scopes,
+                authorization_servers=[cast(AnyHttpUrl, self.issuer_url)],
+                scopes_supported=supported_scopes,
             )
             oauth_routes.extend(protected_routes)
 
-        # Add protected MCP endpoint from base class
-        oauth_routes.extend(super().get_routes(mcp_path, mcp_endpoint))
+        # Add base routes
+        oauth_routes.extend(super().get_routes(mcp_path))
 
         return oauth_routes

fastmcp/server/auth/handlers/authorize.py

@@ -0,0 +1,326 @@
+"""Enhanced authorization handler with improved error responses.
+
+This module provides an enhanced authorization handler that wraps the MCP SDK's
+AuthorizationHandler to provide better error messages when clients attempt to
+authorize with unregistered client IDs.
+
+The enhancement adds:
+- Content negotiation: HTML for browsers, JSON for API clients
+- Enhanced JSON responses with registration endpoint hints
+- Styled HTML error pages with registration links/forms
+- Link headers pointing to registration endpoints
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from mcp.server.auth.handlers.authorize import (
+    AuthorizationHandler as SDKAuthorizationHandler,
+)
+from pydantic import AnyHttpUrl
+from starlette.requests import Request
+from starlette.responses import Response
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.ui import (
+    INFO_BOX_STYLES,
+    TOOLTIP_STYLES,
+    create_logo,
+    create_page,
+    create_secure_html_response,
+)
+
+if TYPE_CHECKING:
+    from mcp.server.auth.provider import OAuthAuthorizationServerProvider
+
+logger = get_logger(__name__)
+
+
+def create_unregistered_client_html(
+    client_id: str,
+    registration_endpoint: str,
+    discovery_endpoint: str,
+    server_name: str | None = None,
+    server_icon_url: str | None = None,
+    title: str = "Client Not Registered",
+) -> str:
+    """Create styled HTML error page for unregistered client attempts.
+
+    Args:
+        client_id: The unregistered client ID that was provided
+        registration_endpoint: URL of the registration endpoint
+        discovery_endpoint: URL of the OAuth metadata discovery endpoint
+        server_name: Optional server name for branding
+        server_icon_url: Optional server icon URL
+        title: Page title
+
+    Returns:
+        HTML string for the error page
+    """
+    import html as html_module
+
+    client_id_escaped = html_module.escape(client_id)
+
+    # Main error message
+    error_box = f"""
+        <div class="info-box error">
+            <p>The client ID <code>{client_id_escaped}</code> was not found in the server's client registry.</p>
+        </div>
+    """
+
+    # What to do - yellow warning box
+    warning_box = """
+        <div class="info-box warning">
+            <p>Your MCP client opened this page to complete OAuth authorization,
+            but the server did not recognize its client ID. To fix this:</p>
+            <ul>
+                <li>Close this browser window</li>
+                <li>Clear authentication tokens in your MCP client (or restart it)</li>
+                <li>Try connecting again - your client should automatically re-register</li>
+            </ul>
+        </div>
+    """
+
+    # Help link with tooltip (similar to consent screen)
+    help_link = """
+        <div class="help-link-container">
+            <span class="help-link">
+                Why am I seeing this?
+                <span class="tooltip">
+                    OAuth 2.0 requires clients to register before authorization.
+                    This server returned a 400 error because the provided client
+                    ID was not found.
+                    <br><br>
+                    In browser-delegated OAuth flows, your application cannot
+                    detect this error automatically; it's waiting for a
+                    callback that will never arrive. You must manually clear
+                    auth tokens and reconnect.
+                </span>
+            </span>
+        </div>
+    """
+
+    # Build page content
+    content = f"""
+        <div class="container">
+            {create_logo(icon_url=server_icon_url, alt_text=server_name or "FastMCP")}
+            <h1>{title}</h1>
+            {error_box}
+            {warning_box}
+        </div>
+        {help_link}
+    """
+
+    # Use same styles as consent page
+    additional_styles = (
+        INFO_BOX_STYLES
+        + TOOLTIP_STYLES
+        + """
+        /* Error variant for info-box */
+        .info-box.error {
+            background: #fef2f2;
+            border-color: #f87171;
+        }
+        .info-box.error strong {
+            color: #991b1b;
+        }
+        /* Warning variant for info-box (yellow) */
+        .info-box.warning {
+            background: #fffbeb;
+            border-color: #fbbf24;
+        }
+        .info-box.warning strong {
+            color: #92400e;
+        }
+        .info-box code {
+            background: rgba(0, 0, 0, 0.05);
+            padding: 2px 6px;
+            border-radius: 3px;
+            font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace;
+            font-size: 0.9em;
+        }
+        .info-box ul {
+            margin: 10px 0;
+            padding-left: 20px;
+        }
+        .info-box li {
+            margin: 6px 0;
+        }
+        """
+    )
+
+    return create_page(
+        content=content,
+        title=title,
+        additional_styles=additional_styles,
+    )
+
+
+class AuthorizationHandler(SDKAuthorizationHandler):
+    """Authorization handler with enhanced error responses for unregistered clients.
+
+    This handler extends the MCP SDK's AuthorizationHandler to provide better UX
+    when clients attempt to authorize without being registered. It implements
+    content negotiation to return:
+
+    - HTML error pages for browser requests
+    - Enhanced JSON with registration hints for API clients
+    - Link headers pointing to registration endpoints
+
+    This maintains OAuth 2.1 compliance (returns 400 for invalid client_id)
+    while providing actionable guidance to fix the error.
+    """
+
+    def __init__(
+        self,
+        provider: OAuthAuthorizationServerProvider,
+        base_url: AnyHttpUrl | str,
+        server_name: str | None = None,
+        server_icon_url: str | None = None,
+    ):
+        """Initialize the enhanced authorization handler.
+
+        Args:
+            provider: OAuth authorization server provider
+            base_url: Base URL of the server for constructing endpoint URLs
+            server_name: Optional server name for branding
+            server_icon_url: Optional server icon URL for branding
+        """
+        super().__init__(provider)
+        self._base_url = str(base_url).rstrip("/")
+        self._server_name = server_name
+        self._server_icon_url = server_icon_url
+
+    async def handle(self, request: Request) -> Response:
+        """Handle authorization request with enhanced error responses.
+
+        This method extends the SDK's authorization handler and intercepts
+        errors for unregistered clients to provide better error responses
+        based on the client's Accept header.
+
+        Args:
+            request: The authorization request
+
+        Returns:
+            Response (redirect on success, error response on failure)
+        """
+        # Call the SDK handler
+        response = await super().handle(request)
+
+        # Check if this is a client not found error
+        if response.status_code == 400:
+            # Try to extract client_id from request for enhanced error
+            client_id: str | None = None
+            if request.method == "GET":
+                client_id = request.query_params.get("client_id")
+            else:
+                form = await request.form()
+                client_id_value = form.get("client_id")
+                # Ensure client_id is a string, not UploadFile
+                if isinstance(client_id_value, str):
+                    client_id = client_id_value
+
+            # If we have a client_id and the error is about it not being found,
+            # enhance the response
+            if client_id:
+                try:
+                    # Check if response body contains "not found" error
+                    if hasattr(response, "body"):
+                        body = json.loads(bytes(response.body))
+                        if (
+                            body.get("error") == "invalid_request"
+                            and "not found" in body.get("error_description", "").lower()
+                        ):
+                            return await self._create_enhanced_error_response(
+                                request, client_id, body.get("state")
+                            )
+                except Exception:
+                    # If we can't parse the response, just return the original
+                    pass
+
+        return response
+
+    async def _create_enhanced_error_response(
+        self, request: Request, client_id: str, state: str | None
+    ) -> Response:
+        """Create enhanced error response with content negotiation.
+
+        Args:
+            request: The original request
+            client_id: The unregistered client ID
+            state: The state parameter from the request
+
+        Returns:
+            HTML or JSON error response based on Accept header
+        """
+        registration_endpoint = f"{self._base_url}/register"
+        discovery_endpoint = f"{self._base_url}/.well-known/oauth-authorization-server"
+
+        # Extract server metadata from app state (same pattern as consent screen)
+        from fastmcp.server.server import FastMCP
+
+        fastmcp = getattr(request.app.state, "fastmcp_server", None)
+
+        if isinstance(fastmcp, FastMCP):
+            server_name = fastmcp.name
+            icons = fastmcp.icons
+            server_icon_url = icons[0].src if icons else None
+        else:
+            server_name = self._server_name
+            server_icon_url = self._server_icon_url
+
+        # Check Accept header for content negotiation
+        accept = request.headers.get("accept", "")
+
+        # Prefer HTML for browsers
+        if "text/html" in accept:
+            html = create_unregistered_client_html(
+                client_id=client_id,
+                registration_endpoint=registration_endpoint,
+                discovery_endpoint=discovery_endpoint,
+                server_name=server_name,
+                server_icon_url=server_icon_url,
+            )
+            response = create_secure_html_response(html, status_code=400)
+        else:
+            # Return enhanced JSON for API clients
+            from mcp.server.auth.handlers.authorize import AuthorizationErrorResponse
+
+            error_data = AuthorizationErrorResponse(
+                error="invalid_request",
+                error_description=(
+                    f"Client ID '{client_id}' is not registered with this server. "
+                    f"MCP clients should automatically re-register by sending a POST request to "
+                    f"the registration_endpoint and retry authorization. "
+                    f"If this persists, clear cached authentication tokens and reconnect."
+                ),
+                state=state,
+            )
+
+            # Add extra fields to help clients discover registration
+            error_dict = error_data.model_dump(exclude_none=True)
+            error_dict["registration_endpoint"] = registration_endpoint
+            error_dict["authorization_server_metadata"] = discovery_endpoint
+
+            from starlette.responses import JSONResponse
+
+            response = JSONResponse(
+                status_code=400,
+                content=error_dict,
+                headers={"Cache-Control": "no-store"},
+            )
+
+        # Add Link header for registration endpoint discovery
+        response.headers["Link"] = (
+            f'<{registration_endpoint}>; rel="http://oauth.net/core/2.1/#registration"'
+        )
+
+        logger.info(
+            "Unregistered client_id=%s, returned %s error response",
+            client_id,
+            "HTML" if "text/html" in accept else "JSON",
+        )
+
+        return response