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