π The fast, Pythonic way to build MCP servers and clients.
Fix OAuth proxy refresh token storage for multi-instance deployments (#2483)
Jeremiah Lowin01ecc918074e
diff --git a/src/fastmcp/server/auth/oauth_proxy.py b/src/fastmcp/server/auth/oauth_proxy.pyindex 544da7063..a7acf1368 100644--- a/src/fastmcp/server/auth/oauth_proxy.py+++ b/src/fastmcp/server/auth/oauth_proxy.py@@ -179,6 +179,28 @@ class JTIMapping(BaseModel):created_at: float # Unix timestamp+class RefreshTokenMetadata(BaseModel):+ """Metadata for a refresh token, stored keyed by token hash.++ We store only metadata (not the token itself) for security - if storage+ is compromised, attackers get hashes they can't reverse into usable tokens.+ """++ client_id: str+ scopes: list[str]+ expires_at: int | None = None+ created_at: float+++def _hash_token(token: str) -> str:+ """Hash a token for secure storage lookup.++ Uses SHA-256 to create a one-way hash. The original token cannot be+ recovered from the hash, providing defense in depth if storage is compromised.+ """+ return hashlib.sha256(token.encode()).hexdigest()++class ProxyDCRClient(OAuthClientInformationFull):"""Client for DCR proxy with configurable redirect URI validation.@@ -624,14 +646,18 @@ class OAuthProxy(OAuthProvider):State Management---------------- The proxy maintains minimal but crucial state:+ The proxy maintains minimal but crucial state via pluggable storage (client_storage):- _oauth_transactions: Active authorization flows with client context- _client_codes: Authorization codes with PKCE challenges and upstream tokens- - _access_tokens, _refresh_tokens: Token storage for revocation- - Token relationship mappings for cleanup and rotation+ - _jti_mapping_store: Maps FastMCP token JTIs to upstream token IDs+ - _refresh_token_store: Refresh token metadata (keyed by token hash)++ All state is stored in the configured client_storage backend (Redis, disk, etc.)+ enabling horizontal scaling across multiple instances.Security Considerations----------------------+ - Refresh tokens stored by hash only (defense in depth if storage compromised)- PKCE enforced end-to-end (client to proxy, proxy to upstream)- Authorization codes are single-use with short expiry- Transaction IDs are cryptographically random@@ -895,13 +921,17 @@ class OAuthProxy(OAuthProvider):raise_on_validation_error=True,)- # Local state for token bookkeeping only (no client caching)- self._access_tokens: dict[str, AccessToken] = {}- self._refresh_tokens: dict[str, RefreshToken] = {}-- # Token relation mappings for cleanup- self._access_to_refresh: dict[str, str] = {}- self._refresh_to_access: dict[str, str] = {}+ # Refresh token metadata storage, keyed by token hash for security.+ # We only store metadata (not the token itself) - if storage is compromised,+ # attackers get hashes they can't reverse into usable tokens.+ self._refresh_token_store: PydanticAdapter[RefreshTokenMetadata] = (+ PydanticAdapter[RefreshTokenMetadata](+ key_value=self._client_storage,+ pydantic_model=RefreshTokenMetadata,+ default_collection="mcp-refresh-tokens",+ raise_on_validation_error=True,+ )+ )# Use the provided token validatorself._token_validator: TokenVerifier = token_verifier@@ -1254,25 +1284,18 @@ class OAuthProxy(OAuthProvider):ttl=60 * 60 * 24 * 30, # Auto-expire with refresh token (30 days))- # Store FastMCP access token for MCP framework validation- self._access_tokens[fastmcp_access_token] = AccessToken(- token=fastmcp_access_token,- client_id=client.client_id,- scopes=authorization_code.scopes,- expires_at=int(time.time() + expires_in),- )-- # Store FastMCP refresh token if provided- if fastmcp_refresh_token:- self._refresh_tokens[fastmcp_refresh_token] = RefreshToken(- token=fastmcp_refresh_token,- client_id=client.client_id,- scopes=authorization_code.scopes,- expires_at=None,+ # Store refresh token metadata (keyed by hash for security)+ if fastmcp_refresh_token and refresh_expires_in:+ await self._refresh_token_store.put(+ key=_hash_token(fastmcp_refresh_token),+ value=RefreshTokenMetadata(+ client_id=client.client_id,+ scopes=authorization_code.scopes,+ expires_at=int(time.time()) + refresh_expires_in,+ created_at=time.time(),+ ),+ ttl=refresh_expires_in,)- # Maintain token relationships for cleanup- self._access_to_refresh[fastmcp_access_token] = fastmcp_refresh_token- self._refresh_to_access[fastmcp_refresh_token] = fastmcp_access_tokenlogger.debug("Issued FastMCP tokens for client=%s (access_jti=%s, refresh_jti=%s)",@@ -1316,8 +1339,29 @@ class OAuthProxy(OAuthProvider):client: OAuthClientInformationFull,refresh_token: str,) -> RefreshToken | None:- """Load refresh token from local storage."""- return self._refresh_tokens.get(refresh_token)+ """Load refresh token metadata from distributed storage.++ Looks up by token hash and reconstructs the RefreshToken object.+ Validates that the token belongs to the requesting client.+ """+ token_hash = _hash_token(refresh_token)+ metadata = await self._refresh_token_store.get(key=token_hash)+ if not metadata:+ return None+ # Verify token belongs to this client (prevents cross-client token usage)+ if metadata.client_id != client.client_id:+ logger.warning(+ "Refresh token client_id mismatch: expected %s, got %s",+ client.client_id,+ metadata.client_id,+ )+ return None+ return RefreshToken(+ token=refresh_token,+ client_id=metadata.client_id,+ scopes=metadata.scopes,+ expires_at=metadata.expires_at,+ )async def exchange_refresh_token(self,@@ -1488,30 +1532,20 @@ class OAuthProxy(OAuthProvider):"Rotated refresh token (old JTI invalidated - one-time use enforced)")- # Update local token tracking- self._access_tokens[new_fastmcp_access] = AccessToken(- token=new_fastmcp_access,- client_id=client.client_id,- scopes=scopes,- expires_at=int(time.time() + new_expires_in),- )- self._refresh_tokens[new_fastmcp_refresh] = RefreshToken(- token=new_fastmcp_refresh,- client_id=client.client_id,- scopes=scopes,- expires_at=None,+ # Store new refresh token metadata (keyed by hash)+ await self._refresh_token_store.put(+ key=_hash_token(new_fastmcp_refresh),+ value=RefreshTokenMetadata(+ client_id=client.client_id,+ scopes=scopes,+ expires_at=int(time.time()) + refresh_ttl,+ created_at=time.time(),+ ),+ ttl=refresh_ttl,)- # Update token relationship mappings- self._access_to_refresh[new_fastmcp_access] = new_fastmcp_refresh- self._refresh_to_access[new_fastmcp_refresh] = new_fastmcp_access-- # Clean up old token from in-memory tracking- self._refresh_tokens.pop(refresh_token.token, None)- old_access = self._refresh_to_access.pop(refresh_token.token, None)- if old_access:- self._access_tokens.pop(old_access, None)- self._access_to_refresh.pop(old_access, None)+ # Delete old refresh token (by hash)+ await self._refresh_token_store.delete(key=_hash_token(refresh_token.token))logger.info("Issued new FastMCP tokens (rotated refresh) for client=%s (access_jti=%s, refresh_jti=%s)",@@ -1592,24 +1626,13 @@ class OAuthProxy(OAuthProvider):async def revoke_token(self, token: AccessToken | RefreshToken) -> None:"""Revoke token locally and with upstream server if supported.- Removes tokens from local storage and attempts to revoke them with- the upstream server if a revocation endpoint is configured.+ For refresh tokens, removes from local storage by hash.+ For all tokens, attempts upstream revocation if endpoint is configured.+ Access token JTI mappings expire via TTL."""- # Clean up local token storage- if isinstance(token, AccessToken):- self._access_tokens.pop(token.token, None)- # Also remove associated refresh token- paired_refresh = self._access_to_refresh.pop(token.token, None)- if paired_refresh:- self._refresh_tokens.pop(paired_refresh, None)- self._refresh_to_access.pop(paired_refresh, None)- else: # RefreshToken- self._refresh_tokens.pop(token.token, None)- # Also remove associated access token- paired_access = self._refresh_to_access.pop(token.token, None)- if paired_access:- self._access_tokens.pop(paired_access, None)- self._access_to_refresh.pop(paired_access, None)+ # For refresh tokens, delete from local storage by hash+ if isinstance(token, RefreshToken):+ await self._refresh_token_store.delete(key=_hash_token(token.token))# Attempt upstream revocation if endpoint is configuredif self._upstream_revocation_endpoint: