π The fast, Pythonic way to build MCP servers and clients.
Refactor OAuth 2.1 error handling with TokenHandler subclass (#1948)
Jeremiah Lowind7c60511b9b8
diff --git a/src/fastmcp/server/auth/oauth_proxy.py b/src/fastmcp/server/auth/oauth_proxy.pyindex 55a19d766..5d0dd217d 100644--- a/src/fastmcp/server/auth/oauth_proxy.py+++ b/src/fastmcp/server/auth/oauth_proxy.py@@ -28,6 +28,10 @@ from urllib.parse import urlencodeimport httpxfrom authlib.common.security import generate_tokenfrom authlib.integrations.httpx_client import AsyncOAuth2Client+from mcp.server.auth.handlers.token import TokenErrorResponse, TokenSuccessResponse+from mcp.server.auth.handlers.token import TokenHandler as _SDKTokenHandler+from mcp.server.auth.json_response import PydanticJSONResponse+from mcp.server.auth.middleware.client_auth import ClientAuthenticatorfrom mcp.server.auth.provider import (AccessToken,AuthorizationCode,@@ -35,6 +39,7 @@ from mcp.server.auth.provider import (RefreshToken,TokenError,)+from mcp.server.auth.routes import cors_middlewarefrom mcp.server.auth.settings import (ClientRegistrationOptions,RevocationOptions,@@ -42,7 +47,7 @@ from mcp.server.auth.settings import (from mcp.shared.auth import OAuthClientInformationFull, OAuthTokenfrom pydantic import AnyHttpUrl, AnyUrl, SecretStrfrom starlette.requests import Request-from starlette.responses import JSONResponse, RedirectResponse+from starlette.responses import RedirectResponsefrom starlette.routing import Routeimport fastmcp@@ -122,6 +127,55 @@ DEFAULT_AUTH_CODE_EXPIRY_SECONDS: Final[int] = 5 * 60 # 5 minutesHTTP_TIMEOUT_SECONDS: Final[int] = 30+class TokenHandler(_SDKTokenHandler):+ """TokenHandler that returns OAuth 2.1 compliant error responses.++ The MCP SDK always returns HTTP 400 for all client authentication issues.+ However, OAuth 2.1 Section 5.3 and the MCP specification require that+ invalid or expired tokens MUST receive a HTTP 401 response.++ This handler extends the base MCP SDK TokenHandler to transform client+ authentication failures into OAuth 2.1 compliant responses:+ - Changes 'unauthorized_client' to 'invalid_client' error code+ - Returns HTTP 401 status code instead of 400 for client auth failures++ Per OAuth 2.1 Section 5.3: "The authorization server MAY return an HTTP 401+ (Unauthorized) status code to indicate which HTTP authentication schemes+ are supported."++ Per MCP spec: "Invalid or expired tokens MUST receive a HTTP 401 response."+ """++ def response(self, obj: TokenSuccessResponse | TokenErrorResponse):+ """Override response method to provide OAuth 2.1 compliant error handling."""+ # Check if this is a client authentication failure (not just unauthorized for grant type)+ # unauthorized_client can mean two things:+ # 1. Client authentication failed (client_id not found or wrong credentials) -> invalid_client 401+ # 2. Client not authorized for this grant type -> unauthorized_client 400 (correct per spec)+ if (+ isinstance(obj, TokenErrorResponse)+ and obj.error == "unauthorized_client"+ and obj.error_description+ and "Invalid client_id" in obj.error_description+ ):+ # Transform client auth failure to OAuth 2.1 compliant response+ return PydanticJSONResponse(+ content=TokenErrorResponse(+ error="invalid_client",+ error_description=obj.error_description,+ error_uri=obj.error_uri,+ ),+ status_code=401,+ headers={+ "Cache-Control": "no-store",+ "Pragma": "no-cache",+ },+ )++ # Otherwise use default behavior from parent class+ return super().response(obj)++class OAuthProxy(OAuthProvider):"""OAuth provider that presents a DCR-compliant interface while proxying to non-DCR IDPs.@@ -852,12 +906,17 @@ class OAuthProxy(OAuthProvider):and "POST" in route.methods):token_route_found = True- # Replace with our custom token handler+ # Replace with our OAuth 2.1 compliant token handler+ token_handler = TokenHandler(+ provider=self, client_authenticator=ClientAuthenticator(self)+ )custom_routes.append(Route(path="/token",- endpoint=self._handle_token_request,- methods=["POST"],+ endpoint=cors_middleware(+ token_handler.handle, ["POST", "OPTIONS"]+ ),+ methods=["POST", "OPTIONS"],))else:@@ -878,81 +937,6 @@ class OAuthProxy(OAuthProvider):)return custom_routes- # -------------------------------------------------------------------------- # Custom Token Endpoint Handler- # --------------------------------------------------------------------------- async def _handle_token_request(self, request: Request) -> JSONResponse:- """Handle token requests with proper OAuth 2.1 error handling.-- This custom handler wraps the standard MCP SDK token handler but provides- OAuth 2.1 compliant error responses for client authentication failures:- - Returns HTTP 401 status code for client authentication failures- - Uses 'invalid_client' error code instead of 'unauthorized_client'-- Per OAuth 2.1 spec: "The authorization server MAY return an HTTP 401- (Unauthorized) status code to indicate which HTTP authentication schemes- are supported. If the client attempted to authenticate via the Authorization- request header field, the authorization server MUST respond with an HTTP 401- (Unauthorized) status code and include the WWW-Authenticate response header- field matching the authentication scheme used by the client."- """- from mcp.server.auth.handlers.token import TokenHandler- from mcp.server.auth.middleware.client_auth import ClientAuthenticator-- # Create the standard token handler and client authenticator- token_handler = TokenHandler(- provider=self, client_authenticator=ClientAuthenticator(self)- )-- # Handle the request normally- response = await token_handler.handle(request)-- # Check if the response is an error response for client authentication failure- if (- hasattr(response, "body")- and hasattr(response, "status_code")- and response.status_code == 400- ):- try:- import json-- # Parse the response body to check for client authentication errors- body_content = (- response.body.decode("utf-8")- if hasattr(response.body, "decode")- else str(response.body)- )- error_data = json.loads(body_content)-- # Check if this is an unauthorized_client error (which means invalid client_id)- if error_data.get(- "error"- ) == "unauthorized_client" and "Invalid client_id" in str(- error_data.get("error_description", "")- ):- logger.debug(- "Client authentication failed - client not found, returning OAuth 2.1 compliant error"- )-- # Return the correct OAuth 2.1 response- return JSONResponse(- content={- "error": "invalid_client",- "error_description": error_data.get("error_description"),- },- status_code=401,- headers={- "Cache-Control": "no-store",- "Pragma": "no-cache",- },- )- except (json.JSONDecodeError, AttributeError, KeyError):- # If we can't parse the response, return it as-is- pass-- return response-# -------------------------------------------------------------------------# IdP Callback Forwarding# -------------------------------------------------------------------------diff --git a/tests/server/auth/test_oauth_proxy.py b/tests/server/auth/test_oauth_proxy.pyindex 3bc82d7b9..2cd866938 100644--- a/tests/server/auth/test_oauth_proxy.py+++ b/tests/server/auth/test_oauth_proxy.py@@ -1029,3 +1029,70 @@ class TestParameterForwarding:# Verify proper cache headers are setassert response.headers.get("Cache-Control") == "no-store"assert response.headers.get("Pragma") == "no-cache"+++class TestTokenHandlerErrorTransformation:+ """Tests for TokenHandler's OAuth 2.1 compliant error transformation."""++ def test_transforms_client_auth_failure_to_invalid_client_401(self):+ """Test that client authentication failures return invalid_client with 401."""+ from mcp.server.auth.handlers.token import TokenErrorResponse++ from fastmcp.server.auth.oauth_proxy import TokenHandler++ handler = TokenHandler(provider=Mock(), client_authenticator=Mock())++ # Simulate error from ClientAuthenticator.authenticate() failure+ error_response = TokenErrorResponse(+ error="unauthorized_client",+ error_description="Invalid client_id 'test-client-id'",+ )++ response = handler.response(error_response)++ # Should transform to OAuth 2.1 compliant response+ assert response.status_code == 401+ assert b'"error":"invalid_client"' in response.body+ assert (+ b'"error_description":"Invalid client_id \'test-client-id\'"'+ in response.body+ )++ def test_does_not_transform_grant_type_unauthorized_to_invalid_client(self):+ """Test that grant type authorization errors stay as unauthorized_client with 400."""+ from mcp.server.auth.handlers.token import TokenErrorResponse++ from fastmcp.server.auth.oauth_proxy import TokenHandler++ handler = TokenHandler(provider=Mock(), client_authenticator=Mock())++ # Simulate error from grant_type not in client_info.grant_types+ error_response = TokenErrorResponse(+ error="unauthorized_client",+ error_description="Client not authorized for this grant type",+ )++ response = handler.response(error_response)++ # Should NOT transform - keep as 400 unauthorized_client+ assert response.status_code == 400+ assert b'"error":"unauthorized_client"' in response.body++ def test_does_not_transform_other_errors(self):+ """Test that other error types pass through unchanged."""+ from mcp.server.auth.handlers.token import TokenErrorResponse++ from fastmcp.server.auth.oauth_proxy import TokenHandler++ handler = TokenHandler(provider=Mock(), client_authenticator=Mock())++ error_response = TokenErrorResponse(+ error="invalid_grant",+ error_description="Authorization code has expired",+ )++ response = handler.response(error_response)++ # Should pass through unchanged+ assert response.status_code == 400+ assert b'"error":"invalid_grant"' in response.body