Merge pull request #3 from modelcontextprotocol/d-mcadams/oauth-client-credentials
SEP-1046 and SEP-1502: Support client credentials flow as an auth extension
This commit is contained in:
Paul Carleton
GitHub
commit
2c9438175d
1 changed files with 163 additions and 0 deletions
163
specification/draft/oauth-client-credentials.mdx
Normal file
163
specification/draft/oauth-client-credentials.mdx
Normal file
|
|
@ -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).
|
||||
Loading…
Reference in a new issue