fastmcp 2.12.4__py3-none-any.whl → 2.13.0__py3-none-any.whl

fastmcp/server/auth/providers/google.py

@@ -24,15 +24,16 @@ from __future__ import annotations
 import time
 
 import httpx
+from key_value.aio.protocols import AsyncKeyValue
 from pydantic import AnyHttpUrl, SecretStr, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from fastmcp.server.auth import TokenVerifier
 from fastmcp.server.auth.auth import AccessToken
 from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.settings import ENV_FILE
 from fastmcp.utilities.auth import parse_scopes
 from fastmcp.utilities.logging import get_logger
-from fastmcp.utilities.storage import KVStorage
 from fastmcp.utilities.types import NotSet, NotSetT
 
 logger = get_logger(__name__)
@@ -43,17 +44,19 @@ class GoogleProviderSettings(BaseSettings):
 
     model_config = SettingsConfigDict(
         env_prefix="FASTMCP_SERVER_AUTH_GOOGLE_",
-        env_file=".env",
+        env_file=ENV_FILE,
         extra="ignore",
     )
 
     client_id: str | None = None
     client_secret: SecretStr | None = None
     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
@@ -77,7 +80,7 @@ class GoogleTokenVerifier(TokenVerifier):
         """Initialize the Google token verifier.
 
         Args:
-            required_scopes: Required OAuth scopes (e.g., ['openid', 'email'])
+            required_scopes: Required OAuth scopes (e.g., ['openid', 'https://www.googleapis.com/auth/userinfo.email'])
             timeout_seconds: HTTP request timeout
         """
         super().__init__(required_scopes=required_scopes)
@@ -214,18 +217,23 @@ class GoogleProvider(OAuthProxy):
         client_id: str | NotSetT = NotSet,
         client_secret: str | NotSetT = NotSet,
         base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        issuer_url: AnyHttpUrl | str | NotSetT = NotSet,
         redirect_path: str | NotSetT = NotSet,
         required_scopes: list[str] | NotSetT = NotSet,
         timeout_seconds: int | NotSetT = NotSet,
         allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
-        client_storage: KVStorage | None = None,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | NotSetT = NotSet,
+        require_authorization_consent: bool = True,
     ):
         """Initialize Google OAuth provider.
 
         Args:
             client_id: Google OAuth client ID (e.g., "123456789.apps.googleusercontent.com")
             client_secret: Google OAuth client secret (e.g., "GOCSPX-abc123...")
-            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 Google OAuth app (defaults to "/auth/callback")
             required_scopes: Required Google scopes (defaults to ["openid"]). Common scopes include:
                 - "openid" for OpenID Connect (default)
@@ -234,8 +242,16 @@ class GoogleProvider(OAuthProxy):
             timeout_seconds: HTTP request timeout for Google 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 implementation for OAuth client registrations.
-                Defaults to file-based storage if not specified.
+            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 Google.
+                When False, authorization proceeds directly without user confirmation.
+                SECURITY WARNING: Only disable for local development or testing environments.
         """
 
         settings = GoogleProviderSettings.model_validate(
@@ -245,10 +261,12 @@ class GoogleProvider(OAuthProxy):
                     "client_id": client_id,
                     "client_secret": client_secret,
                     "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
             }
@@ -290,12 +308,15 @@ class GoogleProvider(OAuthProxy):
             token_verifier=token_verifier,
             base_url=settings.base_url,
             redirect_path=settings.redirect_path,
-            issuer_url=settings.base_url,  # We act as the issuer for client registration
+            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 Google OAuth provider for client %s with scopes: %s",
             settings.client_id,
             required_scopes_final,

fastmcp/server/auth/providers/introspection.py

@@ -0,0 +1,281 @@
+"""OAuth 2.0 Token Introspection (RFC 7662) provider for FastMCP.
+
+This module provides token verification for opaque tokens using the OAuth 2.0
+Token Introspection protocol defined in RFC 7662. It allows FastMCP servers to
+validate tokens issued by authorization servers that don't use JWT format.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier
+
+    # Verify opaque tokens via RFC 7662 introspection
+    verifier = IntrospectionTokenVerifier(
+        introspection_url="https://auth.example.com/oauth/introspect",
+        client_id="your-client-id",
+        client_secret="your-client-secret",
+        required_scopes=["read", "write"]
+    )
+
+    mcp = FastMCP("My Protected Server", auth=verifier)
+    ```
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from typing import Any
+
+import httpx
+from pydantic import AnyHttpUrl, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from fastmcp.server.auth import AccessToken, TokenVerifier
+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 IntrospectionTokenVerifierSettings(BaseSettings):
+    """Settings for OAuth 2.0 Token Introspection verification."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_INTROSPECTION_",
+        env_file=ENV_FILE,
+        extra="ignore",
+    )
+
+    introspection_url: str | None = None
+    client_id: str | None = None
+    client_secret: SecretStr | None = None
+    timeout_seconds: int = 10
+    required_scopes: list[str] | None = None
+    base_url: AnyHttpUrl | str | None = None
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
+
+
+class IntrospectionTokenVerifier(TokenVerifier):
+    """
+    OAuth 2.0 Token Introspection verifier (RFC 7662).
+
+    This verifier validates opaque tokens by calling an OAuth 2.0 token introspection
+    endpoint. Unlike JWT verification which is stateless, token introspection requires
+    a network call to the authorization server for each token validation.
+
+    The verifier authenticates to the introspection endpoint using HTTP Basic Auth
+    with the provided client_id and client_secret, as specified in RFC 7662.
+
+    Use this when:
+    - Your authorization server issues opaque (non-JWT) tokens
+    - You need to validate tokens from Auth0, Okta, Keycloak, or other OAuth servers
+    - Your tokens require real-time revocation checking
+    - Your authorization server supports RFC 7662 introspection
+
+    Example:
+        ```python
+        verifier = IntrospectionTokenVerifier(
+            introspection_url="https://auth.example.com/oauth/introspect",
+            client_id="my-service",
+            client_secret="secret-key",
+            required_scopes=["api:read"]
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        introspection_url: str | NotSetT = NotSet,
+        client_id: str | NotSetT = NotSet,
+        client_secret: str | NotSetT = NotSet,
+        timeout_seconds: int | NotSetT = NotSet,
+        required_scopes: list[str] | None | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | None | NotSetT = NotSet,
+    ):
+        """
+        Initialize the introspection token verifier.
+
+        Args:
+            introspection_url: URL of the OAuth 2.0 token introspection endpoint
+            client_id: OAuth client ID for authenticating to the introspection endpoint
+            client_secret: OAuth client secret for authenticating to the introspection endpoint
+            timeout_seconds: HTTP request timeout in seconds (default: 10)
+            required_scopes: Required scopes for all tokens (optional)
+            base_url: Base URL for TokenVerifier protocol
+        """
+        settings = IntrospectionTokenVerifierSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "introspection_url": introspection_url,
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                    "timeout_seconds": timeout_seconds,
+                    "required_scopes": required_scopes,
+                    "base_url": base_url,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        if not settings.introspection_url:
+            raise ValueError(
+                "introspection_url is required - set via parameter or "
+                "FASTMCP_SERVER_AUTH_INTROSPECTION_INTROSPECTION_URL"
+            )
+        if not settings.client_id:
+            raise ValueError(
+                "client_id is required - set via parameter or "
+                "FASTMCP_SERVER_AUTH_INTROSPECTION_CLIENT_ID"
+            )
+        if not settings.client_secret:
+            raise ValueError(
+                "client_secret is required - set via parameter or "
+                "FASTMCP_SERVER_AUTH_INTROSPECTION_CLIENT_SECRET"
+            )
+
+        super().__init__(
+            base_url=settings.base_url, required_scopes=settings.required_scopes
+        )
+
+        self.introspection_url = settings.introspection_url
+        self.client_id = settings.client_id
+        self.client_secret = settings.client_secret.get_secret_value()
+        self.timeout_seconds = settings.timeout_seconds
+        self.logger = get_logger(__name__)
+
+    def _create_basic_auth_header(self) -> str:
+        """Create HTTP Basic Auth header value from client credentials."""
+        credentials = f"{self.client_id}:{self.client_secret}"
+        encoded = base64.b64encode(credentials.encode("utf-8")).decode("utf-8")
+        return f"Basic {encoded}"
+
+    def _extract_scopes(self, introspection_response: dict[str, Any]) -> list[str]:
+        """
+        Extract scopes from introspection response.
+
+        RFC 7662 allows scopes to be returned as either:
+        - A space-separated string in the 'scope' field
+        - An array of strings in the 'scope' field (less common but valid)
+        """
+        scope_value = introspection_response.get("scope")
+
+        if scope_value is None:
+            return []
+
+        # Handle string (space-separated) scopes
+        if isinstance(scope_value, str):
+            return [s.strip() for s in scope_value.split() if s.strip()]
+
+        # Handle array of scopes
+        if isinstance(scope_value, list):
+            return [str(s) for s in scope_value if s]
+
+        return []
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """
+        Verify a bearer token using OAuth 2.0 Token Introspection (RFC 7662).
+
+        This method makes a POST request to the introspection endpoint with the token,
+        authenticated using HTTP Basic Auth with the client credentials.
+
+        Args:
+            token: The opaque token string to validate
+
+        Returns:
+            AccessToken object if valid and active, None if invalid, inactive, or expired
+        """
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                # Prepare introspection request per RFC 7662
+                auth_header = self._create_basic_auth_header()
+
+                response = await client.post(
+                    self.introspection_url,
+                    data={
+                        "token": token,
+                        "token_type_hint": "access_token",
+                    },
+                    headers={
+                        "Authorization": auth_header,
+                        "Content-Type": "application/x-www-form-urlencoded",
+                        "Accept": "application/json",
+                    },
+                )
+
+                # Check for HTTP errors
+                if response.status_code != 200:
+                    self.logger.debug(
+                        "Token introspection failed: HTTP %d - %s",
+                        response.status_code,
+                        response.text[:200] if response.text else "",
+                    )
+                    return None
+
+                introspection_data = response.json()
+
+                # Check if token is active (required field per RFC 7662)
+                if not introspection_data.get("active", False):
+                    self.logger.debug("Token introspection returned active=false")
+                    return None
+
+                # Extract client_id (should be present for active tokens)
+                client_id = introspection_data.get(
+                    "client_id"
+                ) or introspection_data.get("sub", "unknown")
+
+                # Extract expiration time
+                exp = introspection_data.get("exp")
+                if exp:
+                    # Validate expiration (belt and suspenders - server should set active=false)
+                    if exp < time.time():
+                        self.logger.debug(
+                            "Token validation failed: expired token for client %s",
+                            client_id,
+                        )
+                        return None
+
+                # Extract scopes
+                scopes = self._extract_scopes(introspection_data)
+
+                # Check required scopes
+                if self.required_scopes:
+                    token_scopes = set(scopes)
+                    required_scopes = set(self.required_scopes)
+                    if not required_scopes.issubset(token_scopes):
+                        self.logger.debug(
+                            "Token missing required scopes. Has: %s, Required: %s",
+                            token_scopes,
+                            required_scopes,
+                        )
+                        return None
+
+                # Create AccessToken with introspection response data
+                return AccessToken(
+                    token=token,
+                    client_id=str(client_id),
+                    scopes=scopes,
+                    expires_at=int(exp) if exp else None,
+                    claims=introspection_data,  # Store full response for extensibility
+                )
+
+        except httpx.TimeoutException:
+            self.logger.debug(
+                "Token introspection timed out after %d seconds", self.timeout_seconds
+            )
+            return None
+        except httpx.RequestError as e:
+            self.logger.debug("Token introspection request failed: %s", e)
+            return None
+        except Exception as e:
+            self.logger.debug("Token introspection error: %s", e)
+            return None

fastmcp/server/auth/providers/jwt.py

@@ -16,6 +16,7 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 from typing_extensions import TypedDict
 
 from fastmcp.server.auth import AccessToken, TokenVerifier
+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
@@ -143,7 +144,7 @@ class JWTVerifierSettings(BaseSettings):
 
     model_config = SettingsConfigDict(
         env_prefix="FASTMCP_SERVER_AUTH_JWT_",
-        env_file=".env",
+        env_file=ENV_FILE,
         extra="ignore",
     )
 
@@ -381,7 +382,12 @@ class JWTVerifier(TokenVerifier):
             claims = self.jwt.decode(token, verification_key)
 
             # Extract client ID early for logging
-            client_id = claims.get("client_id") or claims.get("sub") or "unknown"
+            client_id = (
+                claims.get("client_id")
+                or claims.get("azp")
+                or claims.get("sub")
+                or "unknown"
+            )
 
             # Validate expiration
             exp = claims.get("exp")

fastmcp/server/auth/providers/scalekit.py

@@ -0,0 +1,179 @@
+"""Scalekit authentication provider for FastMCP.
+
+This module provides ScalekitProvider - a complete authentication solution that integrates
+with Scalekit's OAuth 2.1 and OpenID Connect services, supporting Resource Server
+authentication for seamless MCP client authentication.
+"""
+
+from __future__ import annotations
+
+import httpx
+from pydantic import AnyHttpUrl
+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.logging import get_logger
+from fastmcp.utilities.types import NotSet, NotSetT
+
+logger = get_logger(__name__)
+
+
+class ScalekitProviderSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_",
+        env_file=ENV_FILE,
+        extra="ignore",
+    )
+
+    environment_url: AnyHttpUrl
+    client_id: str
+    resource_id: str
+    mcp_url: AnyHttpUrl
+
+
+class ScalekitProvider(RemoteAuthProvider):
+    """Scalekit resource server provider for OAuth 2.1 authentication.
+
+    This provider implements Scalekit integration using resource server pattern.
+    FastMCP acts as a protected resource server that validates access tokens issued
+    by Scalekit's authorization server.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    1. Create an MCP Server in Scalekit Dashboard:
+       - Go to your [Scalekit Dashboard](https://app.scalekit.com/)
+       - Navigate to MCP Servers section
+       - Register a new MCP Server with appropriate scopes
+       - Ensure the Resource Identifier matches exactly what you configure as MCP URL
+       - Note the Resource ID
+
+    2. Environment Configuration:
+       - Set SCALEKIT_ENVIRONMENT_URL (e.g., https://your-env.scalekit.com)
+       - Set SCALEKIT_CLIENT_ID from your OAuth application
+       - Set SCALEKIT_RESOURCE_ID from your created resource
+       - Set MCP_URL to your FastMCP server's public URL
+
+    For detailed setup instructions, see:
+    https://docs.scalekit.com/mcp/overview/
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.scalekit import ScalekitProvider
+
+        # Create Scalekit resource server provider
+        scalekit_auth = ScalekitProvider(
+            environment_url="https://your-env.scalekit.com",
+            client_id="sk_client_...",
+            resource_id="sk_resource_...",
+            mcp_url="https://your-fastmcp-server.com",
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=scalekit_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        environment_url: AnyHttpUrl | str | NotSetT = NotSet,
+        client_id: str | NotSetT = NotSet,
+        resource_id: str | NotSetT = NotSet,
+        mcp_url: AnyHttpUrl | str | NotSetT = NotSet,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize Scalekit resource server provider.
+
+        Args:
+            environment_url: Your Scalekit environment URL (e.g., "https://your-env.scalekit.com")
+            client_id: Your Scalekit OAuth client ID
+            resource_id: Your Scalekit resource ID
+            mcp_url: Public URL of this FastMCP server (used as audience)
+            token_verifier: Optional token verifier. If None, creates JWT verifier for Scalekit
+        """
+        settings = ScalekitProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "environment_url": environment_url,
+                    "client_id": client_id,
+                    "resource_id": resource_id,
+                    "mcp_url": mcp_url,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        self.environment_url = str(settings.environment_url).rstrip("/")
+        self.client_id = settings.client_id
+        self.resource_id = settings.resource_id
+        self.mcp_url = str(settings.mcp_url)
+
+        # Create default JWT verifier if none provided
+        if token_verifier is None:
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.environment_url}/keys",
+                issuer=self.environment_url,
+                algorithm="RS256",
+                audience=self.mcp_url,
+            )
+
+        # Initialize RemoteAuthProvider with Scalekit as the authorization server
+        super().__init__(
+            token_verifier=token_verifier,
+            authorization_servers=[
+                AnyHttpUrl(f"{self.environment_url}/resources/{self.resource_id}")
+            ],
+            base_url=self.mcp_url,
+        )
+
+    def get_routes(
+        self,
+        mcp_path: str | None = None,
+    ) -> list[Route]:
+        """Get OAuth routes including Scalekit authorization server metadata forwarding.
+
+        This returns the standard protected resource routes plus an authorization server
+        metadata endpoint that forwards Scalekit'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 Scalekit OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        f"{self.environment_url}/.well-known/oauth-authorization-server/resources/{self.resource_id}"
+                    )
+                    response.raise_for_status()
+                    metadata = response.json()
+                    return JSONResponse(metadata)
+            except Exception as e:
+                logger.error(f"Failed to fetch Scalekit metadata: {e}")
+                return JSONResponse(
+                    {
+                        "error": "server_error",
+                        "error_description": f"Failed to fetch Scalekit metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        # Add Scalekit authorization server metadata forwarding
+        routes.append(
+            Route(
+                "/.well-known/oauth-authorization-server",
+                endpoint=oauth_authorization_server_metadata,
+                methods=["GET"],
+            )
+        )
+
+        return routes