Skip to content

Commit b8b98cb

Browse files
dsp-antdsp-ant
committed
authorization: separate AS/RS
1 parent 3afdc13 commit b8b98cb

File tree

1 file changed

+92
-199
lines changed

1 file changed

+92
-199
lines changed

‎docs/specification/draft/basic/authorization.mdx

Lines changed: 92 additions & 199 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Authorization
33
---
44

5-
<Info>**Protocol Revision**: draft</Info>
5+
<Info>**Protocol Revision**: 2025-03-26</Info>
66

77
## 1. Introduction
88

@@ -28,26 +28,28 @@ This authorization mechanism is based on established specifications listed below
2828
implements a selected subset of their features to ensure security and interoperability
2929
while maintaining simplicity:
3030

31-
- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
31+
- OAuth 2.1 IETF DRAFT ([draft-ietf-oauth-v2-1-12](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12))
3232
- OAuth 2.0 Authorization Server Metadata
3333
([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414))
3434
- OAuth 2.0 Dynamic Client Registration Protocol
3535
([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591))
36+
- OAuth 2.0 Protected Resource Metadata IETF DRAFT ([draft-ietf-oauth-resource-metadata-13](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-13))
3637

3738
## 2. Authorization Flow
3839

3940
### 2.1 Overview
4041

41-
1. MCP auth implementations **MUST** implement OAuth 2.1 with appropriate security
42+
1. MCP authorization servers **MUST** implement OAuth 2.1 with appropriate security
4243
measures for both confidential and public clients.
4344

44-
2. MCP auth implementations **SHOULD** support the OAuth 2.0 Dynamic Client Registration
45+
1. MCP authorization servers and MCP clients **SHOULD** support the OAuth 2.0 Dynamic Client Registration
4546
Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)).
4647

47-
3. MCP servers **SHOULD** and MCP clients **MUST** implement OAuth 2.0 Authorization
48-
Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). Servers
49-
that do not support Authorization Server Metadata **MUST** follow the default URI
50-
schema.
48+
1. MCP servers **MUST** implement [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-13).
49+
MCP clients **MUST** use OAuth 2.0 Protected Resource Metadata for authorization discovery.
50+
51+
1. MCP authorization servers and MCP clients **MUST** implement OAuth 2.0 Authorization
52+
Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)).
5153

5254
### 2.1.1 OAuth Grant Types
5355

@@ -63,119 +65,82 @@ audience. For instance:
6365
- For instance, an agent calls a secure MCP tool to check inventory at a specific
6466
store. No need to impersonate the end user.
6567

66-
### 2.2 Example: authorization code grant
67-
68-
This demonstrates the OAuth 2.1 flow for the authorization code grant type, used for user
69-
auth.
70-
71-
**NOTE**: The following example assumes the MCP server is also functioning as the
72-
authorization server. However, the authorization server may be deployed as its own
73-
distinct service.
74-
75-
A human user completes the OAuth flow through a web browser, obtaining an access token
76-
that identifies them personally and allows the client to act on their behalf.
68+
### 2.2 Roles
69+
A protected MCP server acts as a [OAuth 2.1 resource server](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-12.html#name-roles),
70+
capable of accepting and responding to protected resource requests using access tokens.
7771

78-
When authorization is required and not yet proven by the client, servers **MUST** respond
79-
with _HTTP 401 Unauthorized_.
72+
An MCP client acts a [OAuth 2.1 client](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-12.html#name-roles),
73+
making protected resource requests on behalf of a resource owner.
8074

81-
Clients initiate the
82-
[OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#name-authorization-code-grant)
83-
authorization flow after receiving the _HTTP 401 Unauthorized_.
75+
The authorization server is responsible for interacting with the user and issuing access tokens for use at the MCP server. The implementation details of the authorization server are beyond the scope of this specification. It may be the same server as the
76+
resource server or a separate entity. Section [2.3 Authorization Server Discovery](#2-3-authorizaton-server-discovery)
77+
specifies how an MCP server indicates the location of an authorization server to a client.
8478

85-
The following demonstrates the basic OAuth 2.1 for public clients using PKCE.
79+
### 2.3 Authorization Server Discovery
80+
This section describes the mechanisms by which MCP servers advertise their associated
81+
authorization servers to MCP clients, as well as the discovery process through which MCP
82+
clients can determine authorization server endpoints and supported capabilities.
8683

87-
```mermaid
88-
sequenceDiagram
89-
participant B as User-Agent (Browser)
90-
participant C as Client
91-
participant M as MCP Server
84+
### 2.3.1 Authorization Server Location
85+
MCP servers **MUST** implement the [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-13)
86+
specification to indicate the locations of authorization servers. The Protected Resource Metadata document returned by the MCP server **MUST** include
87+
the `authorization_servers` field containing at least one authorization server.
9288

93-
C->>M: MCP Request
94-
M->>C: HTTP 401 Unauthorized
95-
Note over C: Generate code_verifier and code_challenge
96-
C->>B: Open browser with authorization URL + code_challenge
97-
B->>M: GET /authorize
98-
Note over M: User logs in and authorizes
99-
M->>B: Redirect to callback URL with auth code
100-
B->>C: Callback with authorization code
101-
C->>M: Token Request with code + code_verifier
102-
M->>C: Access Token (+ Refresh Token)
103-
C->>M: MCP Request with Access Token
104-
Note over C,M: Begin standard MCP message exchange
105-
```
89+
The specific use of `authorization_servers` is beyond the scope of this specification; implementers should consult
90+
the [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-13) documentation for
91+
guidance on implementation details.
10692

107-
### 2.3 Server Metadata Discovery
93+
MCP servers **MUST** use the HTTP header `WWW-Authenticate` when returning a _401 Unauthorized_ to indicate the location of the resource server metadata URL
94+
as described in [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-13).
10895

109-
For server capability discovery:
96+
MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
11097

111-
- MCP clients _MUST_ follow the OAuth 2.0 Authorization Server Metadata protocol defined
112-
in [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414).
113-
- MCP server _SHOULD_ follow the OAuth 2.0 Authorization Server Metadata protocol.
114-
- MCP servers that do not support the OAuth 2.0 Authorization Server Metadata protocol,
115-
_MUST_ support fallback URLs.
11698

117-
The discovery flow is illustrated below:
99+
#### 2.3.2 Server Metadata Discovery
118100

119-
```mermaid
120-
sequenceDiagram
121-
participant C as Client
122-
participant S as Server
123-
124-
C->>S: GET /.well-known/oauth-authorization-server
125-
alt Discovery Success
126-
S->>C: 200 OK + Metadata Document
127-
Note over C: Use endpoints from metadata
128-
else Discovery Failed
129-
S->>C: 404 Not Found
130-
Note over C: Fall back to default endpoints
131-
end
132-
Note over C: Continue with authorization flow
133-
```
101+
MCP clients **MUST** follow the OAuth 2.0 Authorization Server Metadata protocol defined
102+
in [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414) to obtain the information
103+
required to interact with the authorization server.
134104

135-
#### 2.3.1 Server Metadata Discovery Headers
105+
#### 2.3.3 MCP specific headers for discovery
136106

137-
MCP clients _SHOULD_ include the header `MCP-Protocol-Version: <protocol-version>` during
107+
MCP clients **SHOULD** include the `MCP-Protocol-Version: <protocol-version>` HTTP header during
138108
Server Metadata Discovery to allow the MCP server to respond based on the MCP protocol
139109
version.
140110

141-
For example: `MCP-Protocol-Version: 2024-11-05`
142-
143-
#### 2.3.2 Authorization Base URL
111+
MCP servers **SHOULD** use the `MCP-Protocol-Version` header to determine compatibility with the MCP client.
144112

145-
The authorization base URL **MUST** be determined from the MCP server URL by discarding
146-
any existing `path` component. For example:
147-
148-
If the MCP server URL is `https://api.example.com/v1/mcp`, then:
113+
For example: `MCP-Protocol-Version: 2024-11-05`
149114

150-
- The authorization base URL is `https://api.example.com`
151-
- The metadata endpoint **MUST** be at
152-
`https://api.example.com/.well-known/oauth-authorization-server`
115+
#### 2.3.4 Sequence Diagram
116+
The following diagram outlines an example flow:
153117

154-
This ensures authorization endpoints are consistently located at the root level of the
155-
domain hosting the MCP server, regardless of any path components in the MCP server URL.
118+
```mermaid
119+
sequenceDiagram
120+
participant C as Client
121+
participant M as MCP Server (Resource Server)
122+
participant A as Authorization Server
156123
157-
#### 2.3.3 Fallbacks for Servers without Metadata Discovery
124+
C->>M: MCP Request without token
125+
M-->>C: HTTP 401 Unauthorized with WWW-Authenticate header
126+
Note over C: Extract resource_metadata<br />from WWW-Authenticate
158127
159-
For servers that do not implement OAuth 2.0 Authorization Server Metadata, clients
160-
**MUST** use the following default endpoint paths relative to the authorization base URL
161-
(as defined in [Section 2.3.2](#232-authorization-base-url)):
128+
C->>M: GET /.well-known/oauth-protected-resource
129+
M-->>C: Resource metadata with authorization server URL
130+
Note over C: Validate RS Metadata,<br />build AS metadata URL
162131
163-
| Endpoint | Default Path | Description |
164-
| ---------------------- | ------------ | ------------------------------------ |
165-
| Authorization Endpoint | /authorize | Used for authorization requests |
166-
| Token Endpoint | /token | Used for token exchange & refresh |
167-
| Registration Endpoint | /register | Used for dynamic client registration |
132+
C->>A: GET /.well-known/oauth-authorization-server
133+
A-->>C: Authorization server metadata
168134
169-
For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default
170-
endpoints would be:
135+
Note over C,A: OAuth 2.1 authorization flow happens here
171136
172-
- `https://api.example.com/authorize`
173-
- `https://api.example.com/token`
174-
- `https://api.example.com/register`
137+
C->>A: Token Request
138+
A-->>C: Access Token
175139
176-
Clients **MUST** first attempt to discover endpoints via the metadata document before
177-
falling back to default paths. When using default paths, all other protocol requirements
178-
remain unchanged.
140+
C->>M: MCP Request with Access Token
141+
M-->>C: Protected Resource Response
142+
Note over C,M: MCP communication continues with valid token
143+
```
179144

180145
### 2.4 Dynamic Client Registration
181146

@@ -208,53 +173,36 @@ The complete Authorization flow proceeds as follows:
208173
sequenceDiagram
209174
participant B as User-Agent (Browser)
210175
participant C as Client
211-
participant M as MCP Server
176+
participant M as MCP Server (Resource Server)
177+
participant A as Authorization Server
212178
213-
C->>M: GET /.well-known/oauth-authorization-server
214-
alt Server Supports Discovery
215-
M->>C: Authorization Server Metadata
216-
else No Discovery
217-
M->>C: 404 (Use default endpoints)
179+
C->>M: MCP Request without token
180+
M->>C: HTTP 401 Unauthorized with WWW-Authenticate header
181+
Note over C: Extract resource_metadata from WWW-Authenticate
182+
183+
alt WWW-Authenticate header not present
184+
C->>M: GET /.well-known/oauth-protected-resource
185+
M->>C: Resource metadata with authorization_server URL
218186
end
219187
188+
C->>A: GET /.well-known/oauth-authorization-server
189+
A->>C: Authorization server metadata
190+
220191
alt Dynamic Client Registration
221-
C->>M: POST /register
222-
M->>C: Client Credentials
192+
C->>A: POST /register
193+
A->>C: Client Credentials
223194
end
224195
225196
Note over C: Generate PKCE Parameters
226197
C->>B: Open browser with authorization URL + code_challenge
227-
B->>M: Authorization Request
228-
Note over M: User /authorizes
229-
M->>B: Redirect to callback with authorization code
198+
B->>A: Authorization Request
199+
Note over A: User authorizes
200+
A->>B: Redirect to callback with authorization code
230201
B->>C: Authorization code callback
231-
C->>M: Token Request + code_verifier
232-
M->>C: Access Token (+ Refresh Token)
233-
C->>M: API Requests with Access Token
234-
```
235-
236-
#### 2.5.1 Decision Flow Overview
237-
238-
```mermaid
239-
flowchart TD
240-
A[Start Auth Flow] --> B{Check Metadata Discovery}
241-
B -->|Available| C[Use Metadata Endpoints]
242-
B -->|Not Available| D[Use Default Endpoints]
243-
244-
C --> G{Check Registration Endpoint}
245-
D --> G
246-
247-
G -->|Available| H[Perform Dynamic Registration]
248-
G -->|Not Available| I[Alternative Registration Required]
249-
250-
H --> J[Start OAuth Flow]
251-
I --> J
252-
253-
J --> K[Generate PKCE Parameters]
254-
K --> L[Request Authorization]
255-
L --> M[User Authorization]
256-
M --> N[Exchange Code for Tokens]
257-
N --> O[Use Access Token]
202+
C->>A: Token Request + code_verifier
203+
A->>C: Access Token (+ Refresh Token)
204+
C->>M: MCP Request with Access Token
205+
M->>C: Protected Resource Response
258206
```
259207

260208
### 2.6 Access Token Usage
@@ -294,6 +242,11 @@ If validation fails, servers **MUST** respond according to
294242
error handling requirements. Invalid or expired tokens **MUST** receive a HTTP 401
295243
response.
296244

245+
MCP client **MUST NOT** send tokens other than issued by the MCP authorization server.
246+
247+
MCP servers **MUST** only issue tokens that are valid for use with their own resources.
248+
MCP servers **MUST NOT** accept or transit any other tokens.
249+
297250
### 2.7 Security Considerations
298251

299252
The following security requirements **MUST** be implemented:
@@ -317,70 +270,10 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors:
317270
### 2.9 Implementation Requirements
318271

319272
1. Implementations **MUST** follow OAuth 2.1 security best practices
320-
2. PKCE is **REQUIRED** for all clients
321-
3. Token rotation **SHOULD** be implemented for enhanced security
322-
4. Token lifetimes **SHOULD** be limited based on security requirements
323-
324-
### 2.10 Third-Party Authorization Flow
325-
326-
#### 2.10.1 Overview
327-
328-
MCP servers **MAY** support delegated authorization through third-party authorization
329-
servers. In this flow, the MCP server acts as both an OAuth client (to the third-party
330-
auth server) and an OAuth authorization server (to the MCP client).
331-
332-
#### 2.10.2 Flow Description
333-
334-
The third-party authorization flow comprises these steps:
335-
336-
1. MCP client initiates standard OAuth flow with MCP server
337-
2. MCP server redirects user to third-party authorization server
338-
3. User authorizes with third-party server
339-
4. Third-party server redirects back to MCP server with authorization code
340-
5. MCP server exchanges code for third-party access token
341-
6. MCP server generates its own access token bound to the third-party session
342-
7. MCP server completes original OAuth flow with MCP client
343-
344-
```mermaid
345-
sequenceDiagram
346-
participant B as User-Agent (Browser)
347-
participant C as MCP Client
348-
participant M as MCP Server
349-
participant T as Third-Party Auth Server
350-
351-
C->>M: Initial OAuth Request
352-
M->>B: Redirect to Third-Party /authorize
353-
B->>T: Authorization Request
354-
Note over T: User authorizes
355-
T->>B: Redirect to MCP Server callback
356-
B->>M: Authorization code
357-
M->>T: Exchange code for token
358-
T->>M: Third-party access token
359-
Note over M: Generate bound MCP token
360-
M->>B: Redirect to MCP Client callback
361-
B->>C: MCP authorization code
362-
C->>M: Exchange code for token
363-
M->>C: MCP access token
364-
```
365-
366-
#### 2.10.3 Session Binding Requirements
367-
368-
MCP servers implementing third-party authorization **MUST**:
369-
370-
1. Maintain secure mapping between third-party tokens and issued MCP tokens
371-
2. Validate third-party token status before honoring MCP tokens
372-
3. Implement appropriate token lifecycle management
373-
4. Handle third-party token expiration and renewal
374-
375-
#### 2.10.4 Security Considerations
376-
377-
When implementing third-party authorization, servers **MUST**:
378-
379-
1. Validate all redirect URIs
380-
2. Securely store third-party credentials
381-
3. Implement appropriate session timeout handling
382-
4. Consider security implications of token chaining
383-
5. Implement proper error handling for third-party auth failures
273+
1. PKCE is **REQUIRED** for all clients
274+
1. MCP clients or MCP servers that also act as an AS
275+
1. **SHOULD** implement token rotation for enhanced security
276+
1. Token lifetimes **SHOULD** be limited based on security requirements
384277

385278
## 3. Best Practices
386279

0 commit comments

Comments
 (0)