Skip to content

oauth-client-credentials.mdx

Latest commit

 

History

History
163 lines (122 loc) · 5.41 KB

oauth-client-credentials.mdx

File metadata and controls

163 lines (122 loc) · 5.41 KB
title OAuth Client Credentials Extension

Protocol Revision: draft

Introduction

Purpose and Scope

This extension defines OAuth 2.1 Client Credentials flow support for the Model Context Protocol, enabling machine-to-machine authentication without user interaction. This extension builds upon the baseline authorization requirements defined in the main Authorization specification.

Extension Requirements

This extension is OPTIONAL for MCP implementations. When adopted:

  • Implementations MUST conform to all requirements specified in this extension
  • Implementations MUST also conform to the baseline authorization requirements
  • This extension is specifically designed for HTTP-based transports

Standards Compliance

This extension is based on the following established specifications:

  • OAuth 2.1 IETF DRAFT (draft-ietf-oauth-v2-1-13)
  • OAuth 2.0 Authorization Server Metadata (RFC8414)
  • OAuth 2.0 Protected Resource Metadata (RFC9728)
  • JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC7523)

Client Credentials Flow

Overview

The Client Credentials flow enables machine-to-machine authentication without user interaction. This flow requires pre-registered client credentials, which are typically established out-of-band through administrative channels. Dynamic Client Registration is not used in this flow.

Client Authentication Methods

Clients MUST authenticate using one of these methods:

  • JWT Authentication (RECOMMENDED)
  • Client Secret

Server Metadata Requirements

When supporting the client credentials flow, Authorization Server metadata MUST include the following fields:

  • token_endpoint_auth_methods_supported: MUST include at least one of:
    • "private_key_jwt"
    • "client_secret_basic"
  • token_endpoint_auth_signing_alg_values_supported: Required when supporting JWT authentication

Flow Steps

The complete Client Credentials flow proceeds as follows:

sequenceDiagram
    participant C as Client
    participant M as MCP Server (Resource Server)
    participant A as Authorization Server

    C->>M: MCP request without token
    M->>C: HTTP 401 Unauthorized with WWW-Authenticate header
    Note over C: Extract resource_metadata URL from WWW-Authenticate

    C->>M: Request Protected Resource Metadata
    M->>C: Return metadata

    Note over C: Parse metadata and extract authorization server(s)<br/>Client determines AS to use

    C->>A: GET Authorization server metadata endpoint
    Note over C,A: Try OAuth 2.0 and OpenID Connect<br/>discovery endpoints in priority order
    A-->>C: Authorization server metadata

    Note over C: Prepare client authentication
    alt JWT Authentication (RECOMMENDED)
        Note over C: Generate signed JWT assertion
        C->>A: POST /token with client_assertion
    else Client Secret Authentication
        Note over C: Use client_id and client_secret
        C->>A: POST /token with client credentials
    end
    A->>C: Access token
    C->>M: MCP request with access token
    M-->>C: MCP response
    Note over C,M: MCP communication continues with valid token
Loading

Examples

The following examples illustrate both client authentication methods:

JWT Authentication Example

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.
     eyJpc3Mi[...omitted for brevity...].
     cC4hiUPo[...omitted for brevity...]
&resource=https%3A%2F%2Fmcp.example.com
&scope=mcp%3Aread

Note: The client_id parameter is omitted from the request body as RFC 7523 Section 3 specifies that client identification is conveyed through the sub claim within the JWT assertion.

Client Secret Authentication Example

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=s6BhdRkqt3
&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw
&resource=https%3A%2F%2Fmcp.example.com
&scope=mcp%3Aread

Security Considerations

Implementations adopting this extension MUST follow OAuth 2.1 security best practices as laid out in OAuth 2.1 Section 7. "Security Considerations", with particular attention to:

  • Client authentication security
  • Token storage and handling
  • Communication security requirements
  • Client credential protection

For detailed security guidance specific to client credentials flows, refer to RFC 7523 Section 5 "Security Considerations".