OAuth TokenHandler should check Authorization header for client credentials

[Mars9934]

Description

Currently, TokenHandler assumes that the Token request's body contains client credentials. However, some OAuth requests would contain client credentials in Authorization header:

In this case, it would throw ValidationError even though client credentials are provided in request header.

Can we add a fallback such that if client_id is not found in formData, we try to get it from header? e.g.

async def handle(self, request: Request):
    try:
        form_data = dict(await request.form())

        # Try to get client credentials from header if missing in body
        if "client_id" not in form_data:
            auth_header = request.headers.get("Authorization")
            if auth_header and auth_header.startswith("Basic "):
                encoded = auth_header.split(" ")[1]
                decoded = base64.b64decode(encoded).decode("utf-8")
                client_id, _, client_secret = decoded.partition(":")
                client_secret = urllib.parse.unquote(client_secret)
                form_data.setdefault("client_id", client_id)
                form_data.setdefault("client_secret", client_secret)

        token_request = TokenRequest.model_validate(form_data).root
    except ValidationError as validation_error:
        return self.response(
            TokenErrorResponse(
                error="invalid_request",
                error_description=stringify_pydantic_error(validation_error),
            )
        )
    ...

Thanks.

References

No response

[challenger71498]

Hi @Mars9934,

I encountered the same issue you've experienced when I was testing FastMCP server with:

npx @modelcontextprotocol/inspector

The server responds with 401, says "Missing client_id".

Seems like the indicator tries to get token by providing client_id and client_secret via the auth header, but the server only tries to find client credentials from the request body, and fails.

As you mentioned, the current implementation of token handling violates the OAuth2 protocol RFC 6749 - Client Authentication.

Based on RFC 6749:

The client MUST NOT use more than one authentication method in each request.

• Authentication with headers (Authorization: Basic ...) and with form data are mutual exclusive. Only one auth method should be used at a time.
  • Normally the header is preferred, the form data is used only if the client cannot support the auth header.
• mcp.server.auth.middleware.ClientAuthenticator::authenticate_request allows duplicated client_id and client_secret on header and request body.
  • If both are provided, it checks whether the client_id at the header is same as the client_id at the request body, which is not described at RFC and is an unknown behaviour.
  • If client_id and client_secret is both given at header and request body, the server should throw error, indicates that the auth method should be unique.

The authorization server MUST support the HTTP Basic authentication scheme for authenticating clients that were issued a client password

• AS-IS, mcp.server.auth.handlers.TokenHandler::handle and mcp.server.auth.middleware.ClientAuthenticator::authenticate_request ALWAYS check client_id from the form data.
• Client may send client_id only via header, not the request body.
• client_id must be able to be retrieved even if it is not exist at the request body, when it exists at the header.

I am currently working on this issue, and going to create PR soon, which separates client_id discovery and form data.

From the PR:

• Tries to retrieve client_id from headers first, then from form data if failed, at mcp.server.auth.middleware.ClientAuthenticator::authenticate_request.
• Refer client_id from client not form data at mcp.server.auth.handlers.TokenHandler::handle.
• Throws if auth method used in request and registered auth method in the client are not equal.

You may look into the PR after I create it, if you are interested in.

---

Please let me know if there is a correction needed.
Your feedback is greatly appreciated :)
Thank you.

[joar]

I have discovered this issue as well in google/adk-python#4782, in summary
Using Slack's MCP server with google-adk:

• google-adk always included (prior to the fix) client_id in POST /token body; so
• when POST /token with Authorization: Basic …, Slack assumes that the client is attempting to use client_secret_post method, and
• returns an error about missing client_secret in the request body.
• another user also reported the same issue for google-adk when trying to authencitate with Okta: OpenAPIToolset ERROR - oauth2_credential_exchanger.py:208 - Failed to exchange authorization code google/adk-python#4850

However once the issue was solved in google-adk, I found that python-sdk (via FastMCP) requires the client_id to be present in the body. So it seems to me that google-adk has a choice here:

1. be compliant with RFC 6749 and compatible with Slack and Okta; or
2. be compatible with MCPs using python-sdk

---

a possible workaround is to use the client_secret_post method in google-adk, however the RFC 6749 says this about client_secret_post:

Including the client credentials in the request-body using the two
parameters is NOT RECOMMENDED and SHOULD be limited to clients unable
to directly utilize the HTTP Basic authentication scheme (or other
password-based HTTP authentication schemes).
— https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1

---

However, the MCP protocol seems to use OAuth 2.1 draft 13.

OAuth 2.1 draft 13 flips it around a bit in https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-2.4.1 so that:

• servers MUST implement client_secret_post, and
• servers MAY implement HTTP basic auth.

but in https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-3.2.2 of the same draft, it says this about client_id in the body:

"client_id":

OPTIONAL. The client identifier is needed when a form of client authentication that relies on the parameter is used, or the grant_type requires identification of public clients.

My interpretation of this is that when:

• use a confidential client (not a public client)

The client identifier is needed when a form of client authentication that relies on the parameter is used, or the grant_type requires identification of public clients.

• use client_secret_basic (not a form of client authentication that relies on the client_id parameter in the Token Request body)

The client identifier is needed when a form of client authentication that relies on the parameter is used, or the grant_type requires identification of public clients.

then the Authorization Server has no reason require client_id in Token Request body, so the solution in #1847, in addition to following RFC 6749, seems like a reasonable implementation of OAuth 2.1 draft 13, as they both seem to agree on whether client_id should be in the Token Request body when client_secret_basic is used.