fastmcp 2.12.5__py3-none-any.whl → 2.14.0__py3-none-any.whl

fastmcp/server/auth/providers/github.py

@@ -22,15 +22,16 @@ Example:
 from __future__ import annotations
 
 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__)
@@ -41,17 +42,19 @@ class GitHubProviderSettings(BaseSettings):
 
     model_config = SettingsConfigDict(
         env_prefix="FASTMCP_SERVER_AUTH_GITHUB_",
-        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
@@ -198,25 +201,38 @@ class GitHubProvider(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 GitHub OAuth provider.
 
         Args:
             client_id: GitHub OAuth app client ID (e.g., "Ov23li...")
             client_secret: GitHub OAuth app client secret
-            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 GitHub OAuth app (defaults to "/auth/callback")
             required_scopes: Required GitHub scopes (defaults to ["user"])
             timeout_seconds: HTTP request timeout for GitHub 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 GitHub.
+                When False, authorization proceeds directly without user confirmation.
+                SECURITY WARNING: Only disable for local development or testing environments.
         """
 
         settings = GitHubProviderSettings.model_validate(
@@ -226,10 +242,12 @@ class GitHubProvider(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
             }
@@ -271,12 +289,15 @@ class GitHubProvider(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 GitHub OAuth provider for client %s with scopes: %s",
             settings.client_id,
             required_scopes_final,

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,24 @@ 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,
+        extra_authorize_params: dict[str, str] | None = None,
     ):
         """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 +243,20 @@ 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.
+            extra_authorize_params: Additional parameters to forward to Google's authorization endpoint.
+                By default, GoogleProvider sets {"access_type": "offline", "prompt": "consent"} to ensure
+                refresh tokens are returned. You can override these defaults or add additional parameters.
+                Example: {"prompt": "select_account"} to let users choose their Google account.
         """
 
         settings = GoogleProviderSettings.model_validate(
@@ -245,10 +266,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
             }
@@ -281,6 +304,18 @@ class GoogleProvider(OAuthProxy):
             settings.client_secret.get_secret_value() if settings.client_secret else ""
         )
 
+        # Set Google-specific defaults for extra authorize params
+        # access_type=offline ensures refresh tokens are returned
+        # prompt=consent forces consent screen to get refresh token (Google only issues on first auth otherwise)
+        google_defaults = {
+            "access_type": "offline",
+            "prompt": "consent",
+        }
+        # User-provided params override defaults
+        if extra_authorize_params:
+            google_defaults.update(extra_authorize_params)
+        extra_authorize_params_final = google_defaults
+
         # Initialize OAuth proxy with Google endpoints
         super().__init__(
             upstream_authorization_endpoint="https://accounts.google.com/o/oauth2/v2/auth",
@@ -290,12 +325,16 @@ 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,
+            extra_authorize_params=extra_authorize_params_final,
         )
 
-        logger.info(
+        logger.debug(
             "Initialized Google OAuth provider for client %s with scopes: %s",
             settings.client_id,
             required_scopes_final,

fastmcp/server/auth/providers/in_memory.py

@@ -66,6 +66,22 @@ class InMemoryOAuthProvider(OAuthProvider):
         return self.clients.get(client_id)
 
     async def register_client(self, client_info: OAuthClientInformationFull) -> None:
+        # Validate scopes against valid_scopes if configured (matches MCP SDK behavior)
+        if (
+            client_info.scope is not None
+            and self.client_registration_options is not None
+            and self.client_registration_options.valid_scopes is not None
+        ):
+            requested_scopes = set(client_info.scope.split())
+            valid_scopes = set(self.client_registration_options.valid_scopes)
+            invalid_scopes = requested_scopes - valid_scopes
+            if invalid_scopes:
+                raise ValueError(
+                    f"Requested scopes are not valid: {', '.join(invalid_scopes)}"
+                )
+
+        if client_info.client_id is None:
+            raise ValueError("client_id is required for client registration")
         if client_info.client_id in self.clients:
             # As per RFC 7591, if client_id is already known, it's an update.
             # For this simple provider, we'll treat it as re-registration.
@@ -91,15 +107,15 @@ class InMemoryOAuthProvider(OAuthProvider):
             # OAuthClientInformationFull should have a method like validate_redirect_uri
             # For this test provider, we assume it's valid if it matches one in client_info
             # The AuthorizationHandler already does robust validation using client.validate_redirect_uri
-            if params.redirect_uri not in client.redirect_uris:
+            if client.redirect_uris and params.redirect_uri not in client.redirect_uris:
                 # This check might be too simplistic if redirect_uris can be patterns
                 # or if params.redirect_uri is None and client has a default.
                 # However, the AuthorizationHandler handles the primary validation.
                 pass  # Let's assume AuthorizationHandler did its job.
-        except Exception:  # Replace with specific validation error if client.validate_redirect_uri existed
+        except Exception as e:  # Replace with specific validation error if client.validate_redirect_uri existed
             raise AuthorizeError(
                 error="invalid_request", error_description="Invalid redirect_uri."
-            )
+            ) from e
 
         auth_code_value = f"test_auth_code_{secrets.token_hex(16)}"
         expires_at = time.time() + DEFAULT_AUTH_CODE_EXPIRY_SECONDS
@@ -110,6 +126,10 @@ class InMemoryOAuthProvider(OAuthProvider):
             client_allowed_scopes = set(client.scope.split())
             scopes_list = [s for s in scopes_list if s in client_allowed_scopes]
 
+        if client.client_id is None:
+            raise AuthorizeError(
+                error="invalid_client", error_description="Client ID is required"
+            )
         auth_code = AuthorizationCode(
             code=auth_code_value,
             client_id=client.client_id,
@@ -166,6 +186,8 @@ class InMemoryOAuthProvider(OAuthProvider):
                 time.time() + DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS
             )
 
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
         self.access_tokens[access_token_value] = AccessToken(
             token=access_token_value,
             client_id=client.client_id,
@@ -236,6 +258,8 @@ class InMemoryOAuthProvider(OAuthProvider):
                 time.time() + DEFAULT_REFRESH_TOKEN_EXPIRY_SECONDS
             )
 
+        if client.client_id is None:
+            raise TokenError("invalid_client", "Client ID is required")
         self.access_tokens[new_access_token_value] = AccessToken(
             token=new_access_token_value,
             client_id=client.client_id,
@@ -260,7 +284,7 @@ class InMemoryOAuthProvider(OAuthProvider):
             scope=" ".join(scopes),
         )
 
-    async def load_access_token(self, token: str) -> AccessToken | None:
+    async def load_access_token(self, token: str) -> AccessToken | None:  # type: ignore[override]
         token_obj = self.access_tokens.get(token)
         if token_obj:
             if token_obj.expires_at is not None and token_obj.expires_at < time.time():
@@ -271,7 +295,7 @@ class InMemoryOAuthProvider(OAuthProvider):
             return token_obj
         return None
 
-    async def verify_token(self, token: str) -> AccessToken | None:
+    async def verify_token(self, token: str) -> AccessToken | None:  # type: ignore[override]
         """
         Verify a bearer token and return access info if valid.
 

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] | NotSetT | None = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT | None = 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