Merge pull request #3 from modelcontextprotocol/d-mcadams/oauth-client-credentials

SEP-1046 and SEP-1502: Support client credentials flow as an auth extension

Author: pcarleton

specification/draft/oauth-client-credentials.mdx

@@ -0,0 +1,163 @@
+---
+title: OAuth Client Credentials Extension
+---
+
+<div id="enable-section-numbers" />
+
+<Info>**Protocol Revision**: draft</Info>
+
+## 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](../basic/authorization.mdx).
+
+### 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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13))
+- OAuth 2.0 Authorization Server Metadata
+  ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414))
+- OAuth 2.0 Protected Resource Metadata
+  ([RFC9728](https://datatracker.ietf.org/doc/html/rfc9728))
+- JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and
+  Authorization Grants
+  ([RFC7523](https://datatracker.ietf.org/doc/html/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)
+  - Clients use JWT Authentication as defined in
+    [RFC 7523 Section 2.2](https://datatracker.ietf.org/doc/html/rfc7523#section-2.2).
+- Client Secret
+  - Clients use a Client Secret transmitted in the request content as defined
+    in
+    [OAuth 2.1 Section 2.4.1](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#name-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:
+
+```mermaid
+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
+```
+
+### 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](https://datatracker.ietf.org/doc/html/rfc7523#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"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#name-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"](https://datatracker.ietf.org/doc/html/rfc7523#section-5).