diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx index 91d9b6be4..f1a1991e4 100644 --- a/docs/specification/draft/basic/authorization.mdx +++ b/docs/specification/draft/basic/authorization.mdx @@ -28,26 +28,28 @@ This authorization mechanism is based on established specifications listed below implements a selected subset of their features to ensure security and interoperability while maintaining simplicity: -- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) +- OAuth 2.1 IETF DRAFT ([draft-ietf-oauth-v2-1-12](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)) - OAuth 2.0 Authorization Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)) - OAuth 2.0 Dynamic Client Registration Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)) +- OAuth 2.0 Protected Resource Metadata ([RFC9728](https://datatracker.ietf.org/doc/html/rfc9728)) ## 2. Authorization Flow ### 2.1 Overview -1. MCP auth implementations **MUST** implement OAuth 2.1 with appropriate security +1. MCP authorization servers **MUST** implement OAuth 2.1 with appropriate security measures for both confidential and public clients. -2. MCP auth implementations **SHOULD** support the OAuth 2.0 Dynamic Client Registration +1. MCP authorization servers and MCP clients **SHOULD** support the OAuth 2.0 Dynamic Client Registration Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). -3. MCP servers **SHOULD** and MCP clients **MUST** implement OAuth 2.0 Authorization - Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). Servers - that do not support Authorization Server Metadata **MUST** follow the default URI - schema. +1. MCP servers **MUST** implement [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-13). + MCP clients **MUST** use OAuth 2.0 Protected Resource Metadata for authorization server discovery. + +1. MCP authorization servers and MCP clients **MUST** implement OAuth 2.0 Authorization + Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). ### 2.1.1 OAuth Grant Types @@ -63,144 +65,106 @@ audience. For instance: - For instance, an agent calls a secure MCP tool to check inventory at a specific store. No need to impersonate the end user. -### 2.2 Example: authorization code grant - -This demonstrates the OAuth 2.1 flow for the authorization code grant type, used for user -auth. +### 2.2 Roles +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), +capable of accepting and responding to protected resource requests using access tokens. -**NOTE**: The following example assumes the MCP server is also functioning as the -authorization server. However, the authorization server may be deployed as its own -distinct service. +An MCP client acts as an [OAuth 2.1 client](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-12.html#name-roles), +making protected resource requests on behalf of a resource owner. -A human user completes the OAuth flow through a web browser, obtaining an access token -that identifies them personally and allows the client to act on their behalf. +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 +resource server or a separate entity. Section [2.3 Authorization Server Discovery](#2-3-authorizaton-server-discovery) +specifies how an MCP server indicates the location of its corresponding authorization server to a client. -When authorization is required and not yet proven by the client, servers **MUST** respond -with _HTTP 401 Unauthorized_. +### 2.3 Authorization Server Discovery +This section describes the mechanisms by which MCP servers advertise their associated +authorization servers to MCP clients, as well as the discovery process through which MCP +clients can determine authorization server endpoints and supported capabilities. -Clients initiate the -[OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#name-authorization-code-grant) -authorization flow after receiving the _HTTP 401 Unauthorized_. +### 2.3.1 Authorization Server Location +MCP servers **MUST** implement the [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-13) +specification to indicate the locations of authorization servers. The Protected Resource Metadata document returned by the MCP server **MUST** include +the `authorization_servers` field containing at least one authorization server. -The following demonstrates the basic OAuth 2.1 for public clients using PKCE. +The specific use of `authorization_servers` is beyond the scope of this specification; implementers should consult +the [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-13) documentation for +guidance on implementation details. -```mermaid -sequenceDiagram - participant B as User-Agent (Browser) - participant C as Client - participant M as MCP Server +MCP servers **MUST** use the HTTP header `WWW-Authenticate` when returning a _401 Unauthorized_ to indicate the location of the resource server metadata URL +as described in [OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-resource-metadata-13). - C->>M: MCP Request - M->>C: HTTP 401 Unauthorized - Note over C: Generate code_verifier and code_challenge - C->>B: Open browser with authorization URL + code_challenge - B->>M: GET /authorize - Note over M: User logs in and authorizes - M->>B: Redirect to callback URL with auth code - B->>C: Callback with authorization code - C->>M: Token Request with code + code_verifier - M->>C: Access Token (+ Refresh Token) - C->>M: MCP Request with Access Token - Note over C,M: Begin standard MCP message exchange -``` +MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server. -### 2.3 Server Metadata Discovery -For server capability discovery: +#### 2.3.2 Server Metadata Discovery -- MCP clients _MUST_ follow the OAuth 2.0 Authorization Server Metadata protocol defined - in [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414). -- MCP server _SHOULD_ follow the OAuth 2.0 Authorization Server Metadata protocol. -- MCP servers that do not support the OAuth 2.0 Authorization Server Metadata protocol, - _MUST_ support fallback URLs. +MCP clients **MUST** follow the OAuth 2.0 Authorization Server Metadata protocol defined +in [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414) to obtain the information +required to interact with the authorization server. -The discovery flow is illustrated below: +#### 2.3.4 Sequence Diagram +The following diagram outlines an example flow: ```mermaid sequenceDiagram participant C as Client - participant S as Server - - C->>S: GET /.well-known/oauth-authorization-server - alt Discovery Success - S->>C: 200 OK + Metadata Document - Note over C: Use endpoints from metadata - else Discovery Failed - S->>C: 404 Not Found - Note over C: Fall back to default endpoints - end - Note over C: Continue with authorization flow -``` - -#### 2.3.1 Server Metadata Discovery Headers - -MCP clients _SHOULD_ include the header `MCP-Protocol-Version: ` during -Server Metadata Discovery to allow the MCP server to respond based on the MCP protocol -version. + participant M as MCP Server (Resource Server) + participant A as Authorization Server -For example: `MCP-Protocol-Version: 2024-11-05` - -#### 2.3.2 Authorization Base URL - -The authorization base URL **MUST** be determined from the MCP server URL by discarding -any existing `path` component. For example: + C->>M: MCP request without token + M-->>C: HTTP 401 Unauthorized with WWW-Authenticate header + Note over C: Extract resource_metadata
from WWW-Authenticate -If the MCP server URL is `https://api.example.com/v1/mcp`, then: + C->>M: GET /.well-known/oauth-protected-resource + M-->>C: Resource metadata with authorization server URL + Note over C: Validate RS metadata,
build AS metadata URL -- The authorization base URL is `https://api.example.com` -- The metadata endpoint **MUST** be at - `https://api.example.com/.well-known/oauth-authorization-server` + C->>A: GET /.well-known/oauth-authorization-server + A-->>C: Authorization server metadata -This ensures authorization endpoints are consistently located at the root level of the -domain hosting the MCP server, regardless of any path components in the MCP server URL. + Note over C,A: OAuth 2.1 authorization flow happens here -#### 2.3.3 Fallbacks for Servers without Metadata Discovery + C->>A: Token request + A-->>C: Access token -For servers that do not implement OAuth 2.0 Authorization Server Metadata, clients -**MUST** use the following default endpoint paths relative to the authorization base URL -(as defined in [Section 2.3.2](#232-authorization-base-url)): + C->>M: MCP request with access token + M-->>C: MCP response + Note over C,M: MCP communication continues with valid token +``` -| Endpoint | Default Path | Description | -| ---------------------- | ------------ | ------------------------------------ | -| Authorization Endpoint | /authorize | Used for authorization requests | -| Token Endpoint | /token | Used for token exchange & refresh | -| Registration Endpoint | /register | Used for dynamic client registration | +#### 2.4 MCP specific headers for discovery -For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default -endpoints would be: +MCP clients **SHOULD** include the `MCP-Protocol-Version: ` HTTP header during +any request to the MCP server allowing the MCP server to respond based on the MCP protocol version. -- `https://api.example.com/authorize` -- `https://api.example.com/token` -- `https://api.example.com/register` +MCP servers **SHOULD** use the `MCP-Protocol-Version` header to determine compatibility with the MCP client. -Clients **MUST** first attempt to discover endpoints via the metadata document before -falling back to default paths. When using default paths, all other protocol requirements -remain unchanged. +For example: `MCP-Protocol-Version: 2024-11-05` -### 2.4 Dynamic Client Registration +### 2.5 Dynamic Client Registration -MCP clients and servers **SHOULD** support the +MCP clients and authorization servers **SHOULD** support the [OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591) to allow MCP clients to obtain OAuth client IDs without user interaction. This provides a -standardized way for clients to automatically register with new servers, which is crucial +standardized way for clients to automatically register with new authorization servers, which is crucial for MCP because: -- Clients cannot know all possible servers in advance -- Manual registration would create friction for users -- It enables seamless connection to new servers -- Servers can implement their own registration policies +- Clients may not know all possible MCP servers and their authorization servers in advance. +- Manual registration would create friction for users. +- It enables seamless connection to new MCP servers and their authorization servers. +- Authorization servers can implement their own registration policies. -Any MCP servers that _do not_ support Dynamic Client Registration need to provide -alternative ways to obtain a client ID (and, if applicable, client secret). For one of -these servers, MCP clients will have to either: +Any MCP authorization servers that _do not_ support Dynamic Client Registration need to provide +alternative ways to obtain a client ID (and, if applicable, client credentials). For one of +these authorization servers, MCP clients will have to either: -1. Hardcode a client ID (and, if applicable, client secret) specifically for that MCP +1. Hardcode a client ID (and, if applicable, client credentials) specifically for that MCP server, or 2. Present a UI to users that allows them to enter these details, after registering an OAuth client themselves (e.g., through a configuration interface hosted by the server). -### 2.5 Authorization Flow Steps +### 2.6 Authorization Flow Steps The complete Authorization flow proceeds as follows: @@ -208,58 +172,36 @@ The complete Authorization flow proceeds as follows: sequenceDiagram participant B as User-Agent (Browser) participant C as Client - participant M as MCP Server + participant M as MCP Server (Resource Server) + participant A as Authorization Server - C->>M: GET /.well-known/oauth-authorization-server - alt Server Supports Discovery - M->>C: Authorization Server Metadata - else No Discovery - M->>C: 404 (Use default endpoints) - end + 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 - alt Dynamic Client Registration - C->>M: POST /register - M->>C: Client Credentials + C->>A: GET /.well-known/oauth-authorization-server + A->>C: Authorization server metadata response + + alt Dynamic client registration + C->>A: POST /register + A->>C: Client Credentials end - Note over C: Generate PKCE Parameters + Note over C: Generate PKCE parameters C->>B: Open browser with authorization URL + code_challenge - B->>M: Authorization Request - Note over M: User /authorizes - M->>B: Redirect to callback with authorization code + B->>A: Authorization request + Note over A: User authorizes + A->>B: Redirect to callback with authorization code B->>C: Authorization code callback - C->>M: Token Request + code_verifier - M->>C: Access Token (+ Refresh Token) - C->>M: API Requests with Access Token + C->>A: Token request + code_verifier + A->>C: Access token (+ refresh token) + C->>M: MCP request with access token + M-->>C: MCP response ``` -#### 2.5.1 Decision Flow Overview - -```mermaid -flowchart TD - A[Start Auth Flow] --> B{Check Metadata Discovery} - B -->|Available| C[Use Metadata Endpoints] - B -->|Not Available| D[Use Default Endpoints] - - C --> G{Check Registration Endpoint} - D --> G - - G -->|Available| H[Perform Dynamic Registration] - G -->|Not Available| I[Alternative Registration Required] +### 2.7 Access Token Usage - H --> J[Start OAuth Flow] - I --> J - - J --> K[Generate PKCE Parameters] - K --> L[Request Authorization] - L --> M[User Authorization] - M --> N[Exchange Code for Tokens] - N --> O[Use Access Token] -``` - -### 2.6 Access Token Usage - -#### 2.6.1 Token Requirements +#### 2.7.1 Token Requirements Access token handling **MUST** conform to [OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5) @@ -285,7 +227,7 @@ Host: mcp.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIs... ``` -#### 2.6.2 Token Handling +#### 2.7.2 Token Handling Resource servers **MUST** validate access tokens as described in [Section 5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.2). @@ -294,7 +236,14 @@ If validation fails, servers **MUST** respond according to error handling requirements. Invalid or expired tokens **MUST** receive a HTTP 401 response. -### 2.7 Security Considerations +MCP clients **MUST NOT** send tokens to the MCP server other than ones issued by the MCP server's authorization server. + +MCP authorization servers **MUST** only accept tokens that are valid for use with their +own resources. + +MCP servers **MUST NOT** accept or transit any other tokens. + +### 2.8 Security Considerations The following security requirements **MUST** be implemented: @@ -304,7 +253,7 @@ The following security requirements **MUST** be implemented: 4. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities 5. Redirect URIs **MUST** be either localhost URLs or HTTPS URLs -### 2.8 Error Handling +### 2.9 Error Handling Servers **MUST** return appropriate HTTP status codes for authorization errors: @@ -314,73 +263,13 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors: | 403 | Forbidden | Invalid scopes or insufficient permissions | | 400 | Bad Request | Malformed authorization request | -### 2.9 Implementation Requirements +### 2.10 Implementation Requirements 1. Implementations **MUST** follow OAuth 2.1 security best practices -2. PKCE is **REQUIRED** for all clients -3. Token rotation **SHOULD** be implemented for enhanced security -4. Token lifetimes **SHOULD** be limited based on security requirements - -### 2.10 Third-Party Authorization Flow - -#### 2.10.1 Overview - -MCP servers **MAY** support delegated authorization through third-party authorization -servers. In this flow, the MCP server acts as both an OAuth client (to the third-party -auth server) and an OAuth authorization server (to the MCP client). - -#### 2.10.2 Flow Description - -The third-party authorization flow comprises these steps: - -1. MCP client initiates standard OAuth flow with MCP server -2. MCP server redirects user to third-party authorization server -3. User authorizes with third-party server -4. Third-party server redirects back to MCP server with authorization code -5. MCP server exchanges code for third-party access token -6. MCP server generates its own access token bound to the third-party session -7. MCP server completes original OAuth flow with MCP client - -```mermaid -sequenceDiagram - participant B as User-Agent (Browser) - participant C as MCP Client - participant M as MCP Server - participant T as Third-Party Auth Server - - C->>M: Initial OAuth Request - M->>B: Redirect to Third-Party /authorize - B->>T: Authorization Request - Note over T: User authorizes - T->>B: Redirect to MCP Server callback - B->>M: Authorization code - M->>T: Exchange code for token - T->>M: Third-party access token - Note over M: Generate bound MCP token - M->>B: Redirect to MCP Client callback - B->>C: MCP authorization code - C->>M: Exchange code for token - M->>C: MCP access token -``` - -#### 2.10.3 Session Binding Requirements - -MCP servers implementing third-party authorization **MUST**: - -1. Maintain secure mapping between third-party tokens and issued MCP tokens -2. Validate third-party token status before honoring MCP tokens -3. Implement appropriate token lifecycle management -4. Handle third-party token expiration and renewal - -#### 2.10.4 Security Considerations - -When implementing third-party authorization, servers **MUST**: - -1. Validate all redirect URIs -2. Securely store third-party credentials -3. Implement appropriate session timeout handling -4. Consider security implications of token chaining -5. Implement proper error handling for third-party auth failures +1. PKCE is **REQUIRED** for all MCP clients and authorization servers +1. MCP servers that also act as an AS: + 1. **SHOULD** implement token rotation for enhanced security + 1. **SHOULD** restrict token lifetimes based on security requirements ## 3. Best Practices