> ## Documentation Index > Fetch the complete documentation index at: https://mcp.developerdoc.cn/llms.txt > Use this file to discover all available pages before exploring further. # 授权
## Introduction ### Purpose and Scope Model Context Protocol 在传输层提供授权能力，使 MCP 客户端能够代表资源所有者向受限 MCP 服务器发起请求。本规范定义基于 HTTP 的传输的授权流程。 ### Protocol Requirements 授权对于 MCP 实现是 **OPTIONAL** 的。支持授权时： * 使用基于 HTTP 的传输的实现 **SHOULD** 遵循本规范。 * 使用 STDIO 传输的实现 **SHOULD NOT** 遵循本规范，而应从环境中检索凭据。 * 使用替代传输的实现 **MUST** 遵循其协议已建立的安全最佳实践。 ### Standards Compliance 此授权机制基于下列既有规范，但只实现其中选定的功能子集，以在保持简单性的同时确保安全性和互操作性： * OAuth 2.1 IETF DRAFT ([draft-ietf-oauth-v2-1-13](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13)) * OAuth 2.0 Bearer Token Usage ([RFC6750](https://datatracker.ietf.org/doc/html/rfc6750)) * 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)) * Resource Indicators for OAuth 2.0 ([RFC8707](https://www.rfc-editor.org/rfc/rfc8707.html)) * OAuth 2.0 Protected Resource Metadata ([RFC9728](https://datatracker.ietf.org/doc/html/rfc9728)) * OAuth 2.0 Authorization Server Issuer Identification ([RFC9207](https://datatracker.ietf.org/doc/html/rfc9207)) * OAuth Client ID Metadata Documents ([draft-ietf-oauth-client-id-metadata-document-00](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00)) * [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) * OpenID Connect Dynamic Client Registration 1.0 ([OpenID Connect Registration](https://openid.net/specs/openid-connect-registration-1_0.html)) ## Roles 受保护的 *MCP 服务器* 充当 [OAuth 2.1 资源服务器](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#name-roles)，能够使用访问令牌接受并响应受保护资源请求。 *MCP 客户端* 充当 [OAuth 2.1 客户端](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#name-roles)，代表资源所有者发起受保护资源请求。 *授权服务器* 负责与用户交互（如有必要），并颁发供 MCP 服务器使用的访问令牌。授权服务器的实现细节超出本规范范围。它可以与资源服务器共同托管，也可以由独立实体托管。[授权服务器发现](/specification/draft/basic/authorization/authorization-server-discovery)规定 MCP 服务器如何向客户端指示其对应授权服务器的位置。 ## 概览 1. 授权服务器 **MUST** 实现 OAuth 2.1，并为机密客户端和公共客户端采用适当的安全措施。 2. 授权服务器和 MCP 客户端 **SHOULD** 支持 [OAuth Client ID Metadata Documents](/specification/draft/basic/authorization/client-registration#client-id-metadata-documents) ([draft-ietf-oauth-client-id-metadata-document-00](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00)). 3. 授权服务器和 MCP 客户端 **MAY** 支持 OAuth 2.0 Dynamic Client Registration Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591))。请注意， [Dynamic Client Registration](/specification/draft/basic/authorization/client-registration#dynamic-client-registration) 已弃用，保留它是为了与不支持 Client ID Metadata Documents 的授权服务器保持向后兼容。 4. MCP 服务器 **MUST** 实现 OAuth 2.0 Protected Resource Metadata ([RFC9728](https://datatracker.ietf.org/doc/html/rfc9728))。 MCP 客户端 **MUST** 使用 OAuth 2.0 受保护资源元数据进行[授权服务器发现](/specification/draft/basic/authorization/authorization-server-discovery)。 5. MCP 授权服务器 **MUST** 至少提供以下发现机制之一： * OAuth 2.0 Authorization Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)) * [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) MCP 客户端 **MUST** 同时支持这两种[发现机制](/specification/draft/basic/authorization/authorization-server-discovery#authorization-server-metadata-discovery)，以获得与授权服务器交互所需的信息。 ## Authorization Server Discovery MCP 服务器通过 OAuth 2.0 受保护资源元数据公布其关联的授权服务器，MCP 客户端通过授权服务器元数据发现来确定授权服务器端点和受支持能力。实现 **MUST** 遵循[授权服务器发现](/specification/draft/basic/authorization/authorization-server-discovery)中定义的规范性发现要求。 ## Client Registration 发起授权流程之前，MCP 客户端 **MUST** 通过三种注册机制之一获取客户端 ID：Client ID Metadata Documents、pre-registration 或 Dynamic Client Registration，并遵循[客户端注册](/specification/draft/basic/authorization/client-registration)中定义的要求和选择优先级。 ## Scope Selection Strategy MCP 服务器 **SHOULD** 按照 [RFC 6750 Section 3](https://datatracker.ietf.org/doc/html/rfc6750#section-3) 的定义，在 `WWW-Authenticate` 标头中包含 `scope` 参数，以指示访问资源所需的作用域。这会立即向客户端提供授权期间应请求哪些适当作用域的指导，遵循最小权限原则，并防止客户端请求过多权限。 `WWW-Authenticate` 质询中包含的作用域 **MAY** 与 `scopes_supported` 匹配，可以是它的子集或超集，也可以是既非严格子集也非超集的另一组作用域。客户端 **MUST NOT** 假定被质询的作用域集合与 `scopes_supported` 之间存在任何特定集合关系。客户端 **MUST** 将质询中提供的作用域视为当前操作的权威要求。这些作用域是满足当前请求所必需的。重新授权时，客户端 **SHOULD** 将这些作用域与此前已授予的任何作用域一并包含，以避免丢失其他操作所需的权限（请参见 [Step-up 授权流程](#step-up-authorization-flow)）。服务器 **SHOULD** 努力保持其构造作用域集合的方式一致，但不要求通过 `scopes_supported` 暴露每个动态颁发的作用域。 带有作用域指导的 401 响应示例： ```http theme={null} HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", scope="files:read" ``` 实现授权流程时，MCP 客户端 **SHOULD** 遵循最小权限原则，只请求其预期操作所需的作用域。在初始授权握手期间，MCP 客户端 **SHOULD** 按以下优先级顺序选择作用域： 1. 如果提供了 401 响应中初始 `WWW-Authenticate` 标头里的 `scope` 参数，则**使用 `scope` 参数** 2. **如果 `scope` 不可用**，则使用受保护资源元数据文档中 `scopes_supported` 定义的所有作用域；如果 `scopes_supported` 未定义，则省略 `scope` 参数。 这种方法适应 MCP 客户端的通用性质，因为它们通常缺乏领域特定知识，无法对单个作用域选择做出充分判断。请求所有可用作用域允许授权服务器和最终用户在同意流程中确定适当权限。 这种方法在遵循最小权限原则的同时最大限度减少用户阻力。`scopes_supported` 字段旨在表示基本功能所需的最小作用域集合（请参见[作用域最小化](/docs/tutorials/security/security_best_practices#scope-minimization)），额外作用域则通过[作用域质询处理](#scope-challenge-handling)部分描述的 step-up 授权流程步骤逐步请求。 ## Authorization Flow Steps 流程中显示的注册步骤使用[客户端注册](/specification/draft/basic/authorization/client-registration)中定义的机制之一。 完整授权流程如下： ```mermaid theme={null} sequenceDiagram participant B as User-Agent (Browser) participant C as Client participant M as MCP Server (Resource Server) participant A as Authorization Server C->>M: MCP request without token M->>C: HTTP 401 Unauthorized with WWW-Authenticate header Note over C: Extract resource_metadata URL from WWW-Authenticate C->>M: Request Protected Resource Metadata M->>C: Return metadata Note over C: Parse metadata and extract authorization server(s)
Client determines AS to use C->>A: GET Authorization server metadata endpoint Note over C,A: Try OAuth 2.0 and OpenID Connect
discovery endpoints in priority order A-->>C: Authorization server metadata alt Client ID Metadata Documents Note over C: Client uses HTTPS URL as client_id Note over A: Server detects URL-formatted client_id A->>C: Fetch metadata from client_id URL C-->>A: JSON metadata document Note over A: Validate metadata and redirect_uris else Dynamic client registration C->>A: POST /register A->>C: Client Credentials else Pre-registered client Note over C: Use existing client_id end Note over C: Generate PKCE parameters
Include resource parameter
Apply scope selection strategy
Record expected issuer C->>B: Open browser with authorization URL + code_challenge + resource B->>A: Authorization request with resource parameter Note over A: User authorizes A->>B: Redirect to callback with authorization code + iss B->>C: Authorization code callback Note over C: Validate iss against recorded issuer (RFC 9207) C->>A: Token request + code_verifier + resource A->>C: Access token (+ refresh token) C->>M: MCP request with access token M-->>C: MCP response Note over C,M: MCP communication continues with valid token ``` ### Authorization Response Validation 重定向用户代理之前，客户端 **MUST** 记录所选授权服务器已验证元数据文档中的 `issuer` 值（请参见[授权服务器元数据发现](/specification/draft/basic/authorization/authorization-server-discovery#authorization-server-metadata-discovery)），并将其与用于存储 PKCE code verifier（以及 `state` 值，如果使用）的同一按请求记录关联。本节中的验证依赖所记录值的真实性；如果预期 issuer 来自未经验证的来源，则它不提供保护。 MCP 授权服务器 **SHOULD** 按照 [RFC9207 Section 2](https://datatracker.ietf.org/doc/html/rfc9207#section-2) 的定义，在授权响应（包括错误响应）中包含 `iss` 参数。包含 `iss` 参数的授权服务器 **MUST** 通过在其元数据中将 `authorization_response_iss_parameter_supported` 设置为 `true` 来公布这一点（[RFC9207 Section 2.3](https://datatracker.ietf.org/doc/html/rfc9207#section-2.3)）。 收到授权响应时，MCP 客户端 **MUST** 在将授权码传输到任何令牌端点之前，应用 [RFC9207 Section 2.4](https://datatracker.ietf.org/doc/html/rfc9207#section-2.4) 中的验证： | `authorization_response_iss_parameter_supported` | 响应中的 `iss` | 客户端动作 | | ------------------------------------------------ | ---------- | --------------------------------------------------- | | `true` | 存在 | 使用简单字符串比较与记录的 issuer 比较（[RFC3986 Section 6.2.1][1]） | | `true` | 不存在 | 拒绝该响应 | | `false` 或不存在 | 存在 | 使用简单字符串比较与记录的 issuer 比较（[RFC3986 Section 6.2.1][1]） | | `false` 或不存在 | 不存在 | 继续 | [1]: https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.1 第三行应用了 [RFC9207 Section 2.4](https://datatracker.ietf.org/doc/html/rfc9207#section-2.4) 中的本地策略规定：本规范会将存在的 `iss` 与记录的 issuer 比较，而不管元数据是否公布支持，以适应先发出 `iss`、后更新元数据的授权服务器。 本规范未来的修订预计会将授权服务器包含 `iss` 的要求从 **SHOULD** 升级为 **MUST**。鼓励实现者现在就发出并验证 `iss`，以简化该过渡；在该修订定义升级路径之前，客户端在缺少 `iss` 时的拒绝行为仍将以 `authorization_response_iss_parameter_supported` 为依据。 按照 [RFC 9207 Section 2.4](https://datatracker.ietf.org/doc/html/rfc9207#section-2.4) 从 `application/x-www-form-urlencoded` 响应中解码 `iss` 值后，客户端在比较前 **MUST NOT** 应用 scheme 或 host 大小写折叠、默认端口省略、尾随斜杠处理或百分号编码规范化（[RFC 3986 Sections 6.2.2-6.2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2)）。 此验证同样适用于错误响应；如果不匹配，客户端 **MUST NOT** 处理或显示 `error`、`error_description` 或 `error_uri`。 ## Resource Parameter Implementation MCP 客户端 **MUST** 实现 [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) 中定义的 OAuth 2.0 Resource Indicators，以显式指定正在为其请求令牌的目标资源。`resource` 参数： 1. **MUST** 同时包含在授权请求和令牌请求中。 2. **MUST** 标识客户端打算与该令牌一起使用的 MCP 服务器。 3. **MUST** 使用 [RFC 8707 Section 2](https://www.rfc-editor.org/rfc/rfc8707.html#name-access-token-request) 中定义的 MCP 服务器规范 URI。 ### Canonical Server URI 就本规范而言，MCP 服务器的规范 URI 定义为 [RFC 8707 Section 2](https://www.rfc-editor.org/rfc/rfc8707.html#section-2) 中规定的资源标识符，并与 [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) 中的 `resource` 参数保持一致。 MCP 客户端 **SHOULD** 遵循 [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707) 中的指导，为其打算访问的 MCP 服务器提供尽可能具体的 URI。虽然规范形式使用小写的 scheme 和 host 组件，但实现 **SHOULD** 接受大写的 scheme 和 host 组件，以增强稳健性和互操作性。 有效规范 URI 示例： * `https://mcp.example.com/mcp` * `https://mcp.example.com` * `https://mcp.example.com:8443` * `https://mcp.example.com/server/mcp`（当需要路径组件来标识单个 MCP 服务器时） 无效规范 URI 示例： * `mcp.example.com`（缺少 scheme） * `https://mcp.example.com#fragment`（包含 fragment） > **注意：** 根据 [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986)，`https://mcp.example.com/`（带尾随斜杠）和 `https://mcp.example.com`（不带尾随斜杠）在技术上都是有效的绝对 URI；但除非尾随斜杠对特定资源具有语义意义，否则实现 **SHOULD** 一致使用不带尾随斜杠的形式，以获得更好的互操作性。 例如，如果访问位于 `https://mcp.example.com` 的 MCP 服务器，授权请求会包含： ``` &resource=https%3A%2F%2Fmcp.example.com ``` 无论授权服务器是否支持此参数，MCP 客户端 **MUST** 发送它。 ## Access Token Usage ### Token Requirements 向 MCP 服务器发起请求时的访问令牌处理 **MUST** 符合 [OAuth 2.1 Section 5 "Resource Requests"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5) 中定义的要求。具体而言： 1. MCP 客户端 **MUST** 使用 [OAuth 2.1 Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5.1.1) 中定义的 Authorization 请求标头字段： ``` Authorization: Bearer ``` 请注意，每个从客户端到服务器的 HTTP 请求中都 **MUST** 包含授权信息。 2. 访问令牌 **MUST NOT** 包含在 URI 查询字符串中 请求示例： ```http theme={null} GET /mcp HTTP/1.1 Host: mcp.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIs... ``` ### Token Handling MCP 服务器作为 OAuth 2.1 资源服务器，**MUST** 按照 [OAuth 2.1 Section 5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5.2) 中的描述验证访问令牌。MCP 服务器 **MUST** 根据 [RFC 8707 Section 2](https://www.rfc-editor.org/rfc/rfc8707.html#section-2) 验证访问令牌是专门以它们为预期受众颁发的。如果验证失败，服务器 **MUST** 按照 [OAuth 2.1 Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5.3) 的错误处理要求响应。无效或过期的令牌 **MUST** 收到 HTTP 401 响应。 MCP 客户端 **MUST NOT** 向 MCP 服务器发送非该 MCP 服务器授权服务器颁发的令牌。 MCP 服务器 **MUST** 只接受对其自身资源有效的令牌。 MCP 服务器 **MUST NOT** 接受或传递任何其他令牌。 ## Refresh Tokens 本节为 MCP 客户端和 MCP 服务器在处理或颁发 OAuth 与 OpenID Connect 刷新令牌时提供指导。 需要刷新令牌的 **MCP 客户端**： * **MUST** 按照 [OAuth 2.1 Section 4.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-14#section-4.3) 的规定，在传输和存储中保持刷新令牌机密 * **SHOULD** 在其 `grant_types` 客户端元数据中包含 `refresh_token` * 当授权服务器元数据的 `scopes_supported` 中包含 `offline_access` 时，**MAY** 将 `offline_access` 添加到授权请求和令牌请求的 `scope` 参数中 * **MUST NOT** 假定一定会颁发刷新令牌；AS 保留决定权 **MCP 服务器**（受保护资源）**SHOULD NOT** 在 `WWW-Authenticate` scope 或受保护资源元数据的 `scopes_supported` 中包含 `offline_access`，因为刷新令牌不是资源要求。 ## Error Handling 服务器 **MUST** 为授权错误返回适当的 HTTP 状态码： | 状态码 | 描述 | 用途 | | --- | ------------ | ---------- | | 401 | Unauthorized | 需要授权或令牌无效 | | 403 | Forbidden | 作用域无效或权限不足 | | 400 | Bad Request | 授权请求格式错误 | ### Scope Challenge Handling 本节涵盖运行时操作期间 insufficient scope 错误的处理方式，此时客户端已经拥有令牌，但需要额外权限。这遵循 [OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5) 中定义的错误处理模式，并利用 [RFC 9728 (OAuth 2.0 Protected Resource Metadata)](https://datatracker.ietf.org/doc/html/rfc9728) 中的元数据字段。 #### Runtime Insufficient Scope Errors 当客户端在运行时操作期间使用作用域不足的访问令牌发起请求时，服务器 **SHOULD** 以如下方式响应： * `HTTP 403 Forbidden` 状态码（根据 [RFC 6750 Section 3.1](https://datatracker.ietf.org/doc/html/rfc6750#section-3.1)） * 带有 `Bearer` scheme 和附加参数的 `WWW-Authenticate` 标头： * `error="insufficient_scope"` - 表示授权失败的具体类型 * `scope="required_scope1 required_scope2"` - 指定该操作所需的最小作用域 * `resource_metadata` - 受保护资源元数据文档的 URI（与 401 响应保持一致） * `error_description`（可选）- 人类可读的错误描述 **服务器作用域管理**：响应 insufficient scope 错误时，服务器 **SHOULD** 按照 [RFC 6750 Section 3.1](https://datatracker.ietf.org/doc/html/rfc6750#section-3.1)，在 `scope` 参数中包含满足当前操作所需的作用域。`scope` 属性描述访问所请求资源所需的作用域；服务器不需要包含客户端此前已授予的作用域。 服务器可以灵活决定包含哪些作用域： * **最小方法**：仅包含触发错误的特定操作所需的作用域。 * **推荐方法**：包含当前操作所需的作用域，以及通常一起使用的相关作用域，以减少 step-up 授权轮次。 * **扩展方法**：包含当前操作所需的作用域、相关作用域，以及服务器预期客户端近期可能需要的任何其他作用域。 选择取决于服务器对用户体验影响和授权阻力的评估。 无论选择哪种方法，服务器 **SHOULD** 在单个质询中包含当前操作所需的所有作用域。增量质询（先返回一个缺失作用域，再在后续重试中返回另一个）会迫使单个操作经历多次授权往返，并降低用户体验。所需作用域可以基于具体请求参数和上下文动态确定，但一旦确定，就应一起发出。 服务器 **SHOULD** 在其作用域包含策略上保持一致，以向客户端提供可预测的行为。 服务器在确定响应中包含哪些作用域时 **SHOULD** 考虑用户体验影响，因为配置错误的作用域可能需要频繁的用户交互。 跨操作的作用域累积是客户端侧责任。如 [Step-up 授权流程](#step-up-authorization-flow) 中所述，客户端在发起重新授权时 **SHOULD** 计算此前请求的作用域与新质询作用域的并集。这允许服务器在客户端作用域集合方面保持无状态，同时确保客户端不会丢失此前授予的权限。 insufficient scope 响应示例： ```http theme={null} HTTP/1.1 403 Forbidden WWW-Authenticate: Bearer error="insufficient_scope", scope="files:write", resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", error_description="File write permission required for this operation" ``` #### Step-Up Authorization Flow 客户端会在初始授权期间或运行时收到与作用域相关的错误（`insufficient_scope`）。客户端 **SHOULD** 通过 step-up 授权流程请求具有更多作用域的新访问令牌来响应这些错误，或以其他适当方式处理错误。代表用户行事的客户端 **SHOULD** 尝试 step-up 授权流程。代表自身行事的客户端（`client_credentials` 客户端）**MAY** 尝试 step-up 授权流程，或立即中止请求。 流程如下： 1. 从授权服务器响应或 `WWW-Authenticate` 标头中**解析错误信息** 2. 通过计算客户端此前请求的作用域集合与当前质询中作用域的并集，**确定所需作用域**。这确保当服务器按照 [RFC 6750 Section 3.1](https://datatracker.ietf.org/doc/html/rfc6750#section-3.1) 发出按操作划分的作用域质询时，此前授予的权限会被保留。客户端 **MAY** 还可以参考[作用域选择策略](#scope-selection-strategy)获取初始作用域选择指导。 3. 使用确定的作用域集合**发起（重新）授权** 4. 使用新授权**重试原始请求**，重试次数不超过几次；若仍失败，则将其视为永久授权失败 客户端 **SHOULD** 实现重试限制，并且 **SHOULD** 跟踪作用域升级尝试，以避免同一资源和操作组合反复失败。 **层级作用域**：某些授权服务器定义作用域层级，其中较宽泛的作用域隐含较窄的作用域（例如，`admin` 作用域包含 `read`）。累积作用域时，客户端的并集可能包含语义上冗余的条目；例如，此前已授予宽泛作用域的令牌，可能又被质询一个它已经隐含的较窄作用域。客户端无需按层级去重；授权服务器通常会在令牌颁发期间规范化此类冗余。服务器方面在决定令牌是否足以执行某项操作时必须考虑层级，但这不影响它们在质询中发出的作用域。 ## 安全 Considerations 本规范的实现 **MUST** 遵循[安全注意事项](/specification/draft/basic/authorization/security-considerations)中的规范性安全要求，涵盖令牌受众绑定与验证、令牌盗窃、通信安全、授权码保护、mix-up 和 confused deputy 攻击、开放重定向，以及 Client ID Metadata Document 安全。 ## MCP Authorization Extensions 核心协议有多个授权扩展，用于定义额外的授权机制。这些扩展是： * **可选** - 实现可以选择采用这些扩展 * **增量** - 扩展不会修改或破坏核心协议功能；它们在保留核心协议行为的同时添加新能力 * **可组合** - 扩展是模块化的，并设计为可以无冲突地协同工作，允许实现同时采用多个扩展 * **独立版本化** - 扩展遵循核心 MCP 版本周期，但可按需采用独立版本控制 支持的扩展列表可在 [MCP Authorization Extensions](https://github.com/modelcontextprotocol/ext-auth) 仓库中找到。