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

fastmcp/server/auth/providers/supabase.py

@@ -0,0 +1,188 @@
+"""Supabase authentication provider for FastMCP.
+
+This module provides SupabaseProvider - a complete authentication solution that integrates
+with Supabase Auth's JWT verification, supporting Dynamic Client Registration (DCR)
+for seamless MCP client authentication.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import httpx
+from pydantic import AnyHttpUrl, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.settings import ENV_FILE
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import NotSet, NotSetT
+
+logger = get_logger(__name__)
+
+
+class SupabaseProviderSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_SUPABASE_",
+        env_file=ENV_FILE,
+        extra="ignore",
+    )
+
+    project_url: AnyHttpUrl
+    base_url: AnyHttpUrl
+    algorithm: Literal["HS256", "RS256", "ES256"] = "ES256"
+    required_scopes: list[str] | None = None
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
+
+
+class SupabaseProvider(RemoteAuthProvider):
+    """Supabase metadata provider for DCR (Dynamic Client Registration).
+
+    This provider implements Supabase Auth integration using metadata forwarding.
+    This approach allows Supabase to handle the OAuth flow directly while FastMCP acts
+    as a resource server, verifying JWTs issued by Supabase Auth.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    1. Supabase Project Setup:
+       - Create a Supabase project at https://supabase.com
+       - Note your project URL (e.g., "https://abc123.supabase.co")
+       - Configure your JWT algorithm in Supabase Auth settings (HS256, RS256, or ES256)
+       - Asymmetric keys (RS256/ES256) are recommended for production
+
+    2. JWT Verification:
+       - FastMCP verifies JWTs using the JWKS endpoint at {project_url}/auth/v1/.well-known/jwks.json
+       - JWTs are issued by {project_url}/auth/v1
+       - Tokens are cached for up to 10 minutes by Supabase's edge servers
+       - Algorithm must match your Supabase Auth configuration
+
+    3. Authorization:
+       - Supabase uses Row Level Security (RLS) policies for database authorization
+       - OAuth-level scopes are an upcoming feature in Supabase Auth
+       - Both approaches will be supported once scope handling is available
+
+    For detailed setup instructions, see:
+    https://supabase.com/docs/guides/auth/jwts
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.supabase import SupabaseProvider
+
+        # Create Supabase metadata provider (JWT verifier created automatically)
+        supabase_auth = SupabaseProvider(
+            project_url="https://abc123.supabase.co",
+            base_url="https://your-fastmcp-server.com",
+            algorithm="ES256",  # Match your Supabase Auth configuration
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=supabase_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        project_url: AnyHttpUrl | str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        algorithm: Literal["HS256", "RS256", "ES256"] | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT | None = NotSet,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize Supabase metadata provider.
+
+        Args:
+            project_url: Your Supabase project URL (e.g., "https://abc123.supabase.co")
+            base_url: Public URL of this FastMCP server
+            algorithm: JWT signing algorithm (HS256, RS256, or ES256). Must match your
+                Supabase Auth configuration. Defaults to ES256.
+            required_scopes: Optional list of scopes to require for all requests.
+                Note: Supabase currently uses RLS policies for authorization. OAuth-level
+                scopes are an upcoming feature.
+            token_verifier: Optional token verifier. If None, creates JWT verifier for Supabase
+        """
+        settings = SupabaseProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "project_url": project_url,
+                    "base_url": base_url,
+                    "algorithm": algorithm,
+                    "required_scopes": required_scopes,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        self.project_url = str(settings.project_url).rstrip("/")
+        self.base_url = AnyHttpUrl(str(settings.base_url).rstrip("/"))
+
+        # Create default JWT verifier if none provided
+        if token_verifier is None:
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.project_url}/auth/v1/.well-known/jwks.json",
+                issuer=f"{self.project_url}/auth/v1",
+                algorithm=settings.algorithm,
+                required_scopes=settings.required_scopes,
+            )
+
+        # Initialize RemoteAuthProvider with Supabase as the authorization server
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[AnyHttpUrl(f"{self.project_url}/auth/v1")],
+            base_url=self.base_url,
+        )
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get OAuth routes including Supabase authorization server metadata forwarding.
+
+        This returns the standard protected resource routes plus an authorization server
+        metadata endpoint that forwards Supabase's OAuth metadata to clients.
+
+        Args:
+            mcp_path: The path where the MCP endpoint is mounted (e.g., "/mcp")
+                This is used to advertise the resource URL in metadata.
+        """
+        # Get the standard protected resource routes from RemoteAuthProvider
+        routes = super().get_routes(mcp_path)
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward Supabase OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        f"{self.project_url}/auth/v1/.well-known/oauth-authorization-server"
+                    )
+                    response.raise_for_status()
+                    metadata = response.json()
+                    return JSONResponse(metadata)
+            except Exception as e:
+                return JSONResponse(
+                    {
+                        "error": "server_error",
+                        "error_description": f"Failed to fetch Supabase metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        # Add Supabase authorization server metadata forwarding
+        routes.append(
+            Route(
+                "/.well-known/oauth-authorization-server",
+                endpoint=oauth_authorization_server_metadata,
+                methods=["GET"],
+            )
+        )
+
+        return routes

fastmcp/server/auth/providers/workos.py

@@ -10,9 +10,8 @@ Choose based on your WorkOS setup and authentication requirements.
 
 from __future__ import annotations
 
-from typing import Any
-
 import httpx
+from key_value.aio.protocols import AsyncKeyValue
 from pydantic import AnyHttpUrl, SecretStr, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from starlette.responses import JSONResponse
@@ -21,6 +20,7 @@ from starlette.routing import Route
 from fastmcp.server.auth import AccessToken, RemoteAuthProvider, TokenVerifier
 from fastmcp.server.auth.oauth_proxy import OAuthProxy
 from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.settings import ENV_FILE
 from fastmcp.utilities.auth import parse_scopes
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import NotSet, NotSetT
@@ -33,7 +33,7 @@ class WorkOSProviderSettings(BaseSettings):
 
     model_config = SettingsConfigDict(
         env_prefix="FASTMCP_SERVER_AUTH_WORKOS_",
-        env_file=".env",
+        env_file=ENV_FILE,
         extra="ignore",
     )
 
@@ -41,10 +41,12 @@ class WorkOSProviderSettings(BaseSettings):
     client_secret: SecretStr | None = None
     authkit_domain: str | None = None  # e.g., "https://your-app.authkit.app"
     base_url: AnyHttpUrl | str | None = None
+    issuer_url: AnyHttpUrl | str | None = None
     redirect_path: str | None = None
     required_scopes: list[str] | None = None
     timeout_seconds: int | None = None
     allowed_client_redirect_uris: list[str] | None = None
+    jwt_signing_key: str | None = None
 
     @field_validator("required_scopes", mode="before")
     @classmethod
@@ -165,10 +167,14 @@ class WorkOSProvider(OAuthProxy):
         client_secret: str | NotSetT = NotSet,
         authkit_domain: str | NotSetT = NotSet,
         base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        issuer_url: AnyHttpUrl | str | NotSetT = NotSet,
         redirect_path: str | NotSetT = NotSet,
-        required_scopes: list[str] | None | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT | None = NotSet,
         timeout_seconds: int | NotSetT = NotSet,
         allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | NotSetT = NotSet,
+        require_authorization_consent: bool = True,
     ):
         """Initialize WorkOS OAuth provider.
 
@@ -176,12 +182,24 @@ class WorkOSProvider(OAuthProxy):
             client_id: WorkOS client ID
             client_secret: WorkOS client secret
             authkit_domain: Your WorkOS AuthKit domain (e.g., "https://your-app.authkit.app")
-            base_url: Public URL of your FastMCP server (for OAuth callbacks)
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
             redirect_path: Redirect path configured in WorkOS (defaults to "/auth/callback")
             required_scopes: Required OAuth scopes (no default)
             timeout_seconds: HTTP request timeout for WorkOS API calls
             allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
                 If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, a DiskStore will be created in the data directory (derived from `platformdirs`). The
+                disk store will be encrypted using a key derived from the JWT Signing Key.
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to WorkOS.
+                When False, authorization proceeds directly without user confirmation.
+                SECURITY WARNING: Only disable for local development or testing environments.
         """
 
         settings = WorkOSProviderSettings.model_validate(
@@ -192,10 +210,12 @@ class WorkOSProvider(OAuthProxy):
                     "client_secret": client_secret,
                     "authkit_domain": authkit_domain,
                     "base_url": base_url,
+                    "issuer_url": issuer_url,
                     "redirect_path": redirect_path,
                     "required_scopes": required_scopes,
                     "timeout_seconds": timeout_seconds,
                     "allowed_client_redirect_uris": allowed_client_redirect_uris,
+                    "jwt_signing_key": jwt_signing_key,
                 }.items()
                 if v is not NotSet
             }
@@ -220,7 +240,6 @@ class WorkOSProvider(OAuthProxy):
         if not authkit_domain_str.startswith(("http://", "https://")):
             authkit_domain_str = f"https://{authkit_domain_str}"
         authkit_domain_final = authkit_domain_str.rstrip("/")
-        redirect_path_final = settings.redirect_path or "/auth/callback"
         timeout_seconds_final = settings.timeout_seconds or 10
         scopes_final = settings.required_scopes or []
         allowed_client_redirect_uris_final = settings.allowed_client_redirect_uris
@@ -245,12 +264,16 @@ class WorkOSProvider(OAuthProxy):
             upstream_client_secret=client_secret_str,
             token_verifier=token_verifier,
             base_url=settings.base_url,
-            redirect_path=redirect_path_final,
-            issuer_url=settings.base_url,
+            redirect_path=settings.redirect_path,
+            issuer_url=settings.issuer_url
+            or settings.base_url,  # Default to base_url if not specified
             allowed_client_redirect_uris=allowed_client_redirect_uris_final,
+            client_storage=client_storage,
+            jwt_signing_key=settings.jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
         )
 
-        logger.info(
+        logger.debug(
             "Initialized WorkOS OAuth provider for client %s with AuthKit domain %s",
             settings.client_id,
             authkit_domain_final,
@@ -260,7 +283,7 @@ class WorkOSProvider(OAuthProxy):
 class AuthKitProviderSettings(BaseSettings):
     model_config = SettingsConfigDict(
         env_prefix="FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_",
-        env_file=".env",
+        env_file=ENV_FILE,
         extra="ignore",
     )
 
@@ -315,7 +338,7 @@ class AuthKitProvider(RemoteAuthProvider):
         *,
         authkit_domain: AnyHttpUrl | str | NotSetT = NotSet,
         base_url: AnyHttpUrl | str | NotSetT = NotSet,
-        required_scopes: list[str] | None | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT | None = NotSet,
         token_verifier: TokenVerifier | None = None,
     ):
         """Initialize AuthKit metadata provider.
@@ -339,7 +362,7 @@ class AuthKitProvider(RemoteAuthProvider):
         )
 
         self.authkit_domain = str(settings.authkit_domain).rstrip("/")
-        self.base_url = str(settings.base_url).rstrip("/")
+        self.base_url = AnyHttpUrl(str(settings.base_url).rstrip("/"))
 
         # Create default JWT verifier if none provided
         if token_verifier is None:
@@ -360,7 +383,6 @@ class AuthKitProvider(RemoteAuthProvider):
     def get_routes(
         self,
         mcp_path: str | None = None,
-        mcp_endpoint: Any | None = None,
     ) -> list[Route]:
         """Get OAuth routes including AuthKit authorization server metadata forwarding.
 
@@ -369,10 +391,10 @@ class AuthKitProvider(RemoteAuthProvider):
 
         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.
         """
         # Get the standard protected resource routes from RemoteAuthProvider
-        routes = super().get_routes(mcp_path, mcp_endpoint)
+        routes = super().get_routes(mcp_path)
 
         async def oauth_authorization_server_metadata(request):
             """Forward AuthKit OAuth authorization server metadata with FastMCP customizations."""