Add client_secret_basic authentication support (#1334)

Co-authored-by: Paul Carleton <paulc@anthropic.com>

src/mcp/server/auth/handlers/register.py

@@ -49,6 +49,11 @@ class RegistrationHandler:
             )
 
         client_id = str(uuid4())
+
+        # If auth method is None, default to client_secret_post
+        if client_metadata.token_endpoint_auth_method is None:
+            client_metadata.token_endpoint_auth_method = "client_secret_post"
+
         client_secret = None
         if client_metadata.token_endpoint_auth_method != "none":  # pragma: no branch
             # cryptographically secure random 32-byte hex string

src/mcp/server/auth/handlers/revoke.py

@@ -39,6 +39,17 @@ class RevocationHandler:
         """
         Handler for the OAuth 2.0 Token Revocation endpoint.
         """
+        try:
+            client = await self.client_authenticator.authenticate_request(request)
+        except AuthenticationError as e:  # pragma: no cover
+            return PydanticJSONResponse(
+                status_code=401,
+                content=RevocationErrorResponse(
+                    error="unauthorized_client",
+                    error_description=e.message,
+                ),
+            )
+
         try:
             form_data = await request.form()
             revocation_request = RevocationRequest.model_validate(dict(form_data))
@@ -51,20 +62,6 @@ class RevocationHandler:
                 ),
             )
 
-        # Authenticate client
-        try:
-            client = await self.client_authenticator.authenticate(
-                revocation_request.client_id, revocation_request.client_secret
-            )
-        except AuthenticationError as e:  # pragma: no cover
-            return PydanticJSONResponse(
-                status_code=401,
-                content=RevocationErrorResponse(
-                    error="unauthorized_client",
-                    error_description=e.message,
-                ),
-            )
-
         loaders = [
             self.provider.load_access_token,
             partial(self.provider.load_refresh_token, client),

src/mcp/server/auth/handlers/token.py

@@ -91,10 +91,26 @@ class TokenHandler:
         )
 
     async def handle(self, request: Request):
+        try:
+            client_info = await self.client_authenticator.authenticate_request(request)
+        except AuthenticationError as e:
+            # Authentication failures should return 401
+            return PydanticJSONResponse(
+                content=TokenErrorResponse(
+                    error="unauthorized_client",
+                    error_description=e.message,
+                ),
+                status_code=401,
+                headers={
+                    "Cache-Control": "no-store",
+                    "Pragma": "no-cache",
+                },
+            )
+
         try:
             form_data = await request.form()
             token_request = TokenRequest.model_validate(dict(form_data)).root
-        except ValidationError as validation_error:
+        except ValidationError as validation_error:  # pragma: no cover
             return self.response(
                 TokenErrorResponse(
                     error="invalid_request",
@@ -102,19 +118,6 @@ class TokenHandler:
                 )
             )
 
-        try:
-            client_info = await self.client_authenticator.authenticate(
-                client_id=token_request.client_id,
-                client_secret=token_request.client_secret,
-            )
-        except AuthenticationError as e:  # pragma: no cover
-            return self.response(
-                TokenErrorResponse(
-                    error="unauthorized_client",
-                    error_description=e.message,
-                )
-            )
-
         if token_request.grant_type not in client_info.grant_types:  # pragma: no cover
             return self.response(
                 TokenErrorResponse(

src/mcp/server/auth/middleware/client_auth.py

@@ -1,5 +1,11 @@
+import base64
+import binascii
+import hmac
 import time
 from typing import Any
+from urllib.parse import unquote
+
+from starlette.requests import Request
 
 from mcp.server.auth.provider import OAuthAuthorizationServerProvider
 from mcp.shared.auth import OAuthClientInformationFull
@@ -30,19 +36,77 @@ class ClientAuthenticator:
         """
         self.provider = provider
 
-    async def authenticate(self, client_id: str, client_secret: str | None) -> OAuthClientInformationFull:
-        # Look up client information
-        client = await self.provider.get_client(client_id)
+    async def authenticate_request(self, request: Request) -> OAuthClientInformationFull:
+        """
+        Authenticate a client from an HTTP request.
+
+        Extracts client credentials from the appropriate location based on the
+        client's registered authentication method and validates them.
+
+        Args:
+            request: The HTTP request containing client credentials
+
+        Returns:
+            The authenticated client information
+
+        Raises:
+            AuthenticationError: If authentication fails
+        """
+        form_data = await request.form()
+        client_id = form_data.get("client_id")
+        if not client_id:
+            raise AuthenticationError("Missing client_id")
+
+        client = await self.provider.get_client(str(client_id))
         if not client:
             raise AuthenticationError("Invalid client_id")  # pragma: no cover
 
+        request_client_secret: str | None = None
+        auth_header = request.headers.get("Authorization", "")
+
+        if client.token_endpoint_auth_method == "client_secret_basic":
+            if not auth_header.startswith("Basic "):
+                raise AuthenticationError("Missing or invalid Basic authentication in Authorization header")
+
+            try:
+                encoded_credentials = auth_header[6:]  # Remove "Basic " prefix
+                decoded = base64.b64decode(encoded_credentials).decode("utf-8")
+                if ":" not in decoded:
+                    raise ValueError("Invalid Basic auth format")
+                basic_client_id, request_client_secret = decoded.split(":", 1)
+
+                # URL-decode both parts per RFC 6749 Section 2.3.1
+                basic_client_id = unquote(basic_client_id)
+                request_client_secret = unquote(request_client_secret)
+
+                if basic_client_id != client_id:
+                    raise AuthenticationError("Client ID mismatch in Basic auth")
+            except (ValueError, UnicodeDecodeError, binascii.Error):
+                raise AuthenticationError("Invalid Basic authentication header")
+
+        elif client.token_endpoint_auth_method == "client_secret_post":
+            raw_form_data = form_data.get("client_secret")
+            # form_data.get() can return a UploadFile or None, so we need to check if it's a string
+            if isinstance(raw_form_data, str):
+                request_client_secret = str(raw_form_data)
+
+        elif client.token_endpoint_auth_method == "none":
+            request_client_secret = None
+        else:
+            raise AuthenticationError(  # pragma: no cover
+                f"Unsupported auth method: {client.token_endpoint_auth_method}"
+            )
+
         # If client from the store expects a secret, validate that the request provides
         # that secret
         if client.client_secret:  # pragma: no branch
-            if not client_secret:
+            if not request_client_secret:
                 raise AuthenticationError("Client secret is required")  # pragma: no cover
 
-            if client.client_secret != client_secret:
+            # hmac.compare_digest requires that both arguments are either bytes or a `str` containing
+            # only ASCII characters. Since we do not control `request_client_secret`, we encode both
+            # arguments to bytes.
+            if not hmac.compare_digest(client.client_secret.encode(), request_client_secret.encode()):
                 raise AuthenticationError("Invalid client_secret")  # pragma: no cover
 
             if client.client_secret_expires_at and client.client_secret_expires_at < int(time.time()):

src/mcp/server/auth/routes.py

@@ -165,7 +165,7 @@ def build_metadata(
         response_types_supported=["code"],
         response_modes_supported=None,
         grant_types_supported=["authorization_code", "refresh_token"],
-        token_endpoint_auth_methods_supported=["client_secret_post"],
+        token_endpoint_auth_methods_supported=["client_secret_post", "client_secret_basic"],
         token_endpoint_auth_signing_alg_values_supported=None,
         service_documentation=service_documentation_url,
         ui_locales_supported=None,
@@ -182,7 +182,7 @@ def build_metadata(
     # Add revocation endpoint if supported
     if revocation_options.enabled:  # pragma: no branch
         metadata.revocation_endpoint = AnyHttpUrl(str(issuer_url).rstrip("/") + REVOCATION_PATH)
-        metadata.revocation_endpoint_auth_methods_supported = ["client_secret_post"]
+        metadata.revocation_endpoint_auth_methods_supported = ["client_secret_post", "client_secret_basic"]
 
     return metadata