From 246792ca0efb9d91b06677b1ff1bb013d0945a8c Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 11:52:44 -0700 Subject: [PATCH 01/98] Initial commit with spec proposal --- .../2025-03-26/basic/authorization.md | 525 ++++++++---------- 1 file changed, 236 insertions(+), 289 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 72b3d6f12..b8eae22fc 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -4,7 +4,7 @@ type: docs weight: 15 --- -{{< callout type="info" >}} **Protocol Revision**: 2025-03-26 {{< /callout >}} +{{< callout type="info" >}} **Protocol Revision**: TBD {{< /callout >}} ## 1. Introduction @@ -14,375 +14,325 @@ The Model Context Protocol provides authorization capabilities at the transport enabling MCP clients to make requests to restricted MCP servers on behalf of resource owners. This specification defines the authorization flow for HTTP-based transports. -### 1.2 Protocol Requirements +The scope of this document is **user authorization** - how a client can authenticate a +user to access a server and the server determine whether to authorize the user to +access its tools, resources, or any other capabilities. + +This document **does not discuss server-to-server authorization patterns**. + +### 1.2 Baseline tenets + +1. **MCP server developers are not security experts – do not make them do that work**. + The current specification assumes that developers will be building their own + authorization server. That is not something they ever need to do in the context of + MCP servers. This also introduces room for serious mistakes that can lead to compromise. +1. **MCP clients are identity provider (IdP)-agnostic**. We do not and will not expect + clients to be "enlightened" in any capacity to support a protected MCP server. This will + fragment the ecosystem. The specification explicitly assumes that clients are not enabled + in any unique way to support specific IdPs. + - **Note:** It is acceptable for clients to be enhanced for specific IdPs, primarily through + pre-registration. +1. **MCP clients perform user authentication without the server.** The MCP server can guide the + client to the IdP but will not be responsible for authenticating the user and obtaining credential + artifacts for the user. The server might transform incoming credential artifacts, like tokens, but + it does not do any kind of exchange for the user in the client, nor does the MCP server have access + to any user authentication credentials or protocols. +1. **We focus on OAuth 2.1, with room for extensibility for other providers/specifications.** Our running + assumption is that most developers will want to use OAuth 2.1, however in the long-run unusual cases + for authentication and authorization may emerge (e.g., mTLS, Kerberos), which will need clients to be + extensible. + +### 1.3 Protocol Requirements Authorization is **OPTIONAL** for MCP implementations. When supported: -- Implementations using an HTTP-based transport **SHOULD** conform to this specification. -- Implementations using an STDIO transport **SHOULD NOT** follow this specification, and - instead retrieve credentials from the environment. -- Implementations using alternative transports **MUST** follow established security best - practices for their protocol. +- Streamable HTTP or SSE transports **SHOULD** conform to this specification. +- Implementations using an STDIO transport **SHOULD NOT** follow this specification and instead retrieve + credentials from the environment. +- Implementations using alternative transports **MUST** follow established security best practices for their + protocol. -### 1.3 Standards Compliance +### 1.4 Standards Compliance -This authorization mechanism is based on established specifications listed below, but -implements a selected subset of their features to ensure security and interoperability -while maintaining simplicity: +This authorization mechanism is based on established specifications listed below, but 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.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.1 IETF DRAFT](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 Demonstrating Proof of Possession (DPoP) ([RFC9449](https://datatracker.ietf.org/doc/html/rfc9449)) +- Resource Indicators for OAuth 2.0 ([RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html)) + +This specification **DOES NOT** require MCP server developers to implement their own OAuth Provider (OP) and instead +relies on developers adopting dedicated and well-tested third-party Identity Providers (IdPs). ## 2. Authorization Flow ### 2.1 Overview -1. MCP auth implementations **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 - Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). +1. Identity providers **MUST** implement OAuth 2.1 with appropriate security measures for both confidential + and public clients. -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. +2. Identity providers **SHOULD** support the OAuth 2.1 Dynamic Client Registration Protocol + ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). -### 2.1.1 OAuth Grant Types +3. Identity providers **SHOULD** implement and MCP clients **MUST** consume 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. -OAuth specifies different flows or grant types, which are different ways of obtaining an -access token. Each of these targets different use cases and scenarios. +### 2.2 Basic OAuth 2.1 Authorization -MCP servers **SHOULD** support the OAuth grant types that best align with the intended -audience. For instance: +When authorization is required and not yet proven by the client, servers **MUST** respond with *HTTP 401 Unauthorized*. -1. Authorization Code: useful when the client is acting on behalf of a (human) end user. - - For instance, an agent calls an MCP tool implemented by a SaaS system. -2. Client Credentials: the client is another application (not a human) - - For instance, an agent calls a secure MCP tool to check inventory at a specific - store. No need to impersonate the end user. +A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with information about the issuer that the +server is using to authenticate in the following format: -### 2.2 Example: authorization code grant +`WWW-Authenticate: Bearer realm="default", issuer="https://idp.example",` +`scope="mcp_access_tool1", resource="https://mcp-server.example"` +`WWW-Authenticate: DPoP realm="default", issuer="https://idp.example",` +`scope="mcp_access_tool1", resource="https://mcp-server.example",` +`algs="ES256 PS256"` -This demonstrates the OAuth 2.1 flow for the authorization code grant type, used for user -auth. +An MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of issuers discovered this way +(to prevent phishing). For example, an MCP client could prompt the user "Do you want to login with `https://idp.example`?" -**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 **MUST** use the `issuer` identifier to construct the OAuth 2.0 metadata discovery document path, following +[RFC8414](https://datatracker.ietf.org/doc/html/rfc8414#section-3). -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. +An MCP client may use the `registration_endpoint` to register itself with OAuth Provider. An MCP client may also be +pre-registered with certain OAuth Providers. -When authorization is required and not yet proven by the client, servers **MUST** respond -with _HTTP 401 Unauthorized_. +An MCP client **MUST** check the `resource` identifier against the hostname of the MCP server. An MCP client **MUST** send +the `resource` identifier to the OAuth Provider, following [RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html). -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_. +An MCP client **MUST** implement Demonstrating Proof of Possession (DPoP) and use it to the extent supported by the OAuth +Provider. See [RFC9449](https://datatracker.ietf.org/doc/html/rfc9449). -The following demonstrates the basic OAuth 2.1 for public clients using PKCE. +Clients initiate the [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization +flow after receiving the *HTTP 401 Unauthorized*. -```mermaid -sequenceDiagram - participant B as User-Agent (Browser) - participant C as Client - participant M as MCP Server +The following demonstrates the OAuth 2.1 flow for public clients using PKCE. - 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 -``` + ### 2.3 Server Metadata Discovery +Servers **MUST** return the issuer identifier in `WWW-Authenticate` headers in a *HTTP 401 Unauthorized* response. + +For servers that are overriding identity provider capabilities, such as those for token exchange or dynamic client registration, +they **MUST** return their fully-qualified domain as the issuer in `WWW-Authenticate` headers in a *HTTP 401 Unauthorized* +response. + For server capability 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. - -The discovery flow is illustrated below: - -```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 -``` +- MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct the metadata endpoint + from that issuer identifier. +- MCP servers **MUST** use an established identity provider and include its issuer in *HTTP 401 Unauthorized* responses. +- MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity providers. +- MCP servers with partial support for other identity providers or that implement their own authentication and authorization + logic **SHOULD** follow the OAuth 2.0 Authorization Server Metadata protocol. +- MCP servers **MUST** respond with a `WWW-Authenticate` header with `issuer`, `scope`, and `resource` identifiers. + +The discovery flow is illustrated below: + + #### 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. +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. For example: `MCP-Protocol-Version: 2024-11-05` -#### 2.3.2 Authorization Base URL +### 2.4 Identity provider integration -The authorization base URL **MUST** be determined from the MCP server URL by discarding -any existing `path` component. For example: +#### 2.4.1 Overview -If the MCP server URL is `https://api.example.com/v1/mcp`, then: +MCP servers **SHOULD** support delegated authorization through third-party authorization servers instead of implementing their own +OAuth provider. In this flow, the MCP server acts as the proxy for the identity provider. -- The authorization base URL is `https://api.example.com` -- The metadata endpoint **MUST** be at - `https://api.example.com/.well-known/oauth-authorization-server` +MCP servers **MAY** override endpoints on an as-needed basis if the identity provider requires additional gestures that are not +captured by the specification. -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. +MCP servers **MUST NOT** complete PKCE or other public client flows on behalf of the client. -#### 2.3.3 Fallbacks for Servers without Metadata Discovery +MCP servers that do not implement a [metadata discovery process](#23-server-metadata-discovery) must be assumed to implement the +OAuth flow through standard endpoints (e.g., `/authorize` and `/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)): +#### 2.4.2 Flow Description -| 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 | +The third-party authorization flow comprises these steps: -For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default -endpoints would be: +1. MCP client requests data from the MCP server. +1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the `issuer`, `scope`, and `resource`. +1. MCP client constructs the `/authorize` endpoint from the `issuer` identifier. +1. MCP client redirects user to identity provider's `/authorize` endpoint. MCP client uses `scope` and `resource` parameters + provided in the `WWW-Authenticate` header in the `/authorize` URL. +1. User authorizes with identity provider with `scope` and `resource`. +1. Identity provider redirects back to MCP client with authorization code. +1. MCP client exchanges the code for the requested tokens. +1. MCP client caches the token. +1. MCP clients can now request data from the MCP server with the token attached in the `Authorization` header. -- `https://api.example.com/authorize` -- `https://api.example.com/token` -- `https://api.example.com/register` + + +#### 2.4.3 Session Binding Requirements -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. +MCP servers implementing third-party authorization **MUST**: -### 2.4 Dynamic Client Registration +1. Maintain secure mapping between third-party tokens and issued client sessions. +2. Validate third-party token status before honoring MCP tokens. +3. Implement appropriate token lifecycle management. +4. Provide appropriate responses to the client if re-authentication is needed. -MCP clients and 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 -for MCP because: +#### 2.4.4 Security Considerations -- 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 +When implementing authorization with identity providers, MCP servers **MUST**: + +1. Request the minimum number of required scopes. +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. -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: +MCP clients **MUST**: -1. Hardcode a client ID (and, if applicable, client secret) 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). +1. Securely store authentication tokens received from the identity provider. +2. Properly handle request to re-authenticate users with expired or invalid tokens. +3. Verify that the resource identifier returned matches the FQDN of the MCP server. +4. Forward the resource identifier returns as `resource` parameter according to + [RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html). -### 2.5 Authorization Flow Steps +Identity providers **MUST**: -The complete Authorization flow proceeds as follows: +1. Verify that the resource identifier is registered for the audience of the access token issued. -```mermaid -sequenceDiagram - participant B as User-Agent (Browser) - participant C as Client - participant M as MCP Server +### 2.5 Implementing server overrides - 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 +In certain scenarios, identity providers might have limited capability support and MCP server developers may choose to supplement those +with their own implementation. In this scenario, the server **MUST** return its fully-qualified domain name as the `issuer` in the +*HTTP 401 Unauthorized* response, included in the `WWW-Authenticate` header. - alt Dynamic Client Registration - C->>M: POST /register - M->>C: Client Credentials - end +#### 2.5.1 Discovery of server-driven overrides - 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->>C: Authorization code callback - C->>M: Token Request + code_verifier - M->>C: Access Token (+ Refresh Token) - C->>M: API Requests with Access Token -``` +Under all circumstances, the server **MUST** return a `WWW-Authenticate` with `issuer` information, even if the server provides its +own metadata document that overrides IdP endpoints (such as `/authorize`, `/token`, or `/register`). -#### 2.5.1 Decision Flow Overview +#### 2.5.2 Fallbacks for Servers without Metadata Discovery -```mermaid -flowchart TD - A[Start Auth Flow] --> B{Check Metadata Discovery} - B -->|Available| C[Use Metadata Endpoints] - B -->|Not Available| D[Use Default Endpoints] +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.5.1](#251-discovery-of-server-driven-overrides): - C --> G{Check Registration Endpoint} - D --> G +| 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 | - G -->|Available| H[Perform Dynamic Registration] - G -->|Not Available| I[Alternative Registration Required] +For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default endpoints would be: - H --> J[Start OAuth Flow] - I --> J +- `https://api.example.com/authorize` +- `https://api.example.com/token` +- `https://api.example.com/register` - J --> K[Generate PKCE Parameters] - K --> L[Request Authorization] - L --> M[User Authorization] - M --> N[Exchange Code for Tokens] - N --> O[Use Access Token] -``` +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. -### 2.6 Access Token Usage +### 2.6 Dynamic Client Registration -#### 2.6.1 Token Requirements +MCP clients and 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 for MCP because: -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) -requirements for resource requests. Specifically: +- 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 -1. MCP client **MUST** use the Authorization request header field - [Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): +MCP clients that want to dynamically register OAuth clients with the target identity provider **MUST** provide the `software_id` and `software_version` +parameters, as defined in the [Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) section of +[RFC7591](https://datatracker.ietf.org/doc/html/rfc7591). -``` -Authorization: Bearer -``` +MCP clients with mass audiences will *generally* want to pre-register and hardcode client IDs. Some OAuth Providers (such as Google and Microsoft) +limit the functionality of dynamically registered clients. An MCP client could contain a config for common issuers like: -Note that authorization **MUST** be included in every HTTP request from client to server, -even if they are part of the same logical session. +`[` + `{ "issuer":"https://idp.example", "client_id":"12345"},` + `{ "issuer":"https://idp2.example", "client_id":"urn:client_ids:546"}` +`]` -2. Access tokens **MUST NOT** be included in the URI query string +Alternatively, an MCP client could allow the user to register the MCP client and provide those details to the MCP client through a UI. -Example request: +### 2.7 Authorization Flow Steps -```http -GET /v1/contexts HTTP/1.1 -Host: mcp.example.com -Authorization: Bearer eyJhbGciOiJIUzI1NiIs... -``` +The complete Authorization flow proceeds as follows: -#### 2.6.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). -If validation fails, servers **MUST** respond according to -[Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3) -error handling requirements. Invalid or expired tokens **MUST** receive a HTTP 401 -response. +#### 2.7.1 Decision Flow Overview -### 2.7 Security Considerations + -The following security requirements **MUST** be implemented: +### 2.8 Access Token Usage -1. Clients **MUST** securely store tokens following OAuth 2.0 best practices -2. Servers **SHOULD** enforce token expiration and rotation -3. All authorization endpoints **MUST** be served over HTTPS -4. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities -5. Redirect URIs **MUST** be either localhost URLs or HTTPS URLs +#### 2.8.1 Token Requirements -### 2.8 Error Handling +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) +or [DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) requirements for resource requests. Specifically: -Servers **MUST** return appropriate HTTP status codes for authorization errors: +MCP client **MUST** use the Authorization request header field +[OAuth Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): -| Status Code | Description | Usage | -| ----------- | ------------ | ------------------------------------------ | -| 401 | Unauthorized | Authorization required or token invalid | -| 403 | Forbidden | Invalid scopes or insufficient permissions | -| 400 | Bad Request | Malformed authorization request | +`Authorization: Bearer ` -### 2.9 Implementation Requirements +or DPoP Section 7.1 -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 +`Authorization: DPoP ` +`DPoP: ` -### 2.10 Third-Party Authorization Flow +Note that authorization **MUST** be included in every HTTP request from client to server, even if they are part of the +same logical session. -#### 2.10.1 Overview +Access tokens **MUST NOT** be included in the URI query string. Example request: -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). +`GET /v1/contexts HTTP/1.1` +`Host: mcp.example.com` +`Authorization: Bearer eyJhbGciOiJIUzI1NiIs...` -#### 2.10.2 Flow Description +#### 2.8.2 Token Handling -The third-party authorization flow comprises these steps: +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). If validation fails, servers +**MUST** respond according to [Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3) +error handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` response. -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 +### 2.9 Security Considerations -MCP servers implementing third-party authorization **MUST**: +The following security requirements **MUST** be implemented: -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 +1. Clients **MUST** securely store tokens following OAuth 2.0 best practices. +1. Servers **SHOULD** enforce token expiration and rotation. +1. All authorization endpoints **MUST** be served over HTTPS. +1. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities. +1. Redirect URIs **MUST** be either localhost URLs or HTTPS URLs. +1. Special considerations **MUST** be accounted for to prevent phishing through MCP servers. + +### 2.10 Error Handling + +Servers **MUST** return appropriate HTTP status codes for authorization errors: -#### 2.10.4 Security Considerations +| Status Code | Description | Usage | +| ----- | ----- | ----- | +| 401 | Unauthorized | Authorization required or token invalid | +| 403 | Forbidden | Invalid scopes or insufficient permissions | +| 400 | Bad Request | Malformed authorization request | -When implementing third-party authorization, servers **MUST**: +### 2.11 Implementation Requirements -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. 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. ## 3. Best Practices @@ -390,21 +340,18 @@ When implementing third-party authorization, servers **MUST**: We strongly recommend that local clients implement OAuth 2.1 as a public client: -1. Utilizing code challenges (PKCE) for authorization requests to prevent interception - attacks -2. Implementing secure token storage appropriate for the local system -3. Following token refresh best practices to maintain sessions -4. Properly handling token expiration and renewal +1. Utilizing code challenges (PKCE) for authorization requests to prevent interception attacks. +2. Implementing secure token storage appropriate for the local system. +3. Following token refresh best practices to maintain sessions. +4. Properly handling token expiration and renewal. #### 3.2 Authorization Metadata Discovery -We strongly recommend that all clients implement metadata discovery. This reduces the -need for users to provide endpoints manually or clients to fallback to the defined -defaults. +We strongly recommend that all clients implement metadata discovery. This reduces the need for users +to provide endpoints manually or clients to fallback to the defined defaults. #### 3.3 Dynamic Client Registration -Since clients do not know the set of MCP servers in advance, we strongly recommend the -implementation of dynamic client registration. This allows applications to automatically -register with the MCP server, and removes the need for users to obtain client ids -manually. +Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation +of dynamic client registration. This allows applications to automatically register with the MCP server, +and removes the need for users to obtain client IDs manually. From bc2e1dcdaf9f6bb95264699f24bcc2b28291a39f Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 11:58:59 -0700 Subject: [PATCH 02/98] Formatting updates (100 char per line) --- .../2025-03-26/basic/authorization.md | 238 ++++++++++-------- 1 file changed, 134 insertions(+), 104 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index b8eae22fc..66057b709 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -10,82 +10,88 @@ weight: 15 ### 1.1 Purpose and Scope -The Model Context Protocol provides authorization capabilities at the transport level, -enabling MCP clients to make requests to restricted MCP servers on behalf of resource -owners. This specification defines the authorization flow for HTTP-based transports. +The Model Context Protocol provides authorization capabilities at the transport level, enabling MCP +clients to make requests to restricted MCP servers on behalf of resource owners. This specification +defines the authorization flow for HTTP-based transports. -The scope of this document is **user authorization** - how a client can authenticate a -user to access a server and the server determine whether to authorize the user to -access its tools, resources, or any other capabilities. +The scope of this document is **user authorization** - how a client can authenticate a user to access a +server and the server determine whether to authorize the user to access its tools, resources, or any +other capabilities. This document **does not discuss server-to-server authorization patterns**. ### 1.2 Baseline tenets -1. **MCP server developers are not security experts – do not make them do that work**. - The current specification assumes that developers will be building their own - authorization server. That is not something they ever need to do in the context of - MCP servers. This also introduces room for serious mistakes that can lead to compromise. -1. **MCP clients are identity provider (IdP)-agnostic**. We do not and will not expect - clients to be "enlightened" in any capacity to support a protected MCP server. This will - fragment the ecosystem. The specification explicitly assumes that clients are not enabled - in any unique way to support specific IdPs. - - **Note:** It is acceptable for clients to be enhanced for specific IdPs, primarily through +1. **MCP server developers are not security experts – do not make them do that work**. The current + specification assumes that developers will be building their own authorization server. That is not + something they ever need to do in the context of MCP servers. This also introduces room for serious + mistakes that can lead to compromise. +1. **MCP clients are identity provider (IdP)-agnostic**. We do not and will not expect clients to be + "enlightened" in any capacity to support a protected MCP server. This will fragment the ecosystem. + The specification explicitly assumes that clients are not enabled in any unique way to support + specific IdPs. + - **Note:** It is acceptable for clients to be enhanced for specific IdPs, primarily through pre-registration. -1. **MCP clients perform user authentication without the server.** The MCP server can guide the - client to the IdP but will not be responsible for authenticating the user and obtaining credential - artifacts for the user. The server might transform incoming credential artifacts, like tokens, but - it does not do any kind of exchange for the user in the client, nor does the MCP server have access +1. **MCP clients perform user authentication without the server.** The MCP server can guide the client + to the IdP but will not be responsible for authenticating the user and obtaining credential + artifacts for the user. The server might transform incoming credential artifacts, like tokens, but + it does not do any kind of exchange for the user in the client, nor does the MCP server have access to any user authentication credentials or protocols. -1. **We focus on OAuth 2.1, with room for extensibility for other providers/specifications.** Our running - assumption is that most developers will want to use OAuth 2.1, however in the long-run unusual cases - for authentication and authorization may emerge (e.g., mTLS, Kerberos), which will need clients to be - extensible. +1. **We focus on OAuth 2.1, with room for extensibility for other providers/specifications.** Our + running assumption is that most developers will want to use OAuth 2.1, however in the long-run + unusual cases for authentication and authorization may emerge (e.g., mTLS, Kerberos), which will + need clients to be extensible. ### 1.3 Protocol Requirements Authorization is **OPTIONAL** for MCP implementations. When supported: - Streamable HTTP or SSE transports **SHOULD** conform to this specification. -- Implementations using an STDIO transport **SHOULD NOT** follow this specification and instead retrieve - credentials from the environment. -- Implementations using alternative transports **MUST** follow established security best practices for their - protocol. +- Implementations using an STDIO transport **SHOULD NOT** follow this specification and instead + retrieve credentials from the environment. +- Implementations using alternative transports **MUST** follow established security best practices for + their protocol. ### 1.4 Standards Compliance -This authorization mechanism is based on established specifications listed below, but implements a selected -subset of their features to ensure security and interoperability while maintaining simplicity: +This authorization mechanism is based on established specifications listed below, but 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.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 Demonstrating Proof of Possession (DPoP) ([RFC9449](https://datatracker.ietf.org/doc/html/rfc9449)) -- Resource Indicators for OAuth 2.0 ([RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html)) - -This specification **DOES NOT** require MCP server developers to implement their own OAuth Provider (OP) and instead -relies on developers adopting dedicated and well-tested third-party Identity Providers (IdPs). +- 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 Demonstrating Proof of Possession (DPoP) + ([RFC9449](https://datatracker.ietf.org/doc/html/rfc9449)) +- Resource Indicators for OAuth 2.0 + ([RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html)) + +This specification **DOES NOT** require MCP server developers to implement their own OAuth Provider +(OP) and instead relies on developers adopting dedicated and well-tested third-party Identity +Providers (IdPs). ## 2. Authorization Flow ### 2.1 Overview -1. Identity providers **MUST** implement OAuth 2.1 with appropriate security measures for both confidential - and public clients. +1. Identity providers **MUST** implement OAuth 2.1 with appropriate security measures for both + confidential and public clients. 2. Identity providers **SHOULD** support the OAuth 2.1 Dynamic Client Registration Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). -3. Identity providers **SHOULD** implement and MCP clients **MUST** consume 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. +3. Identity providers **SHOULD** implement and MCP clients **MUST** consume 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. ### 2.2 Basic OAuth 2.1 Authorization -When authorization is required and not yet proven by the client, servers **MUST** respond with *HTTP 401 Unauthorized*. +When authorization is required and not yet proven by the client, servers **MUST** respond with +*HTTP 401 Unauthorized*. -A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with information about the issuer that the -server is using to authenticate in the following format: +A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with information about +the issuer that the server is using to authenticate in the following format: `WWW-Authenticate: Bearer realm="default", issuer="https://idp.example",` `scope="mcp_access_tool1", resource="https://mcp-server.example"` @@ -93,22 +99,27 @@ server is using to authenticate in the following format: `scope="mcp_access_tool1", resource="https://mcp-server.example",` `algs="ES256 PS256"` -An MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of issuers discovered this way -(to prevent phishing). For example, an MCP client could prompt the user "Do you want to login with `https://idp.example`?" +An MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of issuers +discovered this way (to prevent phishing). For example, an MCP client could prompt the user "Do you +want to login with `https://idp.example`?" -An MCP client **MUST** use the `issuer` identifier to construct the OAuth 2.0 metadata discovery document path, following +An MCP client **MUST** use the `issuer` identifier to construct the OAuth 2.0 metadata discovery +document path, following [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414#section-3). -An MCP client may use the `registration_endpoint` to register itself with OAuth Provider. An MCP client may also be -pre-registered with certain OAuth Providers. +An MCP client may use the `registration_endpoint` to register itself with OAuth Provider. An MCP +client may also be pre-registered with certain OAuth Providers. -An MCP client **MUST** check the `resource` identifier against the hostname of the MCP server. An MCP client **MUST** send -the `resource` identifier to the OAuth Provider, following [RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html). +An MCP client **MUST** check the `resource` identifier against the hostname of the MCP server. An MCP +client **MUST** send the `resource` identifier to the OAuth Provider, following +[RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html). -An MCP client **MUST** implement Demonstrating Proof of Possession (DPoP) and use it to the extent supported by the OAuth -Provider. See [RFC9449](https://datatracker.ietf.org/doc/html/rfc9449). +An MCP client **MUST** implement Demonstrating Proof of Possession (DPoP) and use it to the extent +supported by the OAuth Provider. See +[RFC9449](https://datatracker.ietf.org/doc/html/rfc9449). -Clients initiate the [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization +Clients initiate the +[OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization flow after receiving the *HTTP 401 Unauthorized*. The following demonstrates the OAuth 2.1 flow for public clients using PKCE. @@ -117,21 +128,26 @@ The following demonstrates the OAuth 2.1 flow for public clients using PKCE. ### 2.3 Server Metadata Discovery -Servers **MUST** return the issuer identifier in `WWW-Authenticate` headers in a *HTTP 401 Unauthorized* response. +Servers **MUST** return the issuer identifier in `WWW-Authenticate` headers in a +*HTTP 401 Unauthorized* response. -For servers that are overriding identity provider capabilities, such as those for token exchange or dynamic client registration, -they **MUST** return their fully-qualified domain as the issuer in `WWW-Authenticate` headers in a *HTTP 401 Unauthorized* -response. +For servers that are overriding identity provider capabilities, such as those for token exchange or +dynamic client registration, they **MUST** return their fully-qualified domain as the issuer in +`WWW-Authenticate` headers in a *HTTP 401 Unauthorized* response. For server capability discovery: -- MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct the metadata endpoint - from that issuer identifier. -- MCP servers **MUST** use an established identity provider and include its issuer in *HTTP 401 Unauthorized* responses. -- MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity providers. -- MCP servers with partial support for other identity providers or that implement their own authentication and authorization - logic **SHOULD** follow the OAuth 2.0 Authorization Server Metadata protocol. -- MCP servers **MUST** respond with a `WWW-Authenticate` header with `issuer`, `scope`, and `resource` identifiers. +- MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct + the metadata endpoint from that issuer identifier. +- MCP servers **MUST** use an established identity provider and include its issuer in + *HTTP 401 Unauthorized* responses. +- MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity + providers. +- MCP servers with partial support for other identity providers or that implement their own + authentication and authorization logic **SHOULD** follow the OAuth 2.0 Authorization Server Metadata + protocol. +- MCP servers **MUST** respond with a `WWW-Authenticate` header with `issuer`, `scope`, and `resource` + identifiers. The discovery flow is illustrated below: @@ -139,8 +155,8 @@ The discovery flow is illustrated below: #### 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. +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. For example: `MCP-Protocol-Version: 2024-11-05` @@ -148,31 +164,34 @@ For example: `MCP-Protocol-Version: 2024-11-05` #### 2.4.1 Overview -MCP servers **SHOULD** support delegated authorization through third-party authorization servers instead of implementing their own -OAuth provider. In this flow, the MCP server acts as the proxy for the identity provider. +MCP servers **SHOULD** support delegated authorization through third-party authorization servers +instead of implementing their own OAuth provider. In this flow, the MCP server acts as the proxy for +the identity provider. -MCP servers **MAY** override endpoints on an as-needed basis if the identity provider requires additional gestures that are not -captured by the specification. +MCP servers **MAY** override endpoints on an as-needed basis if the identity provider requires +additional gestures that are not captured by the specification. MCP servers **MUST NOT** complete PKCE or other public client flows on behalf of the client. -MCP servers that do not implement a [metadata discovery process](#23-server-metadata-discovery) must be assumed to implement the -OAuth flow through standard endpoints (e.g., `/authorize` and `/token`) +MCP servers that do not implement a [metadata discovery process](#23-server-metadata-discovery) must +be assumed to implement the OAuth flow through standard endpoints (e.g., `/authorize` and `/token`) #### 2.4.2 Flow Description The third-party authorization flow comprises these steps: 1. MCP client requests data from the MCP server. -1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the `issuer`, `scope`, and `resource`. +1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the + `issuer`, `scope`, and `resource`. 1. MCP client constructs the `/authorize` endpoint from the `issuer` identifier. -1. MCP client redirects user to identity provider's `/authorize` endpoint. MCP client uses `scope` and `resource` parameters - provided in the `WWW-Authenticate` header in the `/authorize` URL. +1. MCP client redirects user to identity provider's `/authorize` endpoint. MCP client uses `scope` and + `resource` parameters provided in the `WWW-Authenticate` header in the `/authorize` URL. 1. User authorizes with identity provider with `scope` and `resource`. 1. Identity provider redirects back to MCP client with authorization code. 1. MCP client exchanges the code for the requested tokens. 1. MCP client caches the token. -1. MCP clients can now request data from the MCP server with the token attached in the `Authorization` header. +1. MCP clients can now request data from the MCP server with the token attached in the `Authorization` + header. @@ -209,19 +228,22 @@ Identity providers **MUST**: ### 2.5 Implementing server overrides -In certain scenarios, identity providers might have limited capability support and MCP server developers may choose to supplement those -with their own implementation. In this scenario, the server **MUST** return its fully-qualified domain name as the `issuer` in the -*HTTP 401 Unauthorized* response, included in the `WWW-Authenticate` header. +In certain scenarios, identity providers might have limited capability support and MCP server +developers may choose to supplement those with their own implementation. In this scenario, the server +**MUST** return its fully-qualified domain name as the `issuer` in the *HTTP 401 Unauthorized* +response, included in the `WWW-Authenticate` header. #### 2.5.1 Discovery of server-driven overrides -Under all circumstances, the server **MUST** return a `WWW-Authenticate` with `issuer` information, even if the server provides its -own metadata document that overrides IdP endpoints (such as `/authorize`, `/token`, or `/register`). +Under all circumstances, the server **MUST** return a `WWW-Authenticate` with `issuer` information, +even if the server provides its own metadata document that overrides IdP endpoints (such as +`/authorize`, `/token`, or `/register`). #### 2.5.2 Fallbacks for Servers without Metadata Discovery -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.5.1](#251-discovery-of-server-driven-overrides): +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.5.1](#251-discovery-of-server-driven-overrides): | Endpoint | Default Path | Description | | ----- | ----- | ----- | @@ -229,39 +251,44 @@ relative to the authorization base URL (as defined in [Section 2.5.1](#251-disco | Token Endpoint | `/token` | Used for token exchange & refresh | | Registration Endpoint | `/register` | Used for dynamic client registration | -For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default endpoints would be: +For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default endpoints +would be: - `https://api.example.com/authorize` - `https://api.example.com/token` - `https://api.example.com/register` -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. +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. ### 2.6 Dynamic Client Registration -MCP clients and 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 for MCP because: +MCP clients and 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 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 -MCP clients that want to dynamically register OAuth clients with the target identity provider **MUST** provide the `software_id` and `software_version` -parameters, as defined in the [Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) section of +MCP clients that want to dynamically register OAuth clients with the target identity provider **MUST** +provide the `software_id` and `software_version` parameters, as defined in the +[Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) section of [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591). -MCP clients with mass audiences will *generally* want to pre-register and hardcode client IDs. Some OAuth Providers (such as Google and Microsoft) -limit the functionality of dynamically registered clients. An MCP client could contain a config for common issuers like: +MCP clients with mass audiences will *generally* want to pre-register and hardcode client IDs. Some +OAuth Providers (such as Google and Microsoft) limit the functionality of dynamically registered +clients. An MCP client could contain a config for common issuers like: `[` `{ "issuer":"https://idp.example", "client_id":"12345"},` `{ "issuer":"https://idp2.example", "client_id":"urn:client_ids:546"}` `]` -Alternatively, an MCP client could allow the user to register the MCP client and provide those details to the MCP client through a UI. +Alternatively, an MCP client could allow the user to register the MCP client and provide those details +to the MCP client through a UI. ### 2.7 Authorization Flow Steps @@ -277,8 +304,10 @@ The complete Authorization flow proceeds as follows: #### 2.8.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) -or [DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) requirements for resource requests. Specifically: +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) or +[DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) requirements for resource +requests. Specifically: MCP client **MUST** use the Authorization request header field [OAuth Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): @@ -290,8 +319,8 @@ or DPoP Section 7.1 `Authorization: DPoP ` `DPoP: ` -Note that authorization **MUST** be included in every HTTP request from client to server, even if they are part of the -same logical session. +Note that authorization **MUST** be included in every HTTP request from client to server, even if they +are part of the same logical session. Access tokens **MUST NOT** be included in the URI query string. Example request: @@ -302,9 +331,10 @@ Access tokens **MUST NOT** be included in the URI query string. Example request: #### 2.8.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). If validation fails, servers -**MUST** respond according to [Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3) -error handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` response. +[Section 5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.2). If +validation fails, servers **MUST** respond according to +[Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3) error +handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` response. ### 2.9 Security Considerations @@ -353,5 +383,5 @@ to provide endpoints manually or clients to fallback to the defined defaults. #### 3.3 Dynamic Client Registration Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation -of dynamic client registration. This allows applications to automatically register with the MCP server, -and removes the need for users to obtain client IDs manually. +of dynamic client registration. This allows applications to automatically register with the MCP +server, and removes the need for users to obtain client IDs manually. \ No newline at end of file From 6f20cffbde9c8231349ea53b0f1dc8f484db9001 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 12:02:13 -0700 Subject: [PATCH 03/98] Add Mermaid charts and formatting changes --- .../2025-03-26/basic/authorization.md | 168 +++++++++++++++--- 1 file changed, 143 insertions(+), 25 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 66057b709..9612210c5 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -124,7 +124,25 @@ flow after receiving the *HTTP 401 Unauthorized*. The following demonstrates the OAuth 2.1 flow for public clients using PKCE. - +```mermaid +sequenceDiagram + participant UA as User-Agent (Browser or App/Broker) + participant MC as MCP Client + participant MS as MCP Server + participant IDP as Identity Provider + + MC->>MS: MCP Request + MS-->>MC: 401 Unauthorized with issuer, scope, and resource in WWW-Authenticate + MC->>MC: Construct OIDC /authorize endpoint from issuer identifier + Note over MC: Generate code_verifier and code_challenge,
and request with scope and resource + MC-->>UA: Open /authorize + Note over UA: User authenticates to the IDP + UA->>MC: Return auth code to client + MC->>IDP: Exchange auth code for tokens + IDP-->>MC: Return tokens + MC->>MC: Cache tokens + Note over MC, MS: Begin standard MCP message exchange +``` ### 2.3 Server Metadata Discovery @@ -151,7 +169,18 @@ For server capability discovery: The discovery flow is illustrated below: - +```mermaid +sequenceDiagram + participant MC as MCP Client + participant MS as MCP Server + participant IDP as Identity Provider + + MC->>MS: Request data + MS-->>MC: 401 Unauthorized with WWW-Authenticate + MC->>MC: Construct metadata endpoint from issuer identifier + + Note over MC: Continue with authorization flow +``` #### 2.3.1 Server Metadata Discovery Headers @@ -193,7 +222,23 @@ The third-party authorization flow comprises these steps: 1. MCP clients can now request data from the MCP server with the token attached in the `Authorization` header. - +```mermaid +sequenceDiagram + participant UA as User-Agent (Browser) + participant MC as MCP Client + participant MS as MCP Server + participant IDP as Third-Party Auth Server + + MC->>MS: Request data + MS-->>MC: 401 Unauthorized with WWW-Authenticate + MC->>MC: Construct metadata endpoint from issuer identifier + MC-->>UA: Initiate authentication at /authorize + Note over UA: User authorizes with scope and resource + UA->>MC: Return auth code to client + MC->>IDP: Exchange code for token + IDP-->>MC: Third-party access token + MC->>MC: Cache token +``` #### 2.4.3 Session Binding Requirements @@ -245,11 +290,11 @@ For servers that do not implement OAuth 2.0 Authorization Server Metadata, clien following default endpoint paths relative to the authorization base URL (as defined in [Section 2.5.1](#251-discovery-of-server-driven-overrides): -| 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 | +| 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 | For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default endpoints would be: @@ -282,10 +327,12 @@ MCP clients with mass audiences will *generally* want to pre-register and hardco OAuth Providers (such as Google and Microsoft) limit the functionality of dynamically registered clients. An MCP client could contain a config for common issuers like: -`[` - `{ "issuer":"https://idp.example", "client_id":"12345"},` - `{ "issuer":"https://idp2.example", "client_id":"urn:client_ids:546"}` -`]` +```json +[ + { "issuer":"https://idp.example", "client_id":"12345"}, + { "issuer":"https://idp2.example", "client_id":"urn:client_ids:546"} +] +``` Alternatively, an MCP client could allow the user to register the MCP client and provide those details to the MCP client through a UI. @@ -294,11 +341,76 @@ to the MCP client through a UI. The complete Authorization flow proceeds as follows: - +```mermaid +sequenceDiagram + participant UA as User-Agent (Browser or App/Broker) + participant MC as MCP Client + participant MS as MCP Server + participant IDP as Identity Provider + + MC->>MS: Request data + MS-->>MC: 401 Unauthorized with WWW-Authenticate + MC->>MC: Construct OIDC path + + alt Supports identity provider + MC->>IDP: GET /.well-known/oauth-authorization-server + IDP-->>MC: Return endpoint metadata + else Partial or No IDP Support + MC->>MS: GET /.well-known/oauth-authorization-server + alt Discovery Success + MS-->>MC: 200 OK + Metadata Document + Note over MC: Use endpoints from metadata + else Discovery Failed + MS-->>MC: 404 Not Found + Note over MC: Fall back to default endpoints + end + end + + alt Client is pre-registered for the identity provider + else Identity provider supports dynamic client registration + MC->>IDP: Request client registration + IDP-->>MC: Confirm client registration + else Identity provider does not support dynamic client registration + MC->>MS: Request client registration + MS->>IDP: Register client + IDP-->>MS: Return client registration + MS-->>MC: Return client registration + end + + Note over MC: Generate PKCE artifacts + MC-->>UA: Open /authorize + Note over UA: User enters their credentials + UA->>MC: Return auth code to client + MC->>IDP: Exchange auth code for tokens + IDP-->>MC: Return tokens + MC->>MC: Cache tokens + Note over MC, MS: Begin standard MCP message exchange +``` #### 2.7.1 Decision Flow Overview - +```mermaid +flowchart TD + A[Start Auth Flow] --> AA[Get authority] + AA-->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] + + 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.8 Access Token Usage @@ -312,21 +424,27 @@ requests. Specifically: MCP client **MUST** use the Authorization request header field [OAuth Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): -`Authorization: Bearer ` +``` +Authorization: Bearer +``` or DPoP Section 7.1 -`Authorization: DPoP ` -`DPoP: ` +``` +Authorization: DPoP +DPoP: +``` Note that authorization **MUST** be included in every HTTP request from client to server, even if they are part of the same logical session. Access tokens **MUST NOT** be included in the URI query string. Example request: -`GET /v1/contexts HTTP/1.1` -`Host: mcp.example.com` -`Authorization: Bearer eyJhbGciOiJIUzI1NiIs...` +``` +GET /v1/contexts HTTP/1.1 +Host: mcp.example.com +Authorization: Bearer eyJhbGciOiJIUzI1NiIs... +``` #### 2.8.2 Token Handling @@ -351,11 +469,11 @@ The following security requirements **MUST** be implemented: Servers **MUST** return appropriate HTTP status codes for authorization errors: -| Status Code | Description | Usage | -| ----- | ----- | ----- | -| 401 | Unauthorized | Authorization required or token invalid | -| 403 | Forbidden | Invalid scopes or insufficient permissions | -| 400 | Bad Request | Malformed authorization request | +| Status Code | Description | Usage | +| ----------- | ------------ | ------------------------------------------ | +| 401 | Unauthorized | Authorization required or token invalid | +| 403 | Forbidden | Invalid scopes or insufficient permissions | +| 400 | Bad Request | Malformed authorization request | ### 2.11 Implementation Requirements From 39dfba139406ccd31b975690edaecc2c08234e8a Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 14:01:26 -0700 Subject: [PATCH 04/98] Update authorization.md --- .../2025-03-26/basic/authorization.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 9612210c5..8fb610e13 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -114,7 +114,7 @@ An MCP client **MUST** check the `resource` identifier against the hostname of t client **MUST** send the `resource` identifier to the OAuth Provider, following [RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html). -An MCP client **MUST** implement Demonstrating Proof of Possession (DPoP) and use it to the extent +An MCP client **SHOULD** implement Demonstrating Proof of Possession (DPoP) and use it to the extent supported by the OAuth Provider. See [RFC9449](https://datatracker.ietf.org/doc/html/rfc9449). @@ -193,10 +193,6 @@ For example: `MCP-Protocol-Version: 2024-11-05` #### 2.4.1 Overview -MCP servers **SHOULD** support delegated authorization through third-party authorization servers -instead of implementing their own OAuth provider. In this flow, the MCP server acts as the proxy for -the identity provider. - MCP servers **MAY** override endpoints on an as-needed basis if the identity provider requires additional gestures that are not captured by the specification. @@ -428,7 +424,8 @@ MCP client **MUST** use the Authorization request header field Authorization: Bearer ``` -or DPoP Section 7.1 +or +[DPoP Section 7.1](https://datatracker.ietf.org/doc/html/rfc9449#name-the-dpop-authentication-sch): ``` Authorization: DPoP @@ -502,4 +499,10 @@ to provide endpoints manually or clients to fallback to the defined defaults. Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation of dynamic client registration. This allows applications to automatically register with the MCP -server, and removes the need for users to obtain client IDs manually. \ No newline at end of file +server, and removes the need for users to obtain client IDs manually. + +#### 3.4 Using delegated authorization + +MCP servers **SHOULD** support delegated authorization through third-party authorization servers +instead of implementing their own OAuth provider. MCP server **MAY** act as the proxy for +the identity provider. \ No newline at end of file From 97b0a62a65afa8cb34dc56aa8a06b471691c33b7 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:40:07 -0700 Subject: [PATCH 05/98] Formatting and comment updates --- .../2025-03-26/basic/authorization.md | 174 +++++++++--------- 1 file changed, 87 insertions(+), 87 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 8fb610e13..6f3101c14 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -10,36 +10,36 @@ weight: 15 ### 1.1 Purpose and Scope -The Model Context Protocol provides authorization capabilities at the transport level, enabling MCP -clients to make requests to restricted MCP servers on behalf of resource owners. This specification +The Model Context Protocol provides authorization capabilities at the transport level, enabling MCP +clients to make requests to restricted MCP servers on behalf of resource owners. This specification defines the authorization flow for HTTP-based transports. -The scope of this document is **user authorization** - how a client can authenticate a user to access a -server and the server determine whether to authorize the user to access its tools, resources, or any +The scope of this document is **user authorization** - how a client can authenticate a user to access a +server and the server determine whether to authorize the user to access its tools, resources, or any other capabilities. This document **does not discuss server-to-server authorization patterns**. ### 1.2 Baseline tenets -1. **MCP server developers are not security experts – do not make them do that work**. The current - specification assumes that developers will be building their own authorization server. That is not - something they ever need to do in the context of MCP servers. This also introduces room for serious +1. **MCP server developers are not security experts – do not make them do that work**. The current + specification assumes that developers will be building their own authorization server. That is not + something they ever need to do in the context of MCP servers. This also introduces room for serious mistakes that can lead to compromise. -1. **MCP clients are identity provider (IdP)-agnostic**. We do not and will not expect clients to be - "enlightened" in any capacity to support a protected MCP server. This will fragment the ecosystem. - The specification explicitly assumes that clients are not enabled in any unique way to support +1. **MCP clients are identity provider (IdP)-agnostic**. We do not and will not expect clients to be + "enlightened" in any capacity to support a protected MCP server. This will fragment the ecosystem. + The specification explicitly assumes that clients are not enabled in any unique way to support specific IdPs. - - **Note:** It is acceptable for clients to be enhanced for specific IdPs, primarily through + - **Note:** It is acceptable for clients to be enhanced for specific IdPs, primarily through pre-registration. -1. **MCP clients perform user authentication without the server.** The MCP server can guide the client - to the IdP but will not be responsible for authenticating the user and obtaining credential - artifacts for the user. The server might transform incoming credential artifacts, like tokens, but - it does not do any kind of exchange for the user in the client, nor does the MCP server have access +1. **MCP clients perform user authentication without the server.** The MCP server can guide the client + to the IdP but will not be responsible for authenticating the user and obtaining credential + artifacts for the user. The server might transform incoming credential artifacts, like tokens, but + it does not do any kind of exchange for the user in the client, nor does the MCP server have access to any user authentication credentials or protocols. -1. **We focus on OAuth 2.1, with room for extensibility for other providers/specifications.** Our - running assumption is that most developers will want to use OAuth 2.1, however in the long-run - unusual cases for authentication and authorization may emerge (e.g., mTLS, Kerberos), which will +1. **We focus on OAuth 2.1, with room for extensibility for other providers/specifications.** Our + running assumption is that most developers will want to use OAuth 2.1, however in the long-run + unusual cases for authentication and authorization may emerge (e.g., mTLS, Kerberos), which will need clients to be extensible. ### 1.3 Protocol Requirements @@ -47,14 +47,14 @@ This document **does not discuss server-to-server authorization patterns**. Authorization is **OPTIONAL** for MCP implementations. When supported: - Streamable HTTP or SSE transports **SHOULD** conform to this specification. -- Implementations using an STDIO transport **SHOULD NOT** follow this specification and instead +- Implementations using an STDIO transport **SHOULD NOT** follow this specification and instead retrieve credentials from the environment. -- Implementations using alternative transports **MUST** follow established security best practices for +- Implementations using alternative transports **MUST** follow established security best practices for their protocol. ### 1.4 Standards Compliance -This authorization mechanism is based on established specifications listed below, but implements a +This authorization mechanism is based on established specifications listed below, but 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) @@ -67,30 +67,30 @@ selected subset of their features to ensure security and interoperability while - Resource Indicators for OAuth 2.0 ([RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html)) -This specification **DOES NOT** require MCP server developers to implement their own OAuth Provider -(OP) and instead relies on developers adopting dedicated and well-tested third-party Identity +This specification **DOES NOT** require MCP server developers to implement their own OAuth Provider +(OP) and instead relies on developers adopting dedicated and well-tested third-party Identity Providers (IdPs). ## 2. Authorization Flow ### 2.1 Overview -1. Identity providers **MUST** implement OAuth 2.1 with appropriate security measures for both +1. Identity providers **MUST** implement OAuth 2.1 with appropriate security measures for both confidential and public clients. 2. Identity providers **SHOULD** support the OAuth 2.1 Dynamic Client Registration Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). -3. Identity providers **SHOULD** implement and MCP clients **MUST** consume OAuth 2.0 Authorization - Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). Servers that do not +3. Identity providers **SHOULD** implement and MCP clients **MUST** consume 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. ### 2.2 Basic OAuth 2.1 Authorization -When authorization is required and not yet proven by the client, servers **MUST** respond with +When authorization is required and not yet proven by the client, servers **MUST** respond with *HTTP 401 Unauthorized*. -A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with information about +A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with information about the issuer that the server is using to authenticate in the following format: `WWW-Authenticate: Bearer realm="default", issuer="https://idp.example",` @@ -99,30 +99,30 @@ the issuer that the server is using to authenticate in the following format: `scope="mcp_access_tool1", resource="https://mcp-server.example",` `algs="ES256 PS256"` -An MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of issuers -discovered this way (to prevent phishing). For example, an MCP client could prompt the user "Do you +An MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of issuers +discovered this way (to prevent phishing). For example, an MCP client could prompt the user "Do you want to login with `https://idp.example`?" -An MCP client **MUST** use the `issuer` identifier to construct the OAuth 2.0 metadata discovery -document path, following +An MCP client **MUST** use the `issuer` identifier to construct the OAuth 2.0 metadata discovery +document path, following [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414#section-3). -An MCP client may use the `registration_endpoint` to register itself with OAuth Provider. An MCP -client may also be pre-registered with certain OAuth Providers. +An MCP client **MAY** use the `registration_endpoint` to register itself with OAuth Provider. An MCP +client **MAY** also be pre-registered with certain OAuth Providers. -An MCP client **MUST** check the `resource` identifier against the hostname of the MCP server. An MCP -client **MUST** send the `resource` identifier to the OAuth Provider, following +An MCP client **MUST** check the `resource` identifier against the hostname of the MCP server. An MCP +client **MUST** send the `resource` identifier to the OAuth Provider, following [RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html). -An MCP client **SHOULD** implement Demonstrating Proof of Possession (DPoP) and use it to the extent -supported by the OAuth Provider. See +An MCP client **SHOULD** implement Demonstrating Proof of Possession (DPoP) and use it to the extent +supported by the OAuth Provider. See [RFC9449](https://datatracker.ietf.org/doc/html/rfc9449). -Clients initiate the -[OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization +Clients initiate the +[OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization flow after receiving the *HTTP 401 Unauthorized*. -The following demonstrates the OAuth 2.1 flow for public clients using PKCE. +The following demonstrates the OAuth 2.1 flow for public clients using PKCE for a pre-registered public client. ```mermaid sequenceDiagram @@ -146,25 +146,25 @@ sequenceDiagram ### 2.3 Server Metadata Discovery -Servers **MUST** return the issuer identifier in `WWW-Authenticate` headers in a +Servers **MUST** return the issuer identifier in `WWW-Authenticate` headers in a *HTTP 401 Unauthorized* response. -For servers that are overriding identity provider capabilities, such as those for token exchange or -dynamic client registration, they **MUST** return their fully-qualified domain as the issuer in +For servers that are overriding identity provider capabilities, such as those for token exchange or +dynamic client registration, they **MUST** return their fully-qualified domain as the issuer in `WWW-Authenticate` headers in a *HTTP 401 Unauthorized* response. For server capability discovery: -- MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct +- MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct the metadata endpoint from that issuer identifier. -- MCP servers **MUST** use an established identity provider and include its issuer in +- MCP servers **MUST** use an established identity provider and include its issuer in *HTTP 401 Unauthorized* responses. -- MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity +- MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity providers. -- MCP servers with partial support for other identity providers or that implement their own - authentication and authorization logic **SHOULD** follow the OAuth 2.0 Authorization Server Metadata +- MCP servers with partial support for other identity providers or that implement their own + authentication and authorization logic **SHOULD** follow the OAuth 2.0 Authorization Server Metadata protocol. -- MCP servers **MUST** respond with a `WWW-Authenticate` header with `issuer`, `scope`, and `resource` +- MCP servers **MUST** respond with a `WWW-Authenticate` header with `issuer`, `scope`, and `resource` identifiers. The discovery flow is illustrated below: @@ -184,7 +184,7 @@ sequenceDiagram #### 2.3.1 Server Metadata Discovery Headers -MCP clients **SHOULD** include the header `MCP-Protocol-Version: ` during Server +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. For example: `MCP-Protocol-Version: 2024-11-05` @@ -193,12 +193,12 @@ For example: `MCP-Protocol-Version: 2024-11-05` #### 2.4.1 Overview -MCP servers **MAY** override endpoints on an as-needed basis if the identity provider requires +MCP servers **MAY** override endpoints on an as-needed basis if the identity provider requires additional gestures that are not captured by the specification. MCP servers **MUST NOT** complete PKCE or other public client flows on behalf of the client. -MCP servers that do not implement a [metadata discovery process](#23-server-metadata-discovery) must +MCP servers that do not implement a [metadata discovery process](#23-server-metadata-discovery) must be assumed to implement the OAuth flow through standard endpoints (e.g., `/authorize` and `/token`) #### 2.4.2 Flow Description @@ -206,16 +206,16 @@ be assumed to implement the OAuth flow through standard endpoints (e.g., `/autho The third-party authorization flow comprises these steps: 1. MCP client requests data from the MCP server. -1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the +1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the `issuer`, `scope`, and `resource`. 1. MCP client constructs the `/authorize` endpoint from the `issuer` identifier. -1. MCP client redirects user to identity provider's `/authorize` endpoint. MCP client uses `scope` and +1. MCP client redirects user to identity provider's `/authorize` endpoint. MCP client uses `scope` and `resource` parameters provided in the `WWW-Authenticate` header in the `/authorize` URL. 1. User authorizes with identity provider with `scope` and `resource`. 1. Identity provider redirects back to MCP client with authorization code. 1. MCP client exchanges the code for the requested tokens. 1. MCP client caches the token. -1. MCP clients can now request data from the MCP server with the token attached in the `Authorization` +1. MCP clients can now request data from the MCP server with the token attached in the `Authorization` header. ```mermaid @@ -269,21 +269,21 @@ Identity providers **MUST**: ### 2.5 Implementing server overrides -In certain scenarios, identity providers might have limited capability support and MCP server -developers may choose to supplement those with their own implementation. In this scenario, the server -**MUST** return its fully-qualified domain name as the `issuer` in the *HTTP 401 Unauthorized* +In certain scenarios, identity providers might have limited capability support and MCP server +developers may choose to supplement those with their own implementation. In this scenario, the server +**MUST** return its fully-qualified domain name as the `issuer` in the *HTTP 401 Unauthorized* response, included in the `WWW-Authenticate` header. #### 2.5.1 Discovery of server-driven overrides -Under all circumstances, the server **MUST** return a `WWW-Authenticate` with `issuer` information, -even if the server provides its own metadata document that overrides IdP endpoints (such as +Under all circumstances, the server **MUST** return a `WWW-Authenticate` with `issuer` information, +even if the server provides its own metadata document that overrides IdP endpoints (such as `/authorize`, `/token`, or `/register`). #### 2.5.2 Fallbacks for Servers without Metadata Discovery -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 +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.5.1](#251-discovery-of-server-driven-overrides): | Endpoint | Default Path | Description | @@ -292,21 +292,21 @@ following default endpoint paths relative to the authorization base URL (as defi | Token Endpoint | `/token` | Used for token exchange & refresh | | Registration Endpoint | `/register` | Used for dynamic client registration | -For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default endpoints +For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default endpoints would be: - `https://api.example.com/authorize` - `https://api.example.com/token` - `https://api.example.com/register` -Clients **MUST** first attempt to discover endpoints via the metadata document before falling back to +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. ### 2.6 Dynamic Client Registration MCP clients and 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 +[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 for MCP because: - Clients cannot know all possible servers in advance @@ -314,13 +314,13 @@ way for clients to automatically register with new servers, which is crucial for - It enables seamless connection to new servers - Servers can implement their own registration policies -MCP clients that want to dynamically register OAuth clients with the target identity provider **MUST** -provide the `software_id` and `software_version` parameters, as defined in the +MCP clients that want to dynamically register OAuth clients with the target identity provider **MUST** +provide the `software_id` and `software_version` parameters, as defined in the [Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) section of [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591). -MCP clients with mass audiences will *generally* want to pre-register and hardcode client IDs. Some -OAuth Providers (such as Google and Microsoft) limit the functionality of dynamically registered +MCP clients with mass audiences will *generally* want to pre-register and hardcode client IDs. Some +OAuth Providers (such as Google and Microsoft) limit the functionality of dynamically registered clients. An MCP client could contain a config for common issuers like: ```json @@ -330,7 +330,7 @@ clients. An MCP client could contain a config for common issuers like: ] ``` -Alternatively, an MCP client could allow the user to register the MCP client and provide those details +Alternatively, an MCP client could allow the user to register the MCP client and provide those details to the MCP client through a UI. ### 2.7 Authorization Flow Steps @@ -412,9 +412,9 @@ flowchart TD #### 2.8.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) or -[DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) requirements for resource +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) or +[DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) requirements for resource requests. Specifically: MCP client **MUST** use the Authorization request header field @@ -432,7 +432,7 @@ Authorization: DPoP DPoP: ``` -Note that authorization **MUST** be included in every HTTP request from client to server, even if they +Note that authorization **MUST** be included in every HTTP request from client to server, even if they are part of the same logical session. Access tokens **MUST NOT** be included in the URI query string. Example request: @@ -446,9 +446,9 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIs... #### 2.8.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). If -validation fails, servers **MUST** respond according to -[Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3) error +[Section 5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.2). If +validation fails, servers **MUST** respond according to +[Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3) error handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` response. ### 2.9 Security Considerations @@ -481,7 +481,7 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors: ## 3. Best Practices -#### 3.1 Local clients as Public OAuth 2.1 Clients +### 3.1 Local clients as Public OAuth 2.1 Clients We strongly recommend that local clients implement OAuth 2.1 as a public client: @@ -490,19 +490,19 @@ We strongly recommend that local clients implement OAuth 2.1 as a public client: 3. Following token refresh best practices to maintain sessions. 4. Properly handling token expiration and renewal. -#### 3.2 Authorization Metadata Discovery +### 3.2 Authorization Metadata Discovery We strongly recommend that all clients implement metadata discovery. This reduces the need for users to provide endpoints manually or clients to fallback to the defined defaults. -#### 3.3 Dynamic Client Registration +### 3.3 Dynamic Client Registration Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation -of dynamic client registration. This allows applications to automatically register with the MCP +of dynamic client registration. This allows applications to automatically register with the MCP server, and removes the need for users to obtain client IDs manually. -#### 3.4 Using delegated authorization +### 3.4 Using delegated authorization -MCP servers **SHOULD** support delegated authorization through third-party authorization servers -instead of implementing their own OAuth provider. MCP server **MAY** act as the proxy for -the identity provider. \ No newline at end of file +MCP servers **SHOULD** support delegated authorization through third-party authorization servers +instead of implementing their own OAuth provider. MCP server **MAY** act as the proxy for +the identity provider. From 3b066ad328fbb090e194af6fec051c4481be9c18 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:41:21 -0700 Subject: [PATCH 06/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 6f3101c14..2ca5866db 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -208,7 +208,7 @@ The third-party authorization flow comprises these steps: 1. MCP client requests data from the MCP server. 1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the `issuer`, `scope`, and `resource`. -1. MCP client constructs the `/authorize` endpoint from the `issuer` identifier. +1. MCP client retrieves the `/authorize` endpoint from the `issuer` metadata document. 1. MCP client redirects user to identity provider's `/authorize` endpoint. MCP client uses `scope` and `resource` parameters provided in the `WWW-Authenticate` header in the `/authorize` URL. 1. User authorizes with identity provider with `scope` and `resource`. From 8b368b8196a16d9e5395fad3b0d39e6134518f7a Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:43:26 -0700 Subject: [PATCH 07/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 2ca5866db..c2fb0b437 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -227,7 +227,7 @@ sequenceDiagram MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate - MC->>MC: Construct metadata endpoint from issuer identifier + Note over MC: MCP Client retrieves /authorize endpoint URI from the issuer metadata document (Section 2.3) MC-->>UA: Initiate authentication at /authorize Note over UA: User authorizes with scope and resource UA->>MC: Return auth code to client From 5d2335ef5102050ef8c7a1f82da53b1fe84c7a17 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:43:55 -0700 Subject: [PATCH 08/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index c2fb0b437..cceb98fb9 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -228,7 +228,7 @@ sequenceDiagram MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate Note over MC: MCP Client retrieves /authorize endpoint URI from the issuer metadata document (Section 2.3) - MC-->>UA: Initiate authentication at /authorize + MC-->>UA: Initiate authorization request at /authorize Note over UA: User authorizes with scope and resource UA->>MC: Return auth code to client MC->>IDP: Exchange code for token From 04b115df7d47f6988904ece74c69230b826c7142 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:44:15 -0700 Subject: [PATCH 09/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index cceb98fb9..0d0adb927 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -229,7 +229,7 @@ sequenceDiagram MS-->>MC: 401 Unauthorized with WWW-Authenticate Note over MC: MCP Client retrieves /authorize endpoint URI from the issuer metadata document (Section 2.3) MC-->>UA: Initiate authorization request at /authorize - Note over UA: User authorizes with scope and resource + Note over UA: User authenticates and authorizes client for scope and resource UA->>MC: Return auth code to client MC->>IDP: Exchange code for token IDP-->>MC: Third-party access token From 07ea5748c06ec003aed1ae1d6f705232448f8f96 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:44:37 -0700 Subject: [PATCH 10/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 0d0adb927..e02e94aaf 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -238,7 +238,7 @@ sequenceDiagram #### 2.4.3 Session Binding Requirements -MCP servers implementing third-party authorization **MUST**: +MCP servers integrating with third-party authorization services **MUST**: 1. Maintain secure mapping between third-party tokens and issued client sessions. 2. Validate third-party token status before honoring MCP tokens. From 40f1a2c92a334eff2e11be7231064b0270ee9f00 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:47:52 -0700 Subject: [PATCH 11/98] Update docs/specification/2025-03-26/basic/authorization.md Co-authored-by: Nate Barbettini --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index e02e94aaf..a8c75d60d 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -335,7 +335,7 @@ to the MCP client through a UI. ### 2.7 Authorization Flow Steps -The complete Authorization flow proceeds as follows: +The complete authorization flow proceeds as follows: ```mermaid sequenceDiagram From 4346cb773c6d1e564b98ef74a64ef85279bcb598 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:49:05 -0700 Subject: [PATCH 12/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index e02e94aaf..4bdf2f79b 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -22,10 +22,9 @@ This document **does not discuss server-to-server authorization patterns**. ### 1.2 Baseline tenets -1. **MCP server developers are not security experts – do not make them do that work**. The current - specification assumes that developers will be building their own authorization server. That is not - something they ever need to do in the context of MCP servers. This also introduces room for serious - mistakes that can lead to compromise. +1. **MCP server developers are not security experts**. The current specification assumes that developers + will be building their own authorization server. That is not something they ever need to do in the + context of MCP servers. This also introduces room for serious mistakes that can lead to compromise. 1. **MCP clients are identity provider (IdP)-agnostic**. We do not and will not expect clients to be "enlightened" in any capacity to support a protected MCP server. This will fragment the ecosystem. The specification explicitly assumes that clients are not enabled in any unique way to support From 651af5334cd6bc9f1a94c9a89fe528e509af367e Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:51:20 -0700 Subject: [PATCH 13/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 71a7d6d5e..c20a9d50f 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -242,14 +242,15 @@ MCP servers integrating with third-party authorization services **MUST**: 1. Maintain secure mapping between third-party tokens and issued client sessions. 2. Validate third-party token status before honoring MCP tokens. 3. Implement appropriate token lifecycle management. -4. Provide appropriate responses to the client if re-authentication is needed. +4. Provide appropriate responses to the client if re-authentication is needed. Please refer to + [RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol](https://www.rfc-editor.org/rfc/rfc9470.html). #### 2.4.4 Security Considerations When implementing authorization with identity providers, MCP servers **MUST**: 1. Request the minimum number of required scopes. -2. Securely store third-party credentials. +2. Securely store any credential artifacts obtained from the client and/or the IdP. 3. Implement appropriate session timeout handling. 4. Consider security implications of token chaining. 5. Implement proper error handling for third-party auth failures. From 8fb5274e549bfe8472296b82b44db052ef920949 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:53:00 -0700 Subject: [PATCH 14/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index c20a9d50f..d45ceefb9 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -346,7 +346,7 @@ sequenceDiagram MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate - MC->>MC: Construct OIDC path + MC->>MC: Construct metadata document path alt Supports identity provider MC->>IDP: GET /.well-known/oauth-authorization-server From c9c0cccede34f68c347274f2bab490634f13c4c1 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:53:37 -0700 Subject: [PATCH 15/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index d45ceefb9..e539d70c9 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -374,7 +374,7 @@ sequenceDiagram end Note over MC: Generate PKCE artifacts - MC-->>UA: Open /authorize + MC-->>UA: Initiate authorization call Note over UA: User enters their credentials UA->>MC: Return auth code to client MC->>IDP: Exchange auth code for tokens From 55976c247a3961a5aef802dddcfaa82633a67eea Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:53:56 -0700 Subject: [PATCH 16/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index e539d70c9..116a53445 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -375,7 +375,7 @@ sequenceDiagram Note over MC: Generate PKCE artifacts MC-->>UA: Initiate authorization call - Note over UA: User enters their credentials + Note over UA: User authenticates and authorizes client for scope and resource UA->>MC: Return auth code to client MC->>IDP: Exchange auth code for tokens IDP-->>MC: Return tokens From 8d3b5eead27eac23bf65f0c5a1afd1ad38cdae97 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:54:18 -0700 Subject: [PATCH 17/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 116a53445..4e82915d7 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -387,7 +387,7 @@ sequenceDiagram ```mermaid flowchart TD - A[Start Auth Flow] --> AA[Get authority] + A[Start Authorization Flow] --> AA[Get authority] AA-->B{Check Metadata Discovery} B -->|Available| C[Use Metadata Endpoints] B -->|Not Available| D[Use Default Endpoints] From e82644ad0adcddcc1f94b502a0379bb85c25c18c Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:55:09 -0700 Subject: [PATCH 18/98] Update docs/specification/2025-03-26/basic/authorization.md Co-authored-by: Nate Barbettini --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 4e82915d7..647949ac2 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -84,7 +84,7 @@ Providers (IdPs). Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). Servers that do not support Authorization Server Metadata **MUST** follow the default URI schema. -### 2.2 Basic OAuth 2.1 Authorization +### 2.2 Client OAuth 2.1 Authorization When authorization is required and not yet proven by the client, servers **MUST** respond with *HTTP 401 Unauthorized*. From e9d75a11eb4358c8df1c5647291d908b6e6efa42 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:55:50 -0700 Subject: [PATCH 19/98] Update docs/specification/2025-03-26/basic/authorization.md Co-authored-by: Nate Barbettini --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 647949ac2..ec520fc56 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -135,7 +135,7 @@ sequenceDiagram MC->>MC: Construct OIDC /authorize endpoint from issuer identifier Note over MC: Generate code_verifier and code_challenge,
and request with scope and resource MC-->>UA: Open /authorize - Note over UA: User authenticates to the IDP + UA-->>IDP: User authenticates UA->>MC: Return auth code to client MC->>IDP: Exchange auth code for tokens IDP-->>MC: Return tokens From 554bcc47c01b3c135fe1f5d14b9ce6b4546e0b8e Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 16:58:36 -0700 Subject: [PATCH 20/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index ec520fc56..f28bc5354 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -420,14 +420,14 @@ requests. Specifically: MCP client **MUST** use the Authorization request header field [OAuth Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): -``` +```http Authorization: Bearer ``` or [DPoP Section 7.1](https://datatracker.ietf.org/doc/html/rfc9449#name-the-dpop-authentication-sch): -``` +```http Authorization: DPoP DPoP: ``` @@ -437,7 +437,7 @@ are part of the same logical session. Access tokens **MUST NOT** be included in the URI query string. Example request: -``` +```http GET /v1/contexts HTTP/1.1 Host: mcp.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIs... @@ -456,10 +456,10 @@ handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` r The following security requirements **MUST** be implemented: 1. Clients **MUST** securely store tokens following OAuth 2.0 best practices. -1. Servers **SHOULD** enforce token expiration and rotation. +1. Servers **MUST** validate all incoming tokens. 1. All authorization endpoints **MUST** be served over HTTPS. 1. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities. -1. Redirect URIs **MUST** be either localhost URLs or HTTPS URLs. +1. Redirect URIs **MUST** be either `localhost` URLs or HTTPS URLs. 1. Special considerations **MUST** be accounted for to prevent phishing through MCP servers. ### 2.10 Error Handling From efcc03488514644d476b7c3cc0242c2900b2016e Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 17:00:32 -0700 Subject: [PATCH 21/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index f28bc5354..76a8defb7 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -304,7 +304,7 @@ default paths. When using default paths, all other protocol requirements remain ### 2.6 Dynamic Client Registration -MCP clients and servers **SHOULD** support the +MCP clients **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 for MCP because: From f4cf26154730095627cd03abb7549f32c5a3cfdc Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 17:01:23 -0700 Subject: [PATCH 22/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 76a8defb7..89702a220 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -163,8 +163,8 @@ For server capability discovery: - MCP servers with partial support for other identity providers or that implement their own authentication and authorization logic **SHOULD** follow the OAuth 2.0 Authorization Server Metadata protocol. -- MCP servers **MUST** respond with a `WWW-Authenticate` header with `issuer`, `scope`, and `resource` - identifiers. +- MCP servers **MUST** respond to an unauthorized request with a `WWW-Authenticate` header containing + `issuer`, `scope`, and `resource` identifiers. The discovery flow is illustrated below: From 50fbf5abde00b3bbf7ef0b692ca520cdf3653dc5 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 17:01:51 -0700 Subject: [PATCH 23/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 89702a220..c1bec0800 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -139,7 +139,7 @@ sequenceDiagram UA->>MC: Return auth code to client MC->>IDP: Exchange auth code for tokens IDP-->>MC: Return tokens - MC->>MC: Cache tokens + MC->>MC: Store tokens securely Note over MC, MS: Begin standard MCP message exchange ``` From c1ae0ecccb82f2774cada8431757025554fcf770 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 17:02:56 -0700 Subject: [PATCH 24/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index c1bec0800..6561a6724 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -156,7 +156,7 @@ For server capability discovery: - MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct the metadata endpoint from that issuer identifier. -- MCP servers **MUST** use an established identity provider and include its issuer in +- MCP servers **SHOULD** use a third-party identity provider and include its issuer in *HTTP 401 Unauthorized* responses. - MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity providers. From 4286967c2fe1500319ce91c316fa45f142fbddc2 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 17:04:41 -0700 Subject: [PATCH 25/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 6561a6724..7ecda347e 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -160,9 +160,8 @@ For server capability discovery: *HTTP 401 Unauthorized* responses. - MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity providers. -- MCP servers with partial support for other identity providers or that implement their own - authentication and authorization logic **SHOULD** follow the OAuth 2.0 Authorization Server Metadata - protocol. +- Identity providers **MUST** support + [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - MCP servers **MUST** respond to an unauthorized request with a `WWW-Authenticate` header containing `issuer`, `scope`, and `resource` identifiers. From 09e03bdf568050d703c756d33fd7ac695426720c Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 17:05:23 -0700 Subject: [PATCH 26/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index 7ecda347e..e416b3f7e 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -117,8 +117,8 @@ An MCP client **SHOULD** implement Demonstrating Proof of Possession (DPoP) and supported by the OAuth Provider. See [RFC9449](https://datatracker.ietf.org/doc/html/rfc9449). -Clients initiate the -[OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization +Clients initiate an +[OAuth 2.1 (draft)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization flow after receiving the *HTTP 401 Unauthorized*. The following demonstrates the OAuth 2.1 flow for public clients using PKCE for a pre-registered public client. From 22164356d15e3f7246e7e78907499f2f11372b85 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 17:11:22 -0700 Subject: [PATCH 27/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index e416b3f7e..b6d9aea90 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -444,9 +444,10 @@ Authorization: Bearer eyJhbGciOiJIUzI1NiIs... #### 2.8.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). If -validation fails, servers **MUST** respond according to +Resource servers (MCP servers _or_ downstream APIs) **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). + +If validation fails, servers **MUST** respond according to [Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3) error handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` response. From 1ae49bc97907cfed41eea513c102e3bffcab5681 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 17:17:20 -0700 Subject: [PATCH 28/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index b6d9aea90..b417fb3b7 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -57,19 +57,23 @@ This authorization mechanism is based on established specifications listed below 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.0 Authorization Server Metadata +- OAuth 2.0 Authorization Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)) -- OAuth 2.0 Dynamic Client Registration Protocol +- OAuth 2.0 Dynamic Client Registration Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)) -- OAuth 2.0 Demonstrating Proof of Possession (DPoP) +- OAuth 2.0 Demonstrating Proof of Possession (DPoP) ([RFC9449](https://datatracker.ietf.org/doc/html/rfc9449)) -- Resource Indicators for OAuth 2.0 +- Resource Indicators for OAuth 2.0 ([RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html)) This specification **DOES NOT** require MCP server developers to implement their own OAuth Provider (OP) and instead relies on developers adopting dedicated and well-tested third-party Identity Providers (IdPs). +This specification also enables existing deployments to leverage their current infrastructure. +As a side-effect, this also simplifies consent flows, and services that have multiple MCP Servers +won't require individual registration per client:server pair. + ## 2. Authorization Flow ### 2.1 Overview From 3468f0213c24d637d6cdb493a6bc18134d733748 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 7 Apr 2025 17:18:18 -0700 Subject: [PATCH 29/98] Update authorization.md --- docs/specification/2025-03-26/basic/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.md b/docs/specification/2025-03-26/basic/authorization.md index b417fb3b7..3389cc11d 100644 --- a/docs/specification/2025-03-26/basic/authorization.md +++ b/docs/specification/2025-03-26/basic/authorization.md @@ -459,7 +459,7 @@ handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` r The following security requirements **MUST** be implemented: -1. Clients **MUST** securely store tokens following OAuth 2.0 best practices. +1. Clients **MUST** securely store tokens following OAuth 2.1 best practices. 1. Servers **MUST** validate all incoming tokens. 1. All authorization endpoints **MUST** be served over HTTPS. 1. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities. From 6859c74dfaddd9e0be35fdb55a7741841ebedaa6 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 12:41:46 -0700 Subject: [PATCH 30/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index c148d95d7..5fbc9e8b6 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -76,8 +76,9 @@ won't require individual registration per client:server pair. ### 2.1 Overview -1. Identity providers **MUST** implement OAuth 2.1 with appropriate security measures for both - confidential and public clients. +1. Identity providers **MUST** implement OAuth 2.1 with appropriate security measures + (see [RFC9700](https://datatracker.ietf.org/doc/html/rfc9700)) for both confidential and + public clients. 2. Identity providers **SHOULD** support the OAuth 2.1 Dynamic Client Registration Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). @@ -109,7 +110,7 @@ document path, following [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414#section-3). An MCP client **MAY** use the `registration_endpoint` to register itself with OAuth Provider. An MCP -client **MAY** also be pre-registered with certain OAuth Providers. +client **MAY** also be pre-registered with an OAuth Provider. An MCP client **MUST** check the `resource` identifier against the hostname of the MCP server. An MCP client **MUST** send the `resource` identifier to the OAuth Provider, following From 4efe664f9cb6cc79433878d3ae15c74ce5d48589 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 12:44:43 -0700 Subject: [PATCH 31/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 5fbc9e8b6..faf3a1f02 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -29,7 +29,7 @@ This document **does not discuss server-to-server authorization patterns**. specific IdPs. - **Note:** It is acceptable for clients to be enhanced for specific IdPs, primarily through pre-registration. -1. **MCP clients perform user authentication without the server.** The MCP server can guide the client +1. **User Authentication is not a MCP Server concern.** The MCP server can guide the client to the IdP but will not be responsible for authenticating the user and obtaining credential artifacts for the user. The server might transform incoming credential artifacts, like tokens, but it does not do any kind of exchange for the user in the client, nor does the MCP server have access @@ -224,7 +224,7 @@ sequenceDiagram participant UA as User-Agent (Browser) participant MC as MCP Client participant MS as MCP Server - participant IDP as Third-Party Auth Server + participant IDP as Identity Provider MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate From a0163655495c34bb0ee83cab98e81d4971ace2c8 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 12:45:29 -0700 Subject: [PATCH 32/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index faf3a1f02..ba41247c1 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -259,7 +259,7 @@ When implementing authorization with identity providers, MCP servers **MUST**: MCP clients **MUST**: -1. Securely store authentication tokens received from the identity provider. +1. Securely store Access and Refresh Tokens received from the identity provider. 2. Properly handle request to re-authenticate users with expired or invalid tokens. 3. Verify that the resource identifier returned matches the FQDN of the MCP server. 4. Forward the resource identifier returns as `resource` parameter according to From e406fa26cf5495d679ecb72606aa07e2ab4e7051 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 12:49:16 -0700 Subject: [PATCH 33/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index ba41247c1..b1aff40d9 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -459,7 +459,11 @@ handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` r The following security requirements **MUST** be implemented: 1. Clients **MUST** securely store tokens following OAuth 2.1 best practices. -1. Servers **MUST** validate all incoming tokens. +1. Servers **MUST** validate all incoming tokens in one of the three ways: + 1. Token introspection, according to [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662). + `aud` validation is a **MUST**. + 1. JWT validation, according to [RFC9068](https://www.rfc-editor.org/rfc/rfc9068.html). + 1. Custom validation, according to the conventions established by the Authorization Server. 1. All authorization endpoints **MUST** be served over HTTPS. 1. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities. 1. Redirect URIs **MUST** be either `localhost` URLs or HTTPS URLs. From 65012a590315873a4b161b9a2f4aa8b271931ac0 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 12:52:49 -0700 Subject: [PATCH 34/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 24 +------------------ 1 file changed, 1 insertion(+), 23 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index b1aff40d9..cea1b9282 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -122,29 +122,7 @@ supported by the OAuth Provider. See Clients initiate an [OAuth 2.1 (draft)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization -flow after receiving the *HTTP 401 Unauthorized*. - -The following demonstrates the OAuth 2.1 flow for public clients using PKCE for a pre-registered public client. - -```mermaid -sequenceDiagram - participant UA as User-Agent (Browser or App/Broker) - participant MC as MCP Client - participant MS as MCP Server - participant IDP as Identity Provider - - MC->>MS: MCP Request - MS-->>MC: 401 Unauthorized with issuer, scope, and resource in WWW-Authenticate - MC->>MC: Construct OIDC /authorize endpoint from issuer identifier - Note over MC: Generate code_verifier and code_challenge,
and request with scope and resource - MC-->>UA: Open /authorize - UA-->>IDP: User authenticates - UA->>MC: Return auth code to client - MC->>IDP: Exchange auth code for tokens - IDP-->>MC: Return tokens - MC->>MC: Store tokens securely - Note over MC, MS: Begin standard MCP message exchange -``` +flow after receiving a *HTTP 401 Unauthorized* response. ### 2.3 Server Metadata Discovery From 213880f07295664180d4ea996ea35106a7f27597 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 12:54:59 -0700 Subject: [PATCH 35/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index cea1b9282..a0f36b80a 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -126,12 +126,8 @@ flow after receiving a *HTTP 401 Unauthorized* response. ### 2.3 Server Metadata Discovery -Servers **MUST** return the issuer identifier in `WWW-Authenticate` headers in a -*HTTP 401 Unauthorized* response. - -For servers that are overriding identity provider capabilities, such as those for token exchange or -dynamic client registration, they **MUST** return their fully-qualified domain as the issuer in -`WWW-Authenticate` headers in a *HTTP 401 Unauthorized* response. +Servers **MUST** return the fully-qualified domain name of the issuer in `WWW-Authenticate` +headers in a *HTTP 401 Unauthorized* response. For server capability discovery: From 30ccdae7dea5d6b3a40397fdea63d2ecac2d2456 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 13:07:25 -0700 Subject: [PATCH 36/98] Terminology update --- .../2025-03-26/basic/authorization.mdx | 109 +++++++++--------- 1 file changed, 54 insertions(+), 55 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index a0f36b80a..7bc97e3c4 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -23,15 +23,15 @@ This document **does not discuss server-to-server authorization patterns**. 1. **MCP server developers are not security experts**. The current specification assumes that developers will be building their own authorization server. That is not something they ever need to do in the context of MCP servers. This also introduces room for serious mistakes that can lead to compromise. -1. **MCP clients are identity provider (IdP)-agnostic**. We do not and will not expect clients to be +1. **MCP clients are Authorization Server (AS)-agnostic**. We do not and will not expect clients to be "enlightened" in any capacity to support a protected MCP server. This will fragment the ecosystem. The specification explicitly assumes that clients are not enabled in any unique way to support - specific IdPs. - - **Note:** It is acceptable for clients to be enhanced for specific IdPs, primarily through - pre-registration. + specific Authorization Servers. + - **Note:** It is acceptable for clients to be enhanced for specific Authorization Servers, + primarily through pre-registration. 1. **User Authentication is not a MCP Server concern.** The MCP server can guide the client - to the IdP but will not be responsible for authenticating the user and obtaining credential - artifacts for the user. The server might transform incoming credential artifacts, like tokens, but + to the AS but will not be responsible for authenticating the user and obtaining credential + artifacts for the user. The MCP server might transform incoming credential artifacts, like tokens, but it does not do any kind of exchange for the user in the client, nor does the MCP server have access to any user authentication credentials or protocols. 1. **We focus on OAuth 2.1, with room for extensibility for other providers/specifications.** Our @@ -64,9 +64,8 @@ selected subset of their features to ensure security and interoperability while - Resource Indicators for OAuth 2.0 ([RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html)) -This specification **DOES NOT** require MCP server developers to implement their own OAuth Provider -(OP) and instead relies on developers adopting dedicated and well-tested third-party Identity -Providers (IdPs). +This specification **DOES NOT** require MCP server developers to implement their own Authorization Server +and instead relies on developers adopting dedicated and well-tested third-party AS implementations. This specification also enables existing deployments to leverage their current infrastructure. As a side-effect, this also simplifies consent flows, and services that have multiple MCP Servers @@ -76,14 +75,14 @@ won't require individual registration per client:server pair. ### 2.1 Overview -1. Identity providers **MUST** implement OAuth 2.1 with appropriate security measures +1. Authorization servers **MUST** implement OAuth 2.1 with appropriate security measures (see [RFC9700](https://datatracker.ietf.org/doc/html/rfc9700)) for both confidential and public clients. -2. Identity providers **SHOULD** support the OAuth 2.1 Dynamic Client Registration Protocol +2. Authorization servers **SHOULD** support the OAuth 2.1 Dynamic Client Registration Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). -3. Identity providers **SHOULD** implement and MCP clients **MUST** consume OAuth 2.0 Authorization +3. Authorization servers **SHOULD** implement and MCP clients **MUST** consume 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. @@ -95,15 +94,15 @@ When authorization is required and not yet proven by the client, servers **MUST* A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with information about the issuer that the server is using to authenticate in the following format: -`WWW-Authenticate: Bearer realm="default", issuer="https://idp.example",` +`WWW-Authenticate: Bearer realm="default", issuer="https://authserver.example",` `scope="mcp_access_tool1", resource="https://mcp-server.example"` -`WWW-Authenticate: DPoP realm="default", issuer="https://idp.example",` +`WWW-Authenticate: DPoP realm="default", issuer="https://authserver.example",` `scope="mcp_access_tool1", resource="https://mcp-server.example",` `algs="ES256 PS256"` An MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of issuers discovered this way (to prevent phishing). For example, an MCP client could prompt the user "Do you -want to login with `https://idp.example`?" +want to login with `https://authserver.example`?" An MCP client **MUST** use the `issuer` identifier to construct the OAuth 2.0 metadata discovery document path, following @@ -133,11 +132,11 @@ For server capability discovery: - MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct the metadata endpoint from that issuer identifier. -- MCP servers **SHOULD** use a third-party identity provider and include its issuer in +- MCP servers **SHOULD** use a third-party authorization server and include its issuer in *HTTP 401 Unauthorized* responses. - MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity providers. -- Identity providers **MUST** support +- Authorization Servers **MUST** support [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - MCP servers **MUST** respond to an unauthorized request with a `WWW-Authenticate` header containing `issuer`, `scope`, and `resource` identifiers. @@ -148,7 +147,7 @@ The discovery flow is illustrated below: sequenceDiagram participant MC as MCP Client participant MS as MCP Server - participant IDP as Identity Provider + participant AUTHZS as Authorization Server MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate @@ -164,11 +163,11 @@ Metadata Discovery to allow the MCP server to respond based on the MCP protocol For example: `MCP-Protocol-Version: 2024-11-05` -### 2.4 Identity provider integration +### 2.4 Authorization server integration #### 2.4.1 Overview -MCP servers **MAY** override endpoints on an as-needed basis if the identity provider requires +MCP servers **MAY** override endpoints on an as-needed basis if the authorization server requires additional gestures that are not captured by the specification. MCP servers **MUST NOT** complete PKCE or other public client flows on behalf of the client. @@ -184,10 +183,10 @@ The third-party authorization flow comprises these steps: 1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the `issuer`, `scope`, and `resource`. 1. MCP client retrieves the `/authorize` endpoint from the `issuer` metadata document. -1. MCP client redirects user to identity provider's `/authorize` endpoint. MCP client uses `scope` and +1. MCP client redirects user to authorization server's `/authorize` endpoint. MCP client uses `scope` and `resource` parameters provided in the `WWW-Authenticate` header in the `/authorize` URL. -1. User authorizes with identity provider with `scope` and `resource`. -1. Identity provider redirects back to MCP client with authorization code. +1. User authorizes with authorization server with `scope` and `resource`. +1. Authorization server redirects back to MCP client with authorization code. 1. MCP client exchanges the code for the requested tokens. 1. MCP client caches the token. 1. MCP clients can now request data from the MCP server with the token attached in the `Authorization` @@ -198,7 +197,7 @@ sequenceDiagram participant UA as User-Agent (Browser) participant MC as MCP Client participant MS as MCP Server - participant IDP as Identity Provider + participant AUTHZS as Authorization Server MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate @@ -206,8 +205,8 @@ sequenceDiagram MC-->>UA: Initiate authorization request at /authorize Note over UA: User authenticates and authorizes client for scope and resource UA->>MC: Return auth code to client - MC->>IDP: Exchange code for token - IDP-->>MC: Third-party access token + MC->>AUTHZS: Exchange code for token + AUTHZS-->>MC: Third-party access token MC->>MC: Cache token ``` @@ -223,29 +222,29 @@ MCP servers integrating with third-party authorization services **MUST**: #### 2.4.4 Security Considerations -When implementing authorization with identity providers, MCP servers **MUST**: +When implementing authorization with an existing authorization server, MCP servers **MUST**: 1. Request the minimum number of required scopes. -2. Securely store any credential artifacts obtained from the client and/or the IdP. +2. Securely store any credential artifacts obtained from the client and/or the authorization server. 3. Implement appropriate session timeout handling. 4. Consider security implications of token chaining. 5. Implement proper error handling for third-party auth failures. MCP clients **MUST**: -1. Securely store Access and Refresh Tokens received from the identity provider. +1. Securely store Access and Refresh Tokens received from the authorization server. 2. Properly handle request to re-authenticate users with expired or invalid tokens. 3. Verify that the resource identifier returned matches the FQDN of the MCP server. 4. Forward the resource identifier returns as `resource` parameter according to [RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html). -Identity providers **MUST**: +Authorization servers **MUST**: 1. Verify that the resource identifier is registered for the audience of the access token issued. ### 2.5 Implementing server overrides -In certain scenarios, identity providers might have limited capability support and MCP server +In certain scenarios, authorization servers might have limited capability support and MCP server developers may choose to supplement those with their own implementation. In this scenario, the server **MUST** return its fully-qualified domain name as the `issuer` in the *HTTP 401 Unauthorized* response, included in the `WWW-Authenticate` header. @@ -253,14 +252,14 @@ response, included in the `WWW-Authenticate` header. #### 2.5.1 Discovery of server-driven overrides Under all circumstances, the server **MUST** return a `WWW-Authenticate` with `issuer` information, -even if the server provides its own metadata document that overrides IdP endpoints (such as -`/authorize`, `/token`, or `/register`). +even if the server provides its own metadata document that overrides Authorization Server endpoints +(such as `/authorize`, `/token`, or `/register`). #### 2.5.2 Fallbacks for Servers without Metadata Discovery 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.5.1](#251-discovery-of-server-driven-overrides): +[Section 2.5.1](#251-discovery-of-server-driven-overrides)): | Endpoint | Default Path | Description | | ---------------------- | -------------- | ------------------------------------ | @@ -290,19 +289,19 @@ way for clients to automatically register with new servers, which is crucial for - It enables seamless connection to new servers - Servers can implement their own registration policies -MCP clients that want to dynamically register OAuth clients with the target identity provider **MUST** +MCP clients that want to dynamically register OAuth clients with an authorization server **MUST** provide the `software_id` and `software_version` parameters, as defined in the [Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) section of [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591). MCP clients with mass audiences will *generally* want to pre-register and hardcode client IDs. Some -OAuth Providers (such as Google and Microsoft) limit the functionality of dynamically registered +authorization servers (such as Google and Microsoft) limit the functionality of dynamically registered clients. An MCP client could contain a config for common issuers like: ```json [ - { "issuer":"https://idp.example", "client_id":"12345"}, - { "issuer":"https://idp2.example", "client_id":"urn:client_ids:546"} + { "issuer":"https://authserver.example", "client_id":"12345"}, + { "issuer":"https://authserver2.example", "client_id":"urn:client_ids:546"} ] ``` @@ -318,34 +317,34 @@ sequenceDiagram participant UA as User-Agent (Browser or App/Broker) participant MC as MCP Client participant MS as MCP Server - participant IDP as Identity Provider + participant AUTHZS as Authorization Server MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate MC->>MC: Construct metadata document path - alt Supports identity provider - MC->>IDP: GET /.well-known/oauth-authorization-server - IDP-->>MC: Return endpoint metadata - else Partial or No IDP Support + alt Supports authorization server + MC->>AUTHZS: GET /.well-known/oauth-authorization-server + AUTHZS-->>MC: Return endpoint metadata + else Partial or No authorization server support MC->>MS: GET /.well-known/oauth-authorization-server - alt Discovery Success + alt Discovery success MS-->>MC: 200 OK + Metadata Document Note over MC: Use endpoints from metadata - else Discovery Failed + else Discovery failed MS-->>MC: 404 Not Found Note over MC: Fall back to default endpoints end end - alt Client is pre-registered for the identity provider - else Identity provider supports dynamic client registration - MC->>IDP: Request client registration - IDP-->>MC: Confirm client registration - else Identity provider does not support dynamic client registration + alt Client is pre-registered with the authorization server + else Authorization server supports dynamic client registration + MC->>AUTHZS: Request client registration + AUTHZS-->>MC: Confirm client registration + else Authorization server does not support dynamic client registration MC->>MS: Request client registration - MS->>IDP: Register client - IDP-->>MS: Return client registration + MS->>AUTHZS: Register client + AUTHZS-->>MS: Return client registration MS-->>MC: Return client registration end @@ -353,8 +352,8 @@ sequenceDiagram MC-->>UA: Initiate authorization call Note over UA: User authenticates and authorizes client for scope and resource UA->>MC: Return auth code to client - MC->>IDP: Exchange auth code for tokens - IDP-->>MC: Return tokens + MC->>AUTHZS: Exchange auth code for tokens + AUTHZS-->>MC: Return tokens MC->>MC: Cache tokens Note over MC, MS: Begin standard MCP message exchange ``` @@ -486,4 +485,4 @@ server, and removes the need for users to obtain client IDs manually. MCP servers **SHOULD** support delegated authorization through third-party authorization servers instead of implementing their own OAuth provider. MCP server **MAY** act as the proxy for -the identity provider. +the authorization server. From 493c1e91e2f9c874388cb5b71b983464b604d421 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 13:23:06 -0700 Subject: [PATCH 37/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 7bc97e3c4..c442b2654 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -228,7 +228,7 @@ When implementing authorization with an existing authorization server, MCP serve 2. Securely store any credential artifacts obtained from the client and/or the authorization server. 3. Implement appropriate session timeout handling. 4. Consider security implications of token chaining. -5. Implement proper error handling for third-party auth failures. +5. Implement proper error handling for authorization failures. MCP clients **MUST**: From 364d71bf86d3b5d721133751405f5e41ffb96dfa Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 13:29:49 -0700 Subject: [PATCH 38/98] Update authorization.mdx --- .../specification/2025-03-26/basic/authorization.mdx | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index c442b2654..fab4b9888 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -326,7 +326,7 @@ sequenceDiagram alt Supports authorization server MC->>AUTHZS: GET /.well-known/oauth-authorization-server AUTHZS-->>MC: Return endpoint metadata - else Partial or No authorization server support + else Partial or no authorization server support MC->>MS: GET /.well-known/oauth-authorization-server alt Discovery success MS-->>MC: 200 OK + Metadata Document @@ -392,7 +392,7 @@ Access token handling **MUST** conform to [DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) requirements for resource requests. Specifically: -MCP client **MUST** use the Authorization request header field +MCP client **MUST** use the `Authorization` request header field and **MUST NOT** use URI query string to transport Tokens [OAuth Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): ```http @@ -410,14 +410,6 @@ DPoP: Note that authorization **MUST** be included in every HTTP request from client to server, even if they are part of the same logical session. -Access tokens **MUST NOT** be included in the URI query string. Example request: - -```http -GET /v1/contexts HTTP/1.1 -Host: mcp.example.com -Authorization: Bearer eyJhbGciOiJIUzI1NiIs... -``` - #### 2.8.2 Token Handling Resource servers (MCP servers _or_ downstream APIs) **MUST** validate access tokens as described From 647ca4966f40e4c02d7c196ad177cd82ba13090e Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 13:35:59 -0700 Subject: [PATCH 39/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 29 ++----------------- 1 file changed, 3 insertions(+), 26 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index fab4b9888..c2fe124a3 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -83,8 +83,7 @@ won't require individual registration per client:server pair. ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). 3. Authorization servers **SHOULD** implement and MCP clients **MUST** consume 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. + Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). ### 2.2 Client OAuth 2.1 Authorization @@ -172,8 +171,8 @@ additional gestures that are not captured by the specification. MCP servers **MUST NOT** complete PKCE or other public client flows on behalf of the client. -MCP servers that do not implement a [metadata discovery process](#23-server-metadata-discovery) must -be assumed to implement the OAuth flow through standard endpoints (e.g., `/authorize` and `/token`) +MCP servers that **MUST** implement the [metadata discovery process](#23-server-metadata-discovery) +if they do not use a third-party authorization server. #### 2.4.2 Flow Description @@ -255,28 +254,6 @@ Under all circumstances, the server **MUST** return a `WWW-Authenticate` with `i even if the server provides its own metadata document that overrides Authorization Server endpoints (such as `/authorize`, `/token`, or `/register`). -#### 2.5.2 Fallbacks for Servers without Metadata Discovery - -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.5.1](#251-discovery-of-server-driven-overrides)): - -| 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 | - -For example, with an MCP server hosted at `https://api.example.com/v1/mcp`, the default endpoints -would be: - -- `https://api.example.com/authorize` -- `https://api.example.com/token` -- `https://api.example.com/register` - -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. - ### 2.6 Dynamic Client Registration MCP clients **SHOULD** support the From 9e681766f2d3aa2d5547d02d44e54355562c3991 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 13:43:19 -0700 Subject: [PATCH 40/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index c2fe124a3..66494f8e1 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -122,17 +122,20 @@ Clients initiate an [OAuth 2.1 (draft)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization flow after receiving a *HTTP 401 Unauthorized* response. -### 2.3 Server Metadata Discovery +### 2.3 MCP Server Metadata Discovery -Servers **MUST** return the fully-qualified domain name of the issuer in `WWW-Authenticate` -headers in a *HTTP 401 Unauthorized* response. +MCP servers **MUST** return the fully-qualified domain name of the issuer in `WWW-Authenticate` +headers in an error respose. -For server capability discovery: +MCP servers **MUST** follow [RFC6750 Section 3.1](https://www.rfc-editor.org/rfc/rfc6750#section-3.1) for +any authorization failures. + +For MCP server capability discovery: - MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct the metadata endpoint from that issuer identifier. - MCP servers **SHOULD** use a third-party authorization server and include its issuer in - *HTTP 401 Unauthorized* responses. + error responses. - MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity providers. - Authorization Servers **MUST** support From 397beaedd91e1645a4c21a3379461a4ee8ba8149 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 14:21:13 -0700 Subject: [PATCH 41/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 66494f8e1..7541d4780 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -56,13 +56,13 @@ selected subset of their features to ensure security and interoperability while - [OAuth 2.1 IETF DRAFT](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)) + ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) - OAuth 2.0 Dynamic Client Registration Protocol - ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)) + ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) - OAuth 2.0 Demonstrating Proof of Possession (DPoP) - ([RFC9449](https://datatracker.ietf.org/doc/html/rfc9449)) + ([RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449)) - Resource Indicators for OAuth 2.0 - ([RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html)) + ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html)) This specification **DOES NOT** require MCP server developers to implement their own Authorization Server and instead relies on developers adopting dedicated and well-tested third-party AS implementations. @@ -76,14 +76,14 @@ won't require individual registration per client:server pair. ### 2.1 Overview 1. Authorization servers **MUST** implement OAuth 2.1 with appropriate security measures - (see [RFC9700](https://datatracker.ietf.org/doc/html/rfc9700)) for both confidential and + (see [RFC 9700](https://datatracker.ietf.org/doc/html/rfc9700)) for both confidential and public clients. 2. Authorization servers **SHOULD** support the OAuth 2.1 Dynamic Client Registration Protocol - ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). + ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)). 3. Authorization servers **SHOULD** implement and MCP clients **MUST** consume OAuth 2.0 Authorization - Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). + Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)). ### 2.2 Client OAuth 2.1 Authorization @@ -105,18 +105,18 @@ want to login with `https://authserver.example`?" An MCP client **MUST** use the `issuer` identifier to construct the OAuth 2.0 metadata discovery document path, following -[RFC8414](https://datatracker.ietf.org/doc/html/rfc8414#section-3). +[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414#section-3). An MCP client **MAY** use the `registration_endpoint` to register itself with OAuth Provider. An MCP client **MAY** also be pre-registered with an OAuth Provider. An MCP client **MUST** check the `resource` identifier against the hostname of the MCP server. An MCP client **MUST** send the `resource` identifier to the OAuth Provider, following -[RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html). +[RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html). An MCP client **SHOULD** implement Demonstrating Proof of Possession (DPoP) and use it to the extent supported by the OAuth Provider. See -[RFC9449](https://datatracker.ietf.org/doc/html/rfc9449). +[RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449). Clients initiate an [OAuth 2.1 (draft)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization @@ -127,7 +127,7 @@ flow after receiving a *HTTP 401 Unauthorized* response. MCP servers **MUST** return the fully-qualified domain name of the issuer in `WWW-Authenticate` headers in an error respose. -MCP servers **MUST** follow [RFC6750 Section 3.1](https://www.rfc-editor.org/rfc/rfc6750#section-3.1) for +MCP servers **MUST** follow [RFC 6750 Section 3.1](https://www.rfc-editor.org/rfc/rfc6750#section-3.1) for any authorization failures. For MCP server capability discovery: @@ -235,10 +235,12 @@ When implementing authorization with an existing authorization server, MCP serve MCP clients **MUST**: 1. Securely store Access and Refresh Tokens received from the authorization server. -2. Properly handle request to re-authenticate users with expired or invalid tokens. +2. Properly handle requests to re-authenticate users with expired or invalid tokens (using the + Refresh Token grant) or due to challenges (refer to + [RFC 9470](https://www.rfc-editor.org/rfc/rfc9470.html)). 3. Verify that the resource identifier returned matches the FQDN of the MCP server. 4. Forward the resource identifier returns as `resource` parameter according to - [RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html). + [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html). Authorization servers **MUST**: @@ -272,7 +274,7 @@ way for clients to automatically register with new servers, which is crucial for MCP clients that want to dynamically register OAuth clients with an authorization server **MUST** provide the `software_id` and `software_version` parameters, as defined in the [Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) section of -[RFC7591](https://datatracker.ietf.org/doc/html/rfc7591). +[RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). MCP clients with mass audiences will *generally* want to pre-register and hardcode client IDs. Some authorization servers (such as Google and Microsoft) limit the functionality of dynamically registered @@ -407,7 +409,7 @@ The following security requirements **MUST** be implemented: 1. Servers **MUST** validate all incoming tokens in one of the three ways: 1. Token introspection, according to [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662). `aud` validation is a **MUST**. - 1. JWT validation, according to [RFC9068](https://www.rfc-editor.org/rfc/rfc9068.html). + 1. JWT validation, according to [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068.html). 1. Custom validation, according to the conventions established by the Authorization Server. 1. All authorization endpoints **MUST** be served over HTTPS. 1. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities. From f67d255fc9538c44311a928cef1bcf9b514edeab Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 14:23:45 -0700 Subject: [PATCH 42/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 7541d4780..a05d43807 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -412,7 +412,7 @@ The following security requirements **MUST** be implemented: 1. JWT validation, according to [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068.html). 1. Custom validation, according to the conventions established by the Authorization Server. 1. All authorization endpoints **MUST** be served over HTTPS. -1. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities. +1. Authorization servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities. 1. Redirect URIs **MUST** be either `localhost` URLs or HTTPS URLs. 1. Special considerations **MUST** be accounted for to prevent phishing through MCP servers. From 442b0b43284ac80e1c33d3f65edc5b54be7356d5 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 15:10:51 -0700 Subject: [PATCH 43/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index a05d43807..65910dd00 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -20,9 +20,9 @@ This document **does not discuss server-to-server authorization patterns**. ### 1.2 Baseline tenets -1. **MCP server developers are not security experts**. The current specification assumes that developers - will be building their own authorization server. That is not something they ever need to do in the - context of MCP servers. This also introduces room for serious mistakes that can lead to compromise. +1. **MCP server developers are not security experts**. Developers should not be building their own + authorization servers unless absolutely necessary. This also introduces room for serious mistakes + that can lead to compromise. 1. **MCP clients are Authorization Server (AS)-agnostic**. We do not and will not expect clients to be "enlightened" in any capacity to support a protected MCP server. This will fragment the ecosystem. The specification explicitly assumes that clients are not enabled in any unique way to support @@ -458,5 +458,4 @@ server, and removes the need for users to obtain client IDs manually. ### 3.4 Using delegated authorization MCP servers **SHOULD** support delegated authorization through third-party authorization servers -instead of implementing their own OAuth provider. MCP server **MAY** act as the proxy for -the authorization server. +instead of implementing their own. From ea94d9c158bb9298340fa8bda07e530a24235d40 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 15:11:24 -0700 Subject: [PATCH 44/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 65910dd00..ef5aafb22 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -30,7 +30,7 @@ This document **does not discuss server-to-server authorization patterns**. - **Note:** It is acceptable for clients to be enhanced for specific Authorization Servers, primarily through pre-registration. 1. **User Authentication is not a MCP Server concern.** The MCP server can guide the client - to the AS but will not be responsible for authenticating the user and obtaining credential + to the AS but the MCP Server will not be responsible for authenticating the user and obtaining credential artifacts for the user. The MCP server might transform incoming credential artifacts, like tokens, but it does not do any kind of exchange for the user in the client, nor does the MCP server have access to any user authentication credentials or protocols. From 38b67e36f27a35bab2b3dea4758a05fbd84777fc Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 15:11:37 -0700 Subject: [PATCH 45/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index ef5aafb22..940cf0d68 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -91,7 +91,7 @@ When authorization is required and not yet proven by the client, servers **MUST* *HTTP 401 Unauthorized*. A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with information about -the issuer that the server is using to authenticate in the following format: +the Authorization Server's issuer URL that the MCP Server is using in the following format: `WWW-Authenticate: Bearer realm="default", issuer="https://authserver.example",` `scope="mcp_access_tool1", resource="https://mcp-server.example"` From 77e12928a7e82f9d66831f62cb073278479297a8 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 15:11:48 -0700 Subject: [PATCH 46/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 940cf0d68..c3e706a44 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -90,7 +90,7 @@ won't require individual registration per client:server pair. When authorization is required and not yet proven by the client, servers **MUST** respond with *HTTP 401 Unauthorized*. -A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with information about +A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with the Authorization Server's issuer URL that the MCP Server is using in the following format: `WWW-Authenticate: Bearer realm="default", issuer="https://authserver.example",` From 1b53a4a7f58ceb637f3e754666f96d2dd81798cf Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 15:27:19 -0700 Subject: [PATCH 47/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 65910dd00..69d56a9fd 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -31,9 +31,7 @@ This document **does not discuss server-to-server authorization patterns**. primarily through pre-registration. 1. **User Authentication is not a MCP Server concern.** The MCP server can guide the client to the AS but will not be responsible for authenticating the user and obtaining credential - artifacts for the user. The MCP server might transform incoming credential artifacts, like tokens, but - it does not do any kind of exchange for the user in the client, nor does the MCP server have access - to any user authentication credentials or protocols. + artifacts for the user. 1. **We focus on OAuth 2.1, with room for extensibility for other providers/specifications.** Our running assumption is that most developers will want to use OAuth 2.1, however in the long-run unusual cases for authentication and authorization may emerge (e.g., mTLS, Kerberos), which will From 322e71408cde96294d30acdabbf9fa4530a75f6c Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:48:29 -0700 Subject: [PATCH 48/98] DPoP as optional --- .../2025-03-26/basic/authorization.mdx | 29 ++++++++++++------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 49226e853..c175ac8ad 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -57,7 +57,7 @@ selected subset of their features to ensure security and interoperability while ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) - OAuth 2.0 Dynamic Client Registration Protocol ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) -- OAuth 2.0 Demonstrating Proof of Possession (DPoP) +- OAuth 2.0 Demonstrating Proof of Possession (DPoP) for supporting clients ([RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449)) - Resource Indicators for OAuth 2.0 ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html)) @@ -91,11 +91,19 @@ When authorization is required and not yet proven by the client, servers **MUST* A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with the Authorization Server's issuer URL that the MCP Server is using in the following format: -`WWW-Authenticate: Bearer realm="default", issuer="https://authserver.example",` -`scope="mcp_access_tool1", resource="https://mcp-server.example"` -`WWW-Authenticate: DPoP realm="default", issuer="https://authserver.example",` -`scope="mcp_access_tool1", resource="https://mcp-server.example",` -`algs="ES256 PS256"` +```http +WWW-Authenticate: Bearer realm="default", issuer="https://authserver.example", +scope="mcp_access_tool1", resource="https://mcp-server.example" +``` + +If the client supports DPoP and the authorization servers wants to require DPoP, the +response **MUST** follow this format: + +```http +WWW-Authenticate: DPoP realm="default", issuer="https://authserver.example", +scope="mcp_access_tool1", resource="https://mcp-server.example", +algs="ES256 PS256" +``` An MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of issuers discovered this way (to prevent phishing). For example, an MCP client could prompt the user "Do you @@ -112,7 +120,7 @@ An MCP client **MUST** check the `resource` identifier against the hostname of t client **MUST** send the `resource` identifier to the OAuth Provider, following [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html). -An MCP client **SHOULD** implement Demonstrating Proof of Possession (DPoP) and use it to the extent +An MCP client **MAY** implement Demonstrating Proof of Possession (DPoP) and use it to the extent supported by the OAuth Provider. See [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449). @@ -369,8 +377,8 @@ flowchart TD 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) or -[DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) requirements for resource -requests. Specifically: +[DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) (if client +supports DPoP) requirements for resource requests. Specifically: MCP client **MUST** use the `Authorization` request header field and **MUST NOT** use URI query string to transport Tokens [OAuth Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): @@ -380,7 +388,8 @@ Authorization: Bearer ``` or -[DPoP Section 7.1](https://datatracker.ietf.org/doc/html/rfc9449#name-the-dpop-authentication-sch): +[DPoP Section 7.1](https://datatracker.ietf.org/doc/html/rfc9449#name-the-dpop-authentication-sch) +(if client supports DPoP): ```http Authorization: DPoP From 613cff37845f5b21513f2b50056aea24fbdcd203 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:49:09 -0700 Subject: [PATCH 49/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index c175ac8ad..c46c18e32 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -190,7 +190,7 @@ The third-party authorization flow comprises these steps: 1. MCP client requests data from the MCP server. 1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the `issuer`, `scope`, and `resource`. -1. MCP client retrieves the `/authorize` endpoint from the `issuer` metadata document. +1. MCP client retrieves the `authorization_endpoint` from the `issuer` metadata document. 1. MCP client redirects user to authorization server's `/authorize` endpoint. MCP client uses `scope` and `resource` parameters provided in the `WWW-Authenticate` header in the `/authorize` URL. 1. User authorizes with authorization server with `scope` and `resource`. From 332b4b6d090dca09ff10a0b1654dc326e4ff1296 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:49:22 -0700 Subject: [PATCH 50/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index c46c18e32..4d343adbb 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -209,7 +209,7 @@ sequenceDiagram MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate - Note over MC: MCP Client retrieves /authorize endpoint URI from the issuer metadata document (Section 2.3) + Note over MC: MCP Client retrieves authorization endpoint from the issuer metadata document (Section 2.3) MC-->>UA: Initiate authorization request at /authorize Note over UA: User authenticates and authorizes client for scope and resource UA->>MC: Return auth code to client From 02449b71b8cc763be00ab72ba3bbff79ccfb3e8e Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:49:34 -0700 Subject: [PATCH 51/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 4d343adbb..1dab80c9e 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -214,7 +214,7 @@ sequenceDiagram Note over UA: User authenticates and authorizes client for scope and resource UA->>MC: Return auth code to client MC->>AUTHZS: Exchange code for token - AUTHZS-->>MC: Third-party access token + AUTHZS-->>MC: Access token MC->>MC: Cache token ``` From c8fa24aff53056849eda17917b8651645236c8af Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:51:21 -0700 Subject: [PATCH 52/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 1dab80c9e..f9ca9e57e 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -212,7 +212,7 @@ sequenceDiagram Note over MC: MCP Client retrieves authorization endpoint from the issuer metadata document (Section 2.3) MC-->>UA: Initiate authorization request at /authorize Note over UA: User authenticates and authorizes client for scope and resource - UA->>MC: Return auth code to client + UA->>MC: Return authorization code to client MC->>AUTHZS: Exchange code for token AUTHZS-->>MC: Access token MC->>MC: Cache token From 8b1b76a71bd7d4fdc9be5c2efed4eb4506e67614 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:51:33 -0700 Subject: [PATCH 53/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index f9ca9e57e..9a1714408 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -210,7 +210,7 @@ sequenceDiagram MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate Note over MC: MCP Client retrieves authorization endpoint from the issuer metadata document (Section 2.3) - MC-->>UA: Initiate authorization request at /authorize + MC-->>UA: Initiate authorization request at the authorization endpoint Note over UA: User authenticates and authorizes client for scope and resource UA->>MC: Return authorization code to client MC->>AUTHZS: Exchange code for token From b9a38884aa5599a9c7055bf217f8efa011ee009f Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:51:43 -0700 Subject: [PATCH 54/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 9a1714408..60bc90d80 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -192,7 +192,7 @@ The third-party authorization flow comprises these steps: `issuer`, `scope`, and `resource`. 1. MCP client retrieves the `authorization_endpoint` from the `issuer` metadata document. 1. MCP client redirects user to authorization server's `/authorize` endpoint. MCP client uses `scope` and - `resource` parameters provided in the `WWW-Authenticate` header in the `/authorize` URL. + `resource` parameters provided in the `WWW-Authenticate` header in the authorization URL. 1. User authorizes with authorization server with `scope` and `resource`. 1. Authorization server redirects back to MCP client with authorization code. 1. MCP client exchanges the code for the requested tokens. From 2b351043abc1af48daae385425490a6d3512a965 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:54:51 -0700 Subject: [PATCH 55/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Aaron Parecki --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 60bc90d80..c21d44a9d 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -191,7 +191,7 @@ The third-party authorization flow comprises these steps: 1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the `issuer`, `scope`, and `resource`. 1. MCP client retrieves the `authorization_endpoint` from the `issuer` metadata document. -1. MCP client redirects user to authorization server's `/authorize` endpoint. MCP client uses `scope` and +1. MCP client redirects user to authorization server's authorization endpoint. MCP client uses `scope` and `resource` parameters provided in the `WWW-Authenticate` header in the authorization URL. 1. User authorizes with authorization server with `scope` and `resource`. 1. Authorization server redirects back to MCP client with authorization code. From 7686bc357b3b87b86c5673e6dda4831dd067324e Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:55:59 -0700 Subject: [PATCH 56/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index c21d44a9d..4d2ef0357 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -180,9 +180,6 @@ additional gestures that are not captured by the specification. MCP servers **MUST NOT** complete PKCE or other public client flows on behalf of the client. -MCP servers that **MUST** implement the [metadata discovery process](#23-server-metadata-discovery) -if they do not use a third-party authorization server. - #### 2.4.2 Flow Description The third-party authorization flow comprises these steps: From 22f88b56d3f1bbfb42f0c2eb8ac0d575d2d4785f Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:57:05 -0700 Subject: [PATCH 57/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 4d2ef0357..bda798e24 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -140,8 +140,8 @@ For MCP server capability discovery: - MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct the metadata endpoint from that issuer identifier. -- MCP servers **SHOULD** use a third-party authorization server and include its issuer in - error responses. +- MCP servers **SHOULD** use an existing authorization server and include its issuer in + error responses, rather than implement their own. - MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity providers. - Authorization Servers **MUST** support From 48d759df565c2875ac5049623ece35b9abe05e88 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 17:58:42 -0700 Subject: [PATCH 58/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index bda798e24..cd365cf01 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -140,10 +140,9 @@ For MCP server capability discovery: - MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct the metadata endpoint from that issuer identifier. -- MCP servers **SHOULD** use an existing authorization server and include its issuer in - error responses, rather than implement their own. -- MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of identity - providers. +- MCP servers **SHOULD** include the authorization server issuer in error responses. +- MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of authorization + servers. - Authorization Servers **MUST** support [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) - MCP servers **MUST** respond to an unauthorized request with a `WWW-Authenticate` header containing From ae22cb8dc293438c223df3f23b4947620e749877 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 21:15:50 -0700 Subject: [PATCH 59/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Max Gerber <89937743+max-stytch@users.noreply.github.com> --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index cd365cf01..163df4cde 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -93,7 +93,7 @@ the Authorization Server's issuer URL that the MCP Server is using in the follow ```http WWW-Authenticate: Bearer realm="default", issuer="https://authserver.example", -scope="mcp_access_tool1", resource="https://mcp-server.example" +scope="mcp:read mcp:write", resource="https://mcp-server.example" ``` If the client supports DPoP and the authorization servers wants to require DPoP, the From 2651fbe63ec27f350925c4235d99095cf37d8ec1 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Tue, 8 Apr 2025 21:16:03 -0700 Subject: [PATCH 60/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Max Gerber <89937743+max-stytch@users.noreply.github.com> --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 163df4cde..e8d39c00b 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -101,7 +101,7 @@ response **MUST** follow this format: ```http WWW-Authenticate: DPoP realm="default", issuer="https://authserver.example", -scope="mcp_access_tool1", resource="https://mcp-server.example", +scope="mcp:read mcp:write", resource="https://mcp-server.example", algs="ES256 PS256" ``` From ee6612323323a4665494bbb46502f969aeaf4846 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 14:15:38 -0700 Subject: [PATCH 61/98] Move to PRM --- .../2025-03-26/basic/authorization.mdx | 279 ++++++++++-------- 1 file changed, 149 insertions(+), 130 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index cd365cf01..d9fb05823 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -9,7 +9,7 @@ title: Authorization ### 1.1 Purpose and Scope The Model Context Protocol provides authorization capabilities at the transport level, enabling MCP -clients to make requests to restricted MCP servers on behalf of resource owners. This specification +clients to make requests to protected MCP servers on behalf of resource owners. This specification defines the authorization flow for HTTP-based transports. The scope of this document is **user authorization** - how a client can authenticate a user to access a @@ -21,7 +21,7 @@ This document **does not discuss server-to-server authorization patterns**. ### 1.2 Baseline tenets 1. **MCP server developers are not security experts**. Developers should not be building their own - authorization servers unless absolutely necessary. This also introduces room for serious mistakes + authorization servers unless absolutely necessary. This introduces room for serious mistakes that can lead to compromise. 1. **MCP clients are Authorization Server (AS)-agnostic**. We do not and will not expect clients to be "enlightened" in any capacity to support a protected MCP server. This will fragment the ecosystem. @@ -33,7 +33,7 @@ This document **does not discuss server-to-server authorization patterns**. to the AS but will not be responsible for authenticating the user and obtaining credential artifacts for the user. 1. **We focus on OAuth 2.1, with room for extensibility for other providers/specifications.** Our - running assumption is that most developers will want to use OAuth 2.1, however in the long-run + guiding assumption is that most developers will want to use OAuth 2.1, however in the long-run unusual cases for authentication and authorization may emerge (e.g., mTLS, Kerberos), which will need clients to be extensible. @@ -43,7 +43,7 @@ Authorization is **OPTIONAL** for MCP implementations. When supported: - Streamable HTTP or SSE transports **SHOULD** conform to this specification. - Implementations using an STDIO transport **SHOULD NOT** follow this specification and instead - retrieve credentials from the environment. + retrieve credentials from the execution environment. - Implementations using alternative transports **MUST** follow established security best practices for their protocol. @@ -56,14 +56,16 @@ selected subset of their features to ensure security and interoperability while - OAuth 2.0 Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)) - OAuth 2.0 Dynamic Client Registration Protocol - ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) -- OAuth 2.0 Demonstrating Proof of Possession (DPoP) for supporting clients + ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) +- OAuth 2.0 Protected Resource Metadata + ([RFC DRAFT](https://datatracker.ietf.org/doc/draft-ietf-oauth-resource-metadata/13/)) +- OAuth 2.0 Demonstrating Proof of Possession (DPoP), for supporting clients ([RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449)) - Resource Indicators for OAuth 2.0 ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html)) -This specification **DOES NOT** require MCP server developers to implement their own Authorization Server -and instead relies on developers adopting dedicated and well-tested third-party AS implementations. +This specification **DOES NOT** require MCP server developers to implement their own authorization server (AS) +and instead relies on developers adopting dedicated and well-tested AS implementations. This specification also enables existing deployments to leverage their current infrastructure. As a side-effect, this also simplifies consent flows, and services that have multiple MCP Servers @@ -83,70 +85,73 @@ won't require individual registration per client:server pair. 3. Authorization servers **SHOULD** implement and MCP clients **MUST** consume OAuth 2.0 Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414)). +4. MCP servers **MUST** implement and support Auth 2.0 Protected Resource Metadata + ([RFC DRAFT](https://datatracker.ietf.org/doc/draft-ietf-oauth-resource-metadata/13/)). + ### 2.2 Client OAuth 2.1 Authorization When authorization is required and not yet proven by the client, servers **MUST** respond with -*HTTP 401 Unauthorized*. +`HTTP 401 Unauthorized`. -A *HTTP 401 Unauthorized* response **MUST** include a `WWW-Authenticate` header with -the Authorization Server's issuer URL that the MCP Server is using in the following format: +A `HTTP 401 Unauthorized` response **MUST** include a `WWW-Authenticate` header with +the URL to the protected resource metadata document hosted by the MCP Server in +the following format: ```http -WWW-Authenticate: Bearer realm="default", issuer="https://authserver.example", -scope="mcp_access_tool1", resource="https://mcp-server.example" +WWW-Authenticate: Bearer error="invalid_request", + error_description="No access token was provided in this request", + resource_metadata="https://resource.example.com/.well-known/oauth-protected-resource" ``` -If the client supports DPoP and the authorization servers wants to require DPoP, the -response **MUST** follow this format: +A MCP server **MUST** host its Protected Resource Metadata (PRM) document, as outlined in +[Section 3 of the RFC draft](https://www.ietf.org/archive/id/draft-ietf-oauth-resource-metadata-13.html#section-3). -```http -WWW-Authenticate: DPoP realm="default", issuer="https://authserver.example", -scope="mcp_access_tool1", resource="https://mcp-server.example", -algs="ES256 PS256" -``` +A MCP server **MUST** include its AS configuration in the PRM document as outlined in +[Section 2 of the RFC draft](https://www.ietf.org/archive/id/draft-ietf-oauth-resource-metadata-13.html#section-2). + +A MCP client **MUST** issue a `GET` request to the URL in `resource_metadata` to get information about +the AS. + +A MCP client **MUST** verify that the `resource` value in the PRM document matches the MCP server +fully-qualified domain name. -An MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of issuers -discovered this way (to prevent phishing). For example, an MCP client could prompt the user "Do you +A MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of AS +discovered through the PRM document to prevent phishing. For example, an MCP client could prompt the user "Do you want to login with `https://authserver.example`?" -An MCP client **MUST** use the `issuer` identifier to construct the OAuth 2.0 metadata discovery -document path, following +A MCP client **MUST** use `authorization_servers` values from the PRM document to construct +the OAuth 2.0 metadata discovery document path, following [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414#section-3). -An MCP client **MAY** use the `registration_endpoint` to register itself with OAuth Provider. An MCP -client **MAY** also be pre-registered with an OAuth Provider. +A MCP client **MAY** use the AS-provided registration endpoint to register itself with the AS. -An MCP client **MUST** check the `resource` identifier against the hostname of the MCP server. An MCP -client **MUST** send the `resource` identifier to the OAuth Provider, following -[RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html). +A MCP client **MAY** be pre-registered with an AS and not require dynamic registration. -An MCP client **MAY** implement Demonstrating Proof of Possession (DPoP) and use it to the extent -supported by the OAuth Provider. See +A MCP client **MAY** implement Demonstrating Proof of Possession (DPoP) and use it to the extent +supported by the AS. See [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449). -Clients initiate an +A MCP clients **MUST** initiate an [OAuth 2.1 (draft)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization flow after receiving a *HTTP 401 Unauthorized* response. ### 2.3 MCP Server Metadata Discovery -MCP servers **MUST** return the fully-qualified domain name of the issuer in `WWW-Authenticate` -headers in an error respose. +MCP servers **MUST** return the full path to their PRM document in the `WWW-Authenticate` header +with a `HTTP 401 Unauthorized` response, following the format outlined in +[Section 2.2](#22-client-oauth-21-authorization). MCP servers **MUST** follow [RFC 6750 Section 3.1](https://www.rfc-editor.org/rfc/rfc6750#section-3.1) for any authorization failures. For MCP server capability discovery: -- MCP clients **MUST** parse the `WWW-Authenticate` response to discover the issuer URL, and construct - the metadata endpoint from that issuer identifier. -- MCP servers **SHOULD** include the authorization server issuer in error responses. +- MCP clients **MUST** parse the `WWW-Authenticate` response to discover the path to the PRM document. +- MCP servers **SHOULD** include the PRM document path in error responses. - MCP clients **SHOULD** evaluate or enable the user to evaluate the trustworthiness of authorization - servers. -- Authorization Servers **MUST** support + servers they are connecting to. +- Authorization servers **MUST** support [OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) -- MCP servers **MUST** respond to an unauthorized request with a `WWW-Authenticate` header containing - `issuer`, `scope`, and `resource` identifiers. The discovery flow is illustrated below: @@ -154,13 +159,18 @@ The discovery flow is illustrated below: sequenceDiagram participant MC as MCP Client participant MS as MCP Server - participant AUTHZS as Authorization Server + participant AS as Authorization Server MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate - MC->>MC: Construct metadata endpoint from issuer identifier - - Note over MC: Continue with authorization flow + MC->>MS: Fetch PRM document + MS-->>MC: PRM document response + Note over MC: Validate PRM document
metadata + Note over MC: Build AS metadata URL + MC->>AS: Fetch AS metadata + AS-->>MC: AS metadata response + + Note over MC,AS: Continue with authorization flow ``` #### 2.3.1 Server Metadata Discovery Headers @@ -168,32 +178,38 @@ sequenceDiagram 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. -For example: `MCP-Protocol-Version: 2024-11-05` +For example: + +```http +MCP-Protocol-Version: 2024-11-05 +``` ### 2.4 Authorization server integration #### 2.4.1 Overview MCP servers **MAY** override endpoints on an as-needed basis if the authorization server requires -additional gestures that are not captured by the specification. +additional gestures that are not captured by the specification. This requires servers to become an AS +and host all related metadata. -MCP servers **MUST NOT** complete PKCE or other public client flows on behalf of the client. +MCP servers **MUST NOT** complete PKCE or other public client flows on behalf of the MCP client. #### 2.4.2 Flow Description The third-party authorization flow comprises these steps: 1. MCP client requests data from the MCP server. -1. MCP server responds with *HTTP 401 Unauthorized* and `WWW-Authenticate` header containing the - `issuer`, `scope`, and `resource`. -1. MCP client retrieves the `authorization_endpoint` from the `issuer` metadata document. -1. MCP client redirects user to authorization server's authorization endpoint. MCP client uses `scope` and - `resource` parameters provided in the `WWW-Authenticate` header in the authorization URL. -1. User authorizes with authorization server with `scope` and `resource`. +1. MCP server responds with `HTTP 401 Unauthorized` and `WWW-Authenticate` header containing the + URL to the PRM document. +1. MCP client retrieves and validates the PRM document. +1. MCP client retrieves the AS endpoint from the PRM document. +1. MCP client redirects user to the AS authorization endpoint. MCP client can include scopes that + are defined in the PRM document or other scopes, as supported by the MCP server. +1. User authorizes with authorization server. 1. Authorization server redirects back to MCP client with authorization code. 1. MCP client exchanges the code for the requested tokens. -1. MCP client caches the token. -1. MCP clients can now request data from the MCP server with the token attached in the `Authorization` +1. MCP client stores the token. +1. MCP client can now request data from the MCP server with the token attached in the `Authorization` header. ```mermaid @@ -201,64 +217,72 @@ sequenceDiagram participant UA as User-Agent (Browser) participant MC as MCP Client participant MS as MCP Server - participant AUTHZS as Authorization Server + participant AS as Authorization Server MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate - Note over MC: MCP Client retrieves authorization endpoint from the issuer metadata document (Section 2.3) + Note over MC: MCP Client retrieves and validates
PRM document + Note over MC: MCP Client retrieves authorization
endpoint from AS metadata document
(Section 2.3) MC-->>UA: Initiate authorization request at the authorization endpoint - Note over UA: User authenticates and authorizes client for scope and resource + Note over UA: User authenticates and authorizes
client for scope and resource UA->>MC: Return authorization code to client - MC->>AUTHZS: Exchange code for token - AUTHZS-->>MC: Access token + MC->>AS: Exchange code for token + AS-->>MC: Access token MC->>MC: Cache token ``` -#### 2.4.3 Session Binding Requirements +#### 2.4.3 Implementing custom authorization servers + +MCP servers **MAY** implement their own AS. -MCP servers integrating with third-party authorization services **MUST**: +MCP servers that implement their own AS **MUST** host appropriate AS metadata, as outlined in +[RFC 8414 Section 3](https://datatracker.ietf.org/doc/html/rfc8414#section-3). -1. Maintain secure mapping between third-party tokens and issued client sessions. -2. Validate third-party token status before honoring MCP tokens. +MCP servers that implement their own AS **MUST**: + +1. Maintain secure mapping between third-party tokens and issued client sessions, if used. +2. Validate token status before granting any data access. 3. Implement appropriate token lifecycle management. 4. Provide appropriate responses to the client if re-authentication is needed. Please refer to [RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol](https://www.rfc-editor.org/rfc/rfc9470.html). #### 2.4.4 Security Considerations -When implementing authorization with an existing authorization server, MCP servers **MUST**: +When implementing authorization with an existing AS, MCP servers **MUST**: 1. Request the minimum number of required scopes. -2. Securely store any credential artifacts obtained from the client and/or the authorization server. +2. Securely store any tokens obtained from the client and/or the authorization server. 3. Implement appropriate session timeout handling. 4. Consider security implications of token chaining. 5. Implement proper error handling for authorization failures. MCP clients **MUST**: -1. Securely store Access and Refresh Tokens received from the authorization server. +1. Securely store Access and Refresh Tokens received from the AS. 2. Properly handle requests to re-authenticate users with expired or invalid tokens (using the Refresh Token grant) or due to challenges (refer to [RFC 9470](https://www.rfc-editor.org/rfc/rfc9470.html)). -3. Verify that the resource identifier returned matches the FQDN of the MCP server. -4. Forward the resource identifier returns as `resource` parameter according to - [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html). +3. Verify that the `resource` identifier in the PRM document matches the MCP server. Authorization servers **MUST**: 1. Verify that the resource identifier is registered for the audience of the access token issued. -### 2.5 Implementing server overrides +### 2.5 Implementing authorization server overrides + +In certain scenarios, AS might have limited capability support, such as no dynamic client registration, and +MCP server developers may choose to implement those capabilities themselves. + +In this scenario, the server **MUST** return its fully-qualified domain name as the AS in the PRM document, +that will be linked from the `WWW-Authenticate` header in the `HTTP 401 Unauthorized` response. -In certain scenarios, authorization servers might have limited capability support and MCP server -developers may choose to supplement those with their own implementation. In this scenario, the server -**MUST** return its fully-qualified domain name as the `issuer` in the *HTTP 401 Unauthorized* -response, included in the `WWW-Authenticate` header. +The MCP server will need to be configured in accordance with +[Section 2.4.3](#243-implementing-custom-authorization-servers) to act as an AS. #### 2.5.1 Discovery of server-driven overrides -Under all circumstances, the server **MUST** return a `WWW-Authenticate` with `issuer` information, -even if the server provides its own metadata document that overrides Authorization Server endpoints +Under all circumstances, the server **MUST** return a `WWW-Authenticate` with PRM document information, +even if the server provides its own metadata document that overrides AS endpoints (such as `/authorize`, `/token`, or `/register`). ### 2.6 Dynamic Client Registration @@ -278,9 +302,12 @@ provide the `software_id` and `software_version` parameters, as defined in the [Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) section of [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591). -MCP clients with mass audiences will *generally* want to pre-register and hardcode client IDs. Some -authorization servers (such as Google and Microsoft) limit the functionality of dynamically registered -clients. An MCP client could contain a config for common issuers like: +MCP clients with mass audiences will *generally* want to pre-register and hardcode client IDs. + +Some authorization servers (such as Google and Microsoft) limit the functionality of dynamically +registered clients. + +An MCP client **MAY** contain a configuration for common issuers, such as: ```json [ @@ -301,44 +328,46 @@ sequenceDiagram participant UA as User-Agent (Browser or App/Broker) participant MC as MCP Client participant MS as MCP Server - participant AUTHZS as Authorization Server + participant AS as Authorization Server MC->>MS: Request data MS-->>MC: 401 Unauthorized with WWW-Authenticate - MC->>MC: Construct metadata document path - alt Supports authorization server - MC->>AUTHZS: GET /.well-known/oauth-authorization-server - AUTHZS-->>MC: Return endpoint metadata - else Partial or no authorization server support + MC->>MS: Fetch PRM document + MS-->>MC: PRM document response + Note over MC: Validate PRM document
metadata + Note over MC: Build AS metadata URL + MC->>AS: Fetch AS metadata + AS-->>MC: AS metadata response + + alt External authorization server + MC->>AS: GET /.well-known/oauth-authorization-server + AS-->>MC: 200 OK + Metadata Document + Note over MC: Use endpoints from metadata + else Co-located authorization server MC->>MS: GET /.well-known/oauth-authorization-server - alt Discovery success - MS-->>MC: 200 OK + Metadata Document - Note over MC: Use endpoints from metadata - else Discovery failed - MS-->>MC: 404 Not Found - Note over MC: Fall back to default endpoints - end + MS-->>MC: 200 OK + Metadata Document + Note over MC: Use endpoints from metadata end alt Client is pre-registered with the authorization server else Authorization server supports dynamic client registration - MC->>AUTHZS: Request client registration - AUTHZS-->>MC: Confirm client registration + MC->>AS: Request client registration + AS-->>MC: Confirm client registration else Authorization server does not support dynamic client registration MC->>MS: Request client registration - MS->>AUTHZS: Register client - AUTHZS-->>MS: Return client registration + MS->>AS: Register client + AS-->>MS: Return client registration MS-->>MC: Return client registration end Note over MC: Generate PKCE artifacts MC-->>UA: Initiate authorization call - Note over UA: User authenticates and authorizes client for scope and resource + Note over UA: User authenticates and authorizes
client for scope and resource UA->>MC: Return auth code to client - MC->>AUTHZS: Exchange auth code for tokens - AUTHZS-->>MC: Return tokens - MC->>MC: Cache tokens + MC->>AS: Exchange auth code for tokens + AS-->>MC: Return tokens + Note over MC: Store tokens Note over MC, MS: Begin standard MCP message exchange ``` @@ -346,25 +375,25 @@ sequenceDiagram ```mermaid flowchart TD - A[Start Authorization Flow] --> AA[Get authority] - AA-->B{Check Metadata Discovery} - B -->|Available| C[Use Metadata Endpoints] - B -->|Not Available| D[Use Default Endpoints] + A[Start Authorization Flow] --> P[Get PRM document] + P --> Q[Validate PRM document] + Q --> AA[Get AS URL] + AA-->B[Get metadata document] + B -->C[Use metadata-declared endpoints] - C --> G{Check Registration Endpoint} - D --> G + C --> G{Check registration endpoint} - G -->|Available| H[Perform Dynamic Registration] - G -->|Not Available| I[Alternative Registration Required] + G -->|Available| H[Perform dynamic client registration] + G -->|Not available| I[Alternative client registration required] - H --> J[Start OAuth Flow] + 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] + 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.8 Access Token Usage @@ -374,7 +403,7 @@ flowchart TD 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) or [DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) (if client -supports DPoP) requirements for resource requests. Specifically: +supports DPoP) requirements for resource requests. MCP client **MUST** use the `Authorization` request header field and **MUST NOT** use URI query string to transport Tokens [OAuth Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): @@ -392,8 +421,8 @@ Authorization: DPoP DPoP: ``` -Note that authorization **MUST** be included in every HTTP request from client to server, even if they -are part of the same logical session. +Note that `Authorization` header **MUST** be included in every HTTP request from client to server, +even if they are part of the same logical session. #### 2.8.2 Token Handling @@ -447,18 +476,8 @@ We strongly recommend that local clients implement OAuth 2.1 as a public client: 3. Following token refresh best practices to maintain sessions. 4. Properly handling token expiration and renewal. -### 3.2 Authorization Metadata Discovery - -We strongly recommend that all clients implement metadata discovery. This reduces the need for users -to provide endpoints manually or clients to fallback to the defined defaults. - -### 3.3 Dynamic Client Registration +### 3.2 Dynamic Client Registration Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation of dynamic client registration. This allows applications to automatically register with the MCP server, and removes the need for users to obtain client IDs manually. - -### 3.4 Using delegated authorization - -MCP servers **SHOULD** support delegated authorization through third-party authorization servers -instead of implementing their own. From cef00aa0230acb118777c89b70bfc36913024c5a Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 14:19:55 -0700 Subject: [PATCH 62/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index d9fb05823..bac9bfc32 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -192,7 +192,8 @@ MCP servers **MAY** override endpoints on an as-needed basis if the authorizatio additional gestures that are not captured by the specification. This requires servers to become an AS and host all related metadata. -MCP servers **MUST NOT** complete PKCE or other public client flows on behalf of the MCP client. +MCP servers **MUST NOT** complete public client flows on behalf of the MCP client (e.g., take authorization +codes and exchange them for tokens with a public client ID, and then pass the tokens back to the client). #### 2.4.2 Flow Description From 636d8f10a19609235edb288bc36cab3e784538fb Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 14:58:56 -0700 Subject: [PATCH 63/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 100 +++++++++++++----- 1 file changed, 75 insertions(+), 25 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index bac9bfc32..370ca47d1 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -232,21 +232,6 @@ sequenceDiagram MC->>MC: Cache token ``` -#### 2.4.3 Implementing custom authorization servers - -MCP servers **MAY** implement their own AS. - -MCP servers that implement their own AS **MUST** host appropriate AS metadata, as outlined in -[RFC 8414 Section 3](https://datatracker.ietf.org/doc/html/rfc8414#section-3). - -MCP servers that implement their own AS **MUST**: - -1. Maintain secure mapping between third-party tokens and issued client sessions, if used. -2. Validate token status before granting any data access. -3. Implement appropriate token lifecycle management. -4. Provide appropriate responses to the client if re-authentication is needed. Please refer to - [RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol](https://www.rfc-editor.org/rfc/rfc9470.html). - #### 2.4.4 Security Considerations When implementing authorization with an existing AS, MCP servers **MUST**: @@ -269,7 +254,63 @@ Authorization servers **MUST**: 1. Verify that the resource identifier is registered for the audience of the access token issued. -### 2.5 Implementing authorization server overrides +### 2.5 Delegated authorization or colocated AS flows + +In limited scenarios, MCP servers **MAY** implement their own AS, refer to as a _colocated AS_ due +to the MCP server _colocating_ itself, the resource server (RS) with the AS. + +MCP servers that implement their own AS **MUST** host appropriate AS metadata, as outlined in +[RFC 8414 Section 3](https://datatracker.ietf.org/doc/html/rfc8414#section-3). + +MCP servers **MAY** support delegated authorization through third-party AS. +In this flow, the MCP server acts as both an OAuth client (to the external AS) and an OAuth +AS (to the MCP client). + +#### 2.5.1 Flow description + +The delegated 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 UA as User-Agent (Browser) + participant MC as MCP Client + participant MS as MCP Server + participant T as Third-Party Auth Server + + MC->>MS: Initial OAuth Request + MS->>UA: Redirect to Third-Party /authorize + UA->>T: Authorization Request + Note over T: User authorizes + T->>UA: Redirect to MCP Server callback + UA->>MS: Authorization code + MS->>T: Exchange code for token + T->>MS: Third-party access token + Note over MS: Generate bound MCP token + MS->>UA: Redirect to MCP Client callback + UA->>MC: MCP authorization code + MC->>MS: Exchange code for token + MS->>MC: MCP access token +``` + +#### 2.5.2 Special considerations + +MCP servers that use delegated authorization or implement a colocated AS **MUST**: + +1. Maintain secure mapping between third-party tokens and issued client sessions, if used. +2. Validate token status before granting any data access. +3. Implement appropriate token lifecycle management. +4. Provide appropriate responses to the client if re-authentication is needed. Please refer to + [RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol](https://www.rfc-editor.org/rfc/rfc9470.html). + +### 2.6 Implementing authorization server overrides In certain scenarios, AS might have limited capability support, such as no dynamic client registration, and MCP server developers may choose to implement those capabilities themselves. @@ -280,13 +321,13 @@ that will be linked from the `WWW-Authenticate` header in the `HTTP 401 Unauthor The MCP server will need to be configured in accordance with [Section 2.4.3](#243-implementing-custom-authorization-servers) to act as an AS. -#### 2.5.1 Discovery of server-driven overrides +#### 2.6.1 Discovery of server-driven overrides Under all circumstances, the server **MUST** return a `WWW-Authenticate` with PRM document information, even if the server provides its own metadata document that overrides AS endpoints (such as `/authorize`, `/token`, or `/register`). -### 2.6 Dynamic Client Registration +### 2.7 Dynamic Client Registration MCP clients **SHOULD** support the [OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591) to @@ -320,7 +361,7 @@ An MCP client **MAY** contain a configuration for common issuers, such as: Alternatively, an MCP client could allow the user to register the MCP client and provide those details to the MCP client through a UI. -### 2.7 Authorization Flow Steps +### 2.8 Authorization flow steps The complete authorization flow proceeds as follows: @@ -372,7 +413,7 @@ sequenceDiagram Note over MC, MS: Begin standard MCP message exchange ``` -#### 2.7.1 Decision Flow Overview +#### 2.8.1 Decision Flow Overview ```mermaid flowchart TD @@ -397,9 +438,9 @@ flowchart TD N --> O[Use access token] ``` -### 2.8 Access Token Usage +### 2.9 Access Token Usage -#### 2.8.1 Token Requirements +#### 2.9.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) or @@ -425,7 +466,7 @@ DPoP: Note that `Authorization` header **MUST** be included in every HTTP request from client to server, even if they are part of the same logical session. -#### 2.8.2 Token Handling +#### 2.9.2 Token Handling Resource servers (MCP servers _or_ downstream APIs) **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). @@ -468,7 +509,16 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors: ## 3. Best Practices -### 3.1 Local clients as Public OAuth 2.1 Clients +### 3.1 Authorization servers + +Almost universally, MCP server developers should prefer integrating with existing AS (as +defined in [Section 2.4](#24-authorization-server-integration)) rather than colocate or +support delegated authoriziation (as defined in +[Section 2.5](#25-delegated-authorization-or-colocated-as-flows)). This significantly +reduces the burden on developers and reduces the risk of incorrect token handling +implementations. + +### 3.2 Local clients as Public OAuth 2.1 Clients We strongly recommend that local clients implement OAuth 2.1 as a public client: @@ -477,7 +527,7 @@ We strongly recommend that local clients implement OAuth 2.1 as a public client: 3. Following token refresh best practices to maintain sessions. 4. Properly handling token expiration and renewal. -### 3.2 Dynamic Client Registration +### 3.3 Dynamic Client Registration Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation of dynamic client registration. This allows applications to automatically register with the MCP From 5e4979b2e042d2d309f74e3467b53574c879884d Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 15:00:58 -0700 Subject: [PATCH 64/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 370ca47d1..e4ccfc398 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -127,6 +127,9 @@ A MCP client **MAY** use the AS-provided registration endpoint to register itsel A MCP client **MAY** be pre-registered with an AS and not require dynamic registration. +A MCP client **MUST** send the `resource` identifier to the AS, following +[RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html). + A MCP client **MAY** implement Demonstrating Proof of Possession (DPoP) and use it to the extent supported by the AS. See [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449). From 3f43e94fb719f98a644f0b463401201e4522dab1 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 15:08:01 -0700 Subject: [PATCH 65/98] Line cleanup --- .../2025-03-26/basic/authorization.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index e4ccfc398..243a65d37 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -116,8 +116,8 @@ A MCP client **MUST** verify that the `resource` value in the PRM document match fully-qualified domain name. A MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of AS -discovered through the PRM document to prevent phishing. For example, an MCP client could prompt the user "Do you -want to login with `https://authserver.example`?" +discovered through the PRM document to prevent phishing. For example, an MCP client could prompt +the user "Do you want to login with `https://authserver.example`?" A MCP client **MUST** use `authorization_servers` values from the PRM document to construct the OAuth 2.0 metadata discovery document path, following @@ -195,8 +195,9 @@ MCP servers **MAY** override endpoints on an as-needed basis if the authorizatio additional gestures that are not captured by the specification. This requires servers to become an AS and host all related metadata. -MCP servers **MUST NOT** complete public client flows on behalf of the MCP client (e.g., take authorization -codes and exchange them for tokens with a public client ID, and then pass the tokens back to the client). +MCP servers **MUST NOT** complete public client flows on behalf of the MCP client (e.g., take +authorization codes and exchange them for tokens with a public client ID, and then pass the tokens +back to the client). #### 2.4.2 Flow Description @@ -450,8 +451,8 @@ Access token handling **MUST** conform to [DPoP Section 7](https://datatracker.ietf.org/doc/html/rfc9449#section-7) (if client supports DPoP) requirements for resource requests. -MCP client **MUST** use the `Authorization` request header field and **MUST NOT** use URI query string to transport Tokens -[OAuth Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): +MCP client **MUST** use the `Authorization` request header field and **MUST NOT** use URI query string +to transport tokens [OAuth Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1): ```http Authorization: Bearer From d1852f332cd71512fb235d5e23ae5677c9926934 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 15:16:09 -0700 Subject: [PATCH 66/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 243a65d37..ac7b13676 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -100,12 +100,16 @@ the following format: ```http WWW-Authenticate: Bearer error="invalid_request", error_description="No access token was provided in this request", - resource_metadata="https://resource.example.com/.well-known/oauth-protected-resource" + resource_metadata="https://resource.example.com/.well-known/oauth-protected-resource", + scope="mcp:read mcp:write" ``` A MCP server **MUST** host its Protected Resource Metadata (PRM) document, as outlined in [Section 3 of the RFC draft](https://www.ietf.org/archive/id/draft-ietf-oauth-resource-metadata-13.html#section-3). +A MCP server **MUST** return a set of scopes in the `scope` parameter within the `WWW-Authenticate` header +in the initial handshake as well as in subsequent responses that require incremental authorization. + A MCP server **MUST** include its AS configuration in the PRM document as outlined in [Section 2 of the RFC draft](https://www.ietf.org/archive/id/draft-ietf-oauth-resource-metadata-13.html#section-2). From 2bf8341724f583aef44d4047046a7ea5e168e41b Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 15:47:23 -0700 Subject: [PATCH 67/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index ac7b13676..d0f0e092e 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -98,9 +98,7 @@ the URL to the protected resource metadata document hosted by the MCP Server in the following format: ```http -WWW-Authenticate: Bearer error="invalid_request", - error_description="No access token was provided in this request", - resource_metadata="https://resource.example.com/.well-known/oauth-protected-resource", +WWW-Authenticate: Bearer resource_metadata="https://resource.example.com/.well-known/oauth-protected-resource", scope="mcp:read mcp:write" ``` From a392ed6ec5e1c4a64273f224aa361be6c25d268b Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 16:20:23 -0700 Subject: [PATCH 68/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index d0f0e092e..40587cb70 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -193,10 +193,6 @@ MCP-Protocol-Version: 2024-11-05 #### 2.4.1 Overview -MCP servers **MAY** override endpoints on an as-needed basis if the authorization server requires -additional gestures that are not captured by the specification. This requires servers to become an AS -and host all related metadata. - MCP servers **MUST NOT** complete public client flows on behalf of the MCP client (e.g., take authorization codes and exchange them for tokens with a public client ID, and then pass the tokens back to the client). @@ -251,7 +247,7 @@ When implementing authorization with an existing AS, MCP servers **MUST**: MCP clients **MUST**: 1. Securely store Access and Refresh Tokens received from the AS. -2. Properly handle requests to re-authenticate users with expired or invalid tokens (using the +2. Properly handle requests to renew and replace expired or invalid tokens (using the Refresh Token grant) or due to challenges (refer to [RFC 9470](https://www.rfc-editor.org/rfc/rfc9470.html)). 3. Verify that the `resource` identifier in the PRM document matches the MCP server. From d41afdab7d8f80981c0066711a18a6d32343be01 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 16:21:35 -0700 Subject: [PATCH 69/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 40587cb70..a394bbbb2 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -12,9 +12,9 @@ The Model Context Protocol provides authorization capabilities at the transport clients to make requests to protected MCP servers on behalf of resource owners. This specification defines the authorization flow for HTTP-based transports. -The scope of this document is **user authorization** - how a client can authenticate a user to access a -server and the server determine whether to authorize the user to access its tools, resources, or any -other capabilities. +The scope of this document is **user authorization** - how a MCP client can authenticate a user +to access a MCP server and the MCP server determine whether to authorize the user to access its tools, +resources, or any other capabilities. This document **does not discuss server-to-server authorization patterns**. From 6eddb79b223b972ebf28be7f244098b9a8ece027 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 16:23:58 -0700 Subject: [PATCH 70/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index a394bbbb2..718ff4801 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -23,10 +23,11 @@ This document **does not discuss server-to-server authorization patterns**. 1. **MCP server developers are not security experts**. Developers should not be building their own authorization servers unless absolutely necessary. This introduces room for serious mistakes that can lead to compromise. -1. **MCP clients are Authorization Server (AS)-agnostic**. We do not and will not expect clients to be - "enlightened" in any capacity to support a protected MCP server. This will fragment the ecosystem. - The specification explicitly assumes that clients are not enabled in any unique way to support - specific Authorization Servers. +1. **MCP clients are Authorization Server (AS)-agnostic**. When developers build MCP servers and secure + them with an AS, they need to design them so that standard, off-the-shelf MCP clients can connect + without needing any special modifications for the server's authorization setup. + Not doing this will fragment the ecosystem. The specification explicitly assumes that clients are + not enabled in any unique way to support specific AS implementations beyond what is covered here. - **Note:** It is acceptable for clients to be enhanced for specific Authorization Servers, primarily through pre-registration. 1. **User Authentication is not a MCP Server concern.** The MCP server can guide the client From f41dd50ec9f747eadd860b8d77255567f027ff30 Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 18:37:46 -0700 Subject: [PATCH 71/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Che --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 718ff4801..150e8c529 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -141,7 +141,7 @@ A MCP clients **MUST** initiate an [OAuth 2.1 (draft)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization flow after receiving a *HTTP 401 Unauthorized* response. -### 2.3 MCP Server Metadata Discovery +### 2.3 MCP Server Authorization Metadata Discovery MCP servers **MUST** return the full path to their PRM document in the `WWW-Authenticate` header with a `HTTP 401 Unauthorized` response, following the format outlined in From 13961c45cae31550e9a3e6af6ac6016e29f5503c Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 18:40:59 -0700 Subject: [PATCH 72/98] Add OAuth 2.1 PKCE requirement for public clients --- docs/specification/2025-03-26/basic/authorization.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 150e8c529..0fea88e37 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -198,6 +198,9 @@ MCP servers **MUST NOT** complete public client flows on behalf of the MCP clien authorization codes and exchange them for tokens with a public client ID, and then pass the tokens back to the client). +Public client flows **MUST** be completed by MCP Client using OAuth 2.1 Authorization +Code Flow with PKCE. + #### 2.4.2 Flow Description The third-party authorization flow comprises these steps: From a9001e00a52c3c9162a05610043b96e5e17ac556 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 21:01:06 -0700 Subject: [PATCH 73/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 0fea88e37..77f8e7b0b 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -194,6 +194,10 @@ MCP-Protocol-Version: 2024-11-05 #### 2.4.1 Overview +MCP clients **SHOULD** be considered _public clients_ and MCP servers **MUST** be +considered _confidential clients_, as defined in +[RFC 6749 Section 2.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). + MCP servers **MUST NOT** complete public client flows on behalf of the MCP client (e.g., take authorization codes and exchange them for tokens with a public client ID, and then pass the tokens back to the client). From 8b1f6d256a941c302b8bd74beb5eeced0d5dcff8 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Wed, 9 Apr 2025 22:12:41 -0700 Subject: [PATCH 74/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 45 +++---------------- 1 file changed, 6 insertions(+), 39 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 77f8e7b0b..372fc77a5 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -276,48 +276,15 @@ MCP servers **MAY** support delegated authorization through third-party AS. In this flow, the MCP server acts as both an OAuth client (to the external AS) and an OAuth AS (to the MCP client). -#### 2.5.1 Flow description - -The delegated 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 UA as User-Agent (Browser) - participant MC as MCP Client - participant MS as MCP Server - participant T as Third-Party Auth Server - - MC->>MS: Initial OAuth Request - MS->>UA: Redirect to Third-Party /authorize - UA->>T: Authorization Request - Note over T: User authorizes - T->>UA: Redirect to MCP Server callback - UA->>MS: Authorization code - MS->>T: Exchange code for token - T->>MS: Third-party access token - Note over MS: Generate bound MCP token - MS->>UA: Redirect to MCP Client callback - UA->>MC: MCP authorization code - MC->>MS: Exchange code for token - MS->>MC: MCP access token -``` - -#### 2.5.2 Special considerations +#### 2.5.1 Special considerations MCP servers that use delegated authorization or implement a colocated AS **MUST**: -1. Maintain secure mapping between third-party tokens and issued client sessions, if used. -2. Validate token status before granting any data access. -3. Implement appropriate token lifecycle management. -4. Provide appropriate responses to the client if re-authentication is needed. Please refer to +1. Maintain secure mapping between third-party tokens and issued client sessions. +1. Never pass third-party tokens directly to the client. +1. Validate token status before granting any data access. +1. Implement appropriate token lifecycle management. +1. Provide appropriate responses to the client if re-authentication is needed. Please refer to [RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol](https://www.rfc-editor.org/rfc/rfc9470.html). ### 2.6 Implementing authorization server overrides From 2849c58d8c814ff9654665611ef5932f3d8d5caf Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Thu, 10 Apr 2025 10:53:30 -0700 Subject: [PATCH 75/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 372fc77a5..8df3ab346 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -296,7 +296,7 @@ In this scenario, the server **MUST** return its fully-qualified domain name as that will be linked from the `WWW-Authenticate` header in the `HTTP 401 Unauthorized` response. The MCP server will need to be configured in accordance with -[Section 2.4.3](#243-implementing-custom-authorization-servers) to act as an AS. +[Section 2.5](#25-delegated-authorization-or-colocated-as-flows) to act as an AS. #### 2.6.1 Discovery of server-driven overrides From 1c6e48b68276ee15c20d397040ee2e844aa0d197 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Thu, 10 Apr 2025 11:51:43 -0700 Subject: [PATCH 76/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 8df3ab346..fef38d468 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -481,8 +481,8 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors: 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. +3. Token rotation **MUST** be implemented for enhanced security. +4. Token lifetimes **MUST** be limited based on security requirements. ## 3. Best Practices From bc53f0d025208306f195424b462edb9e0bfe64aa Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Fri, 11 Apr 2025 15:51:55 -0700 Subject: [PATCH 77/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 24 ++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index fef38d468..f687d43a8 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -141,6 +141,26 @@ A MCP clients **MUST** initiate an [OAuth 2.1 (draft)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization flow after receiving a *HTTP 401 Unauthorized* response. +### 2.2.1 OAuth Grant Types + +OAuth specifies different flows or grant types, which are different ways of obtaining an +access token. Each of these targets different use cases and scenarios. + +MCP servers **SHOULD** support the OAuth grant types that best align with the intended +audience. For instance: + +1. Authorization Code: useful when the client is acting on behalf of a (human) end user. + - For instance, an agent calls an MCP tool implemented by a SaaS system. +2. Client Credentials: the client is another application (not a human) + - For instance, an agent calls a secure MCP tool to check inventory at a specific + store. No need to impersonate the end user. + +MCP clients **MUST** support authorization code flow with PKCE, per +OAuth 2.1 specification. + +MCP clients **MAY** choose to implement other authorization grant types +in addition to authorization code flow with PKCE. + ### 2.3 MCP Server Authorization Metadata Discovery MCP servers **MUST** return the full path to their PRM document in the `WWW-Authenticate` header @@ -456,7 +476,9 @@ handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` r The following security requirements **MUST** be implemented: -1. Clients **MUST** securely store tokens following OAuth 2.1 best practices. +1. Clients **MUST** securely store tokens following OAuth 2.1 best practices, as + outlined in the + [OAuth 2.1 Authorization Framework](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12). 1. Servers **MUST** validate all incoming tokens in one of the three ways: 1. Token introspection, according to [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662). `aud` validation is a **MUST**. From b6f5ecc3c21ec81543932aaf8d2a2c1dd06702f8 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Fri, 11 Apr 2025 16:25:20 -0700 Subject: [PATCH 78/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index f687d43a8..e4d477c0d 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -229,17 +229,17 @@ Code Flow with PKCE. The third-party authorization flow comprises these steps: -1. MCP client requests data from the MCP server. +1. MCP client requests data from the MCP server. 1. MCP server responds with `HTTP 401 Unauthorized` and `WWW-Authenticate` header containing the - URL to the PRM document. + URL to the PRM document. 1. MCP client retrieves and validates the PRM document. -1. MCP client retrieves the AS endpoint from the PRM document. +1. MCP client retrieves the AS endpoint from the PRM document. 1. MCP client redirects user to the AS authorization endpoint. MCP client can include scopes that are defined in the PRM document or other scopes, as supported by the MCP server. 1. User authorizes with authorization server. -1. Authorization server redirects back to MCP client with authorization code. -1. MCP client exchanges the code for the requested tokens. -1. MCP client stores the token. +1. Authorization server redirects back to MCP client with authorization code. +1. MCP client exchanges the code for the requested tokens. +1. MCP client stores the token. 1. MCP client can now request data from the MCP server with the token attached in the `Authorization` header. @@ -260,6 +260,7 @@ sequenceDiagram MC->>AS: Exchange code for token AS-->>MC: Access token MC->>MC: Cache token + MC->>MS: Request data
(with Authorization header) ``` #### 2.4.4 Security Considerations From d62e53843ac34dafede492b8908f37fe210e1e8d Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Fri, 11 Apr 2025 16:30:03 -0700 Subject: [PATCH 79/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index e4d477c0d..16389a3a7 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -408,7 +408,7 @@ sequenceDiagram MC->>AS: Exchange auth code for tokens AS-->>MC: Return tokens Note over MC: Store tokens - Note over MC, MS: Begin standard MCP message exchange + Note over MC, MS: Continue MCP message exchange ``` #### 2.8.1 Decision Flow Overview From 46f4e452363f149b3f549482c335e5c07f68ffd3 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Sat, 12 Apr 2025 11:41:25 -0700 Subject: [PATCH 80/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 16389a3a7..e855513f0 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -308,23 +308,6 @@ MCP servers that use delegated authorization or implement a colocated AS **MUST* 1. Provide appropriate responses to the client if re-authentication is needed. Please refer to [RFC 9470 OAuth 2.0 Step Up Authentication Challenge Protocol](https://www.rfc-editor.org/rfc/rfc9470.html). -### 2.6 Implementing authorization server overrides - -In certain scenarios, AS might have limited capability support, such as no dynamic client registration, and -MCP server developers may choose to implement those capabilities themselves. - -In this scenario, the server **MUST** return its fully-qualified domain name as the AS in the PRM document, -that will be linked from the `WWW-Authenticate` header in the `HTTP 401 Unauthorized` response. - -The MCP server will need to be configured in accordance with -[Section 2.5](#25-delegated-authorization-or-colocated-as-flows) to act as an AS. - -#### 2.6.1 Discovery of server-driven overrides - -Under all circumstances, the server **MUST** return a `WWW-Authenticate` with PRM document information, -even if the server provides its own metadata document that overrides AS endpoints -(such as `/authorize`, `/token`, or `/register`). - ### 2.7 Dynamic Client Registration MCP clients **SHOULD** support the From 57550d8a8d9716b42bf9270cd1b9a9dadcfb93e9 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Sat, 12 Apr 2025 11:51:19 -0700 Subject: [PATCH 81/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index e855513f0..4442b6c6f 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -268,7 +268,7 @@ sequenceDiagram When implementing authorization with an existing AS, MCP servers **MUST**: 1. Request the minimum number of required scopes. -2. Securely store any tokens obtained from the client and/or the authorization server. +2. Securely handle any tokens that need to be stored or otherwise managed by the MCP server. 3. Implement appropriate session timeout handling. 4. Consider security implications of token chaining. 5. Implement proper error handling for authorization failures. @@ -378,10 +378,7 @@ sequenceDiagram MC->>AS: Request client registration AS-->>MC: Confirm client registration else Authorization server does not support dynamic client registration - MC->>MS: Request client registration - MS->>AS: Register client - AS-->>MS: Return client registration - MS-->>MC: Return client registration + MC->>MS: Provide UX to specify client ID end Note over MC: Generate PKCE artifacts From 99ef5a64c51c5c8299a0964f9ed4162ca2191616 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Sat, 12 Apr 2025 12:05:56 -0700 Subject: [PATCH 82/98] Update authorization.mdx --- .../specification/2025-03-26/basic/authorization.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 4442b6c6f..067bd9c1f 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -457,17 +457,19 @@ handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` r The following security requirements **MUST** be implemented: -1. Clients **MUST** securely store tokens following OAuth 2.1 best practices, as +1. MCP clients **MUST** securely store tokens following OAuth 2.1 best practices, as outlined in the [OAuth 2.1 Authorization Framework](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12). -1. Servers **MUST** validate all incoming tokens in one of the three ways: +1. MCP servers **MUST** take all necessary steps to ensure no data is returned to unauthorized parties + and **MUST** ensure any credentials are valid before processing the request. For example, a MCP server + could validate inbound tokens through one of the following approaches: 1. Token introspection, according to [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662). `aud` validation is a **MUST**. 1. JWT validation, according to [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068.html). - 1. Custom validation, according to the conventions established by the Authorization Server. + 1. Custom validation, according to the conventions established by the AS. 1. All authorization endpoints **MUST** be served over HTTPS. -1. Authorization servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities. -1. Redirect URIs **MUST** be either `localhost` URLs or HTTPS URLs. +1. Authorization servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities. +1. Redirect URIs **MUST** be either `localhost` URLs or HTTPS URLs. 1. Special considerations **MUST** be accounted for to prevent phishing through MCP servers. ### 2.10 Error Handling From f7ece73d84ae7552d4abc5c5b79b0cf77b039a98 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Sat, 12 Apr 2025 12:22:28 -0700 Subject: [PATCH 83/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 067bd9c1f..ec28d491a 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -214,9 +214,7 @@ MCP-Protocol-Version: 2024-11-05 #### 2.4.1 Overview -MCP clients **SHOULD** be considered _public clients_ and MCP servers **MUST** be -considered _confidential clients_, as defined in -[RFC 6749 Section 2.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). +MCP clients **SHOULD** be considered _public clients_. MCP servers **MUST NOT** complete public client flows on behalf of the MCP client (e.g., take authorization codes and exchange them for tokens with a public client ID, and then pass the tokens @@ -290,6 +288,9 @@ Authorization servers **MUST**: In limited scenarios, MCP servers **MAY** implement their own AS, refer to as a _colocated AS_ due to the MCP server _colocating_ itself, the resource server (RS) with the AS. +MCP servers **MUST** be considered _confidential clients_, as defined in +[RFC 6749 Section 2.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). + MCP servers that implement their own AS **MUST** host appropriate AS metadata, as outlined in [RFC 8414 Section 3](https://datatracker.ietf.org/doc/html/rfc8414#section-3). From 03276b787a2bf7c4356b9241a57395c8c19fdaaa Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Sat, 12 Apr 2025 22:35:37 -0700 Subject: [PATCH 84/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 40 +++++++++++++++---- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index ec28d491a..200f05653 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -18,7 +18,7 @@ resources, or any other capabilities. This document **does not discuss server-to-server authorization patterns**. -### 1.2 Baseline tenets +### 1.2 Baseline Tenets 1. **MCP server developers are not security experts**. Developers should not be building their own authorization servers unless absolutely necessary. This introduces room for serious mistakes @@ -210,7 +210,7 @@ For example: MCP-Protocol-Version: 2024-11-05 ``` -### 2.4 Authorization server integration +### 2.4 Authorization Server Integration #### 2.4.1 Overview @@ -283,7 +283,7 @@ Authorization servers **MUST**: 1. Verify that the resource identifier is registered for the audience of the access token issued. -### 2.5 Delegated authorization or colocated AS flows +### 2.5 Delegated Authorization or Colocated AS In limited scenarios, MCP servers **MAY** implement their own AS, refer to as a _colocated AS_ due to the MCP server _colocating_ itself, the resource server (RS) with the AS. @@ -298,7 +298,7 @@ MCP servers **MAY** support delegated authorization through third-party AS. In this flow, the MCP server acts as both an OAuth client (to the external AS) and an OAuth AS (to the MCP client). -#### 2.5.1 Special considerations +#### 2.5.1 Special Considerations MCP servers that use delegated authorization or implement a colocated AS **MUST**: @@ -343,7 +343,7 @@ An MCP client **MAY** contain a configuration for common issuers, such as: Alternatively, an MCP client could allow the user to register the MCP client and provide those details to the MCP client through a UI. -### 2.8 Authorization flow steps +### 2.8 Authorization Flow Steps The complete authorization flow proceeds as follows: @@ -454,7 +454,7 @@ If validation fails, servers **MUST** respond according to [Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3) error handling requirements. Invalid or expired tokens **MUST** receive a `HTTP 401` response. -### 2.9 Security Considerations +### 2.10 Security Considerations The following security requirements **MUST** be implemented: @@ -473,7 +473,7 @@ The following security requirements **MUST** be implemented: 1. Redirect URIs **MUST** be either `localhost` URLs or HTTPS URLs. 1. Special considerations **MUST** be accounted for to prevent phishing through MCP servers. -### 2.10 Error Handling +### 2.11 Error Handling Servers **MUST** return appropriate HTTP status codes for authorization errors: @@ -483,7 +483,7 @@ Servers **MUST** return appropriate HTTP status codes for authorization errors: | 403 | Forbidden | Invalid scopes or insufficient permissions | | 400 | Bad Request | Malformed authorization request | -### 2.11 Implementation Requirements +### 2.12 Implementation Requirements 1. Implementations **MUST** follow OAuth 2.1 security best practices. 2. PKCE is **REQUIRED** for all clients. @@ -515,3 +515,27 @@ We strongly recommend that local clients implement OAuth 2.1 as a public client: Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation of dynamic client registration. This allows applications to automatically register with the MCP server, and removes the need for users to obtain client IDs manually. + +### 3.4 Separation of Concerns + +To ensure the security of MCP servers and their customers, the following represent best practices +in ensuring that the concerns of MCP clients, MCP servers, and AS are properly separated. + +A protected MCP server is responsible for hosting and protecting MCP-specific entities, such as tools, +prompts, resources, cached data, or any other artifacts directly managed by it. + +MCP clients **MUST** present valid tokens with the protected MCP server as the audience and **MUST NOT** +use the MCP server as a pass-through to channel tokens issued to different audiences through it. + +Protected MCP servers that receive tokens with an audience different than itself **MUST** reject +them under all circumstances (see [Section 3.11](#210-security-considerations) for validation +considerations). + +MCP clients are responsible for performing an OAuth authorization flow, as outlined in +[Section 2.2.1](#221-oauth-grant-types) against the AS declared in the MCP server's PRM document. +This is the only OAuth relationship the client participates in. + +Downstream OAuth calls (e.g., to third-party APIs) are implementation details left to the MCP +server developers to design. For those scenarios, the MCP server itself becomes an OAuth client, +and downstream interactions are handled entirely by the MCP server. The MCP client's authorization +relationship remains solely between itself and the MCP server's declared AS. From 81c13395221a0facc711e2ecf5ad2559b8693116 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 14 Apr 2025 07:47:03 -0700 Subject: [PATCH 85/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 200f05653..62b438ecc 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -20,9 +20,9 @@ This document **does not discuss server-to-server authorization patterns**. ### 1.2 Baseline Tenets -1. **MCP server developers are not security experts**. Developers should not be building their own - authorization servers unless absolutely necessary. This introduces room for serious mistakes - that can lead to compromise. +1. **MCP server developers are not expected to be security experts.**. Developers should not be + building their own authorization servers unless absolutely necessary, as they expect that MCP + provides a basline secure authentication and authorization process. 1. **MCP clients are Authorization Server (AS)-agnostic**. When developers build MCP servers and secure them with an AS, they need to design them so that standard, off-the-shelf MCP clients can connect without needing any special modifications for the server's authorization setup. From 197d993468054ffbf9cb18faf74ce53d71f3c8db Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 14 Apr 2025 07:48:10 -0700 Subject: [PATCH 86/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 62b438ecc..6364dbd40 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -116,7 +116,7 @@ A MCP client **MUST** issue a `GET` request to the URL in `resource_metadata` to the AS. A MCP client **MUST** verify that the `resource` value in the PRM document matches the MCP server -fully-qualified domain name. +protocol and fully-qualified domain name (FQDN). A MCP client **SHOULD** evaluate or permit the user to evaluate the trustworthiness of AS discovered through the PRM document to prevent phishing. For example, an MCP client could prompt From 880c51b3f0c9a064d95fa87abb99454ad8a0114c Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 14 Apr 2025 07:54:31 -0700 Subject: [PATCH 87/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 6364dbd40..9ce40996d 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -268,7 +268,10 @@ When implementing authorization with an existing AS, MCP servers **MUST**: 1. Request the minimum number of required scopes. 2. Securely handle any tokens that need to be stored or otherwise managed by the MCP server. 3. Implement appropriate session timeout handling. -4. Consider security implications of token chaining. +4. Consider security implications of token chaining, such as ensuring that the appropriate + tokens are exposed to the right audiences (e.g., don't pass server-issued tokens to the + client), validating the original scopes and issuers, and looking for unintended privilege + escalation by virtue of token exchange. 5. Implement proper error handling for authorization failures. MCP clients **MUST**: From 562c3ef868ba52d1f225c596248ab169be03b77c Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 14 Apr 2025 10:50:45 -0700 Subject: [PATCH 88/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 9ce40996d..1e437815c 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -288,7 +288,7 @@ Authorization servers **MUST**: ### 2.5 Delegated Authorization or Colocated AS -In limited scenarios, MCP servers **MAY** implement their own AS, refer to as a _colocated AS_ due +In limited scenarios, MCP servers **MAY** implement their own AS, referred to as a _colocated AS_ due to the MCP server _colocating_ itself, the resource server (RS) with the AS. MCP servers **MUST** be considered _confidential clients_, as defined in From 3905cfcb0ef0a32e6f240d083387b50ac9af34fc Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 14 Apr 2025 14:58:49 -0700 Subject: [PATCH 89/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 1e437815c..b45fdd154 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -106,8 +106,9 @@ WWW-Authenticate: Bearer resource_metadata="https://resource.example.com/.well-k A MCP server **MUST** host its Protected Resource Metadata (PRM) document, as outlined in [Section 3 of the RFC draft](https://www.ietf.org/archive/id/draft-ietf-oauth-resource-metadata-13.html#section-3). -A MCP server **MUST** return a set of scopes in the `scope` parameter within the `WWW-Authenticate` header -in the initial handshake as well as in subsequent responses that require incremental authorization. +A MCP server **MUST** return the minimum required set of scopes in the `scope` parameter within the +`WWW-Authenticate` header in the initial handshake as well as any additional scopes in subsequent responses +that require incremental authorization. A MCP server **MUST** include its AS configuration in the PRM document as outlined in [Section 2 of the RFC draft](https://www.ietf.org/archive/id/draft-ietf-oauth-resource-metadata-13.html#section-2). From b41a66407f4013aa03bca7c317fd1d86bf34762e Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 14 Apr 2025 15:03:21 -0700 Subject: [PATCH 90/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index b45fdd154..22f6ac2bd 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -272,7 +272,8 @@ When implementing authorization with an existing AS, MCP servers **MUST**: 4. Consider security implications of token chaining, such as ensuring that the appropriate tokens are exposed to the right audiences (e.g., don't pass server-issued tokens to the client), validating the original scopes and issuers, and looking for unintended privilege - escalation by virtue of token exchange. + escalation by virtue of token exchange. Refer to the [Best Practices](#3-best-practices) + section for additional recommendations. 5. Implement proper error handling for authorization failures. MCP clients **MUST**: From 612eb2d9d689584099406e3c3186b40db5aa02e8 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 14 Apr 2025 15:39:01 -0700 Subject: [PATCH 91/98] Update authorization.mdx --- .../2025-03-26/basic/authorization.mdx | 40 +++++++++++++++++-- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 22f6ac2bd..4aae0a9cb 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -140,7 +140,7 @@ supported by the AS. See A MCP clients **MUST** initiate an [OAuth 2.1 (draft)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) authorization -flow after receiving a *HTTP 401 Unauthorized* response. +flow after receiving a `HTTP 401 Unauthorized` response. ### 2.2.1 OAuth Grant Types @@ -290,8 +290,10 @@ Authorization servers **MUST**: ### 2.5 Delegated Authorization or Colocated AS -In limited scenarios, MCP servers **MAY** implement their own AS, referred to as a _colocated AS_ due -to the MCP server _colocating_ itself, the resource server (RS) with the AS. +MCP servers **MAY** implement their own AS, referred to as a _colocated AS_ due +to the MCP server _colocating_ itself, the resource server (RS) with the AS. This approach should +be limited to scenarios where existing AS implementations cannot be used, as it requires +authorization and security expertise. MCP servers **MUST** be considered _confidential clients_, as defined in [RFC 6749 Section 2.1](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). @@ -544,3 +546,35 @@ Downstream OAuth calls (e.g., to third-party APIs) are implementation details le server developers to design. For those scenarios, the MCP server itself becomes an OAuth client, and downstream interactions are handled entirely by the MCP server. The MCP client's authorization relationship remains solely between itself and the MCP server's declared AS. + +### 3.5 Third-Party API Access + +The third-party API connection process is done out-of-band and does not depend on the authorization +flow outlined in this specification. + +If the MCP server connects to third-party APIs, the MCP client **MUST NOT** hold tokens for said +third-party APIs and instead only the token for access to the MCP server. + +MCP server **MUST** make authorization decisions based solely on tokens with it as the audience, +and it **MUST NOT** use third-party API tokens as a pass-through, as outlined in +[Section 3.4](#34-separation-of-concerns). + +```mermaid +sequenceDiagram + participant UA as User Agent + participant MC as MCP Client + participant MS as MCP Server + participant AS as Downstream API AS + participant API as Downstream API + + MC->>MS: Request resource
(e.g., tool call) + MS-->>MC: 401 Unauthorized (downstream authorization required) Message + MC-->>UA: Direct user for downstream authorization + UA->>AS: Authenticate & authorize + AS-->>UA: Authorization code + UA->>MS: Authorization code + MS->>AS: Exchange code for downstream API token + AS-->>MS: Access token + Note over MS: Stored downstream API access token + Note over MC, MS: Continue message exchange +``` \ No newline at end of file From cb53f968f367fa029b0a11d973829b2e52cf362d Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 14 Apr 2025 15:39:49 -0700 Subject: [PATCH 92/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 4aae0a9cb..f05a59d7b 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -324,7 +324,7 @@ allow MCP clients to obtain OAuth client IDs without user interaction. This prov way for clients to automatically register with new servers, which is crucial for MCP because: - Clients cannot know all possible servers in advance -- Manual registration would create friction for users +- Manual registration would create friction for developers and MCP server users - It enables seamless connection to new servers - Servers can implement their own registration policies From af7506662627b5062b055c0c5083253ada4aac64 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 14 Apr 2025 15:43:36 -0700 Subject: [PATCH 93/98] Update authorization.mdx --- docs/specification/2025-03-26/basic/authorization.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index f05a59d7b..951d225e1 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -328,6 +328,10 @@ way for clients to automatically register with new servers, which is crucial for - It enables seamless connection to new servers - Servers can implement their own registration policies +This approach also helps prevent rogue client impersonation attacks, requiring that all clients +register their redirect URIs, as outlined in +[Section 5 of RFC 7591](https://www.rfc-editor.org/rfc/rfc7591#section-5). + MCP clients that want to dynamically register OAuth clients with an authorization server **MUST** provide the `software_id` and `software_version` parameters, as defined in the [Client Metadata](https://datatracker.ietf.org/doc/html/rfc7591#section-2) section of From b4af30d9b9de1ffe029d0039fc088e7e7cf8d27d Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Wed, 16 Apr 2025 10:28:35 -0700 Subject: [PATCH 94/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Eleftheria Stein-Kousathana --- docs/specification/2025-03-26/basic/authorization.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 951d225e1..59d4d4698 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -156,8 +156,7 @@ 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. -MCP clients **MUST** support authorization code flow with PKCE, per -OAuth 2.1 specification. +MCP clients **MUST** implement PKCE when using the authorization code flow, per OAuth 2.1 specification." MCP clients **MAY** choose to implement other authorization grant types in addition to authorization code flow with PKCE. From 2500702b55b2c8c8eaaaa924b350dac4d5da0fa2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?= <53200638+localden@users.noreply.github.com> Date: Mon, 21 Apr 2025 09:55:15 -0700 Subject: [PATCH 95/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Nick Bell --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 59d4d4698..de81b237b 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -22,7 +22,7 @@ This document **does not discuss server-to-server authorization patterns**. 1. **MCP server developers are not expected to be security experts.**. Developers should not be building their own authorization servers unless absolutely necessary, as they expect that MCP - provides a basline secure authentication and authorization process. + provides a baseline secure authentication and authorization process. 1. **MCP clients are Authorization Server (AS)-agnostic**. When developers build MCP servers and secure them with an AS, they need to design them so that standard, off-the-shelf MCP clients can connect without needing any special modifications for the server's authorization setup. From 10856f3ae813cac82f026b757b6c0440e504c972 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?= <53200638+localden@users.noreply.github.com> Date: Mon, 21 Apr 2025 09:55:27 -0700 Subject: [PATCH 96/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Tommy Hansen --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index de81b237b..d61d790f2 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -156,7 +156,7 @@ 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. -MCP clients **MUST** implement PKCE when using the authorization code flow, per OAuth 2.1 specification." +MCP clients **MUST** implement PKCE when using the authorization code flow, per OAuth 2.1 specification. MCP clients **MAY** choose to implement other authorization grant types in addition to authorization code flow with PKCE. From 291f5739732a1c021f7037fd045bd5ac0c03cf84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?= <53200638+localden@users.noreply.github.com> Date: Mon, 21 Apr 2025 21:48:53 -0700 Subject: [PATCH 97/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: Xiao Yijun --- docs/specification/2025-03-26/basic/authorization.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index d61d790f2..8c3effcaf 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -523,8 +523,7 @@ We strongly recommend that local clients implement OAuth 2.1 as a public client: ### 3.3 Dynamic Client Registration Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation -of dynamic client registration. This allows applications to automatically register with the MCP -server, and removes the need for users to obtain client IDs manually. +of dynamic client registration. This allows applications to automatically register with the authorization server referenced by the MCP server, and removes the need for users to obtain client IDs manually. ### 3.4 Separation of Concerns From 7ef66ace90b8ae0948b3d046b9e3a6a6cb1ee41a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Den=20Delimarsky=20=F0=9F=8C=BA?= <53200638+localden@users.noreply.github.com> Date: Wed, 23 Apr 2025 10:47:09 -0700 Subject: [PATCH 98/98] Update docs/specification/2025-03-26/basic/authorization.mdx Co-authored-by: bobby <1544881+desimone@users.noreply.github.com> --- docs/specification/2025-03-26/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/2025-03-26/basic/authorization.mdx b/docs/specification/2025-03-26/basic/authorization.mdx index 8c3effcaf..6619eb124 100644 --- a/docs/specification/2025-03-26/basic/authorization.mdx +++ b/docs/specification/2025-03-26/basic/authorization.mdx @@ -20,7 +20,7 @@ This document **does not discuss server-to-server authorization patterns**. ### 1.2 Baseline Tenets -1. **MCP server developers are not expected to be security experts.**. Developers should not be +1. **MCP server developers are not expected to be security experts.** Developers should not be building their own authorization servers unless absolutely necessary, as they expect that MCP provides a baseline secure authentication and authorization process. 1. **MCP clients are Authorization Server (AS)-agnostic**. When developers build MCP servers and secure