授权

​

简介

​

目的与范围

​

协议要求

• 使用基于 HTTP 传输的实现应当 (SHOULD) 符合本规范。
• 使用 STDIO 传输的实现不应 (SHOULD NOT) 遵循本规范，而应从环境中检索凭据。
• 使用替代传输方式的实现必须 (MUST) 遵循其协议既定的安全最佳实践。

​

标准合规性

• OAuth 2.1 IETF 草案 (draft-ietf-oauth-v2-1-13)
• OAuth 2.0 授权服务器元数据 (RFC8414)
• OAuth 2.0 动态客户端注册协议 (RFC7591)
• OAuth 2.0 受保护资源元数据 (RFC9728)
• OAuth 客户端 ID 元数据文档 (draft-ietf-oauth-client-id-metadata-document-00)

​

角色

​

概述

1. 授权服务器必须 (MUST) 实现 OAuth 2.1，并针对机密客户端和公共客户端采取适当的安全措施。
2. 授权服务器和 MCP 客户端应当 (SHOULD) 支持 OAuth 客户端 ID 元数据文档 (draft-ietf-oauth-client-id-metadata-document-00)。
3. 授权服务器和 MCP 客户端可以 (MAY) 支持 OAuth 2.0 动态客户端注册协议 (RFC7591)。
4. MCP 服务器必须 (MUST) 实现 OAuth 2.0 受保护资源元数据 (RFC9728)。MCP 客户端必须 (MUST) 使用 OAuth 2.0 受保护资源元数据进行授权服务器发现。
5. MCP 授权服务器必须 (MUST) 至少提供以下一种发现机制：
   • OAuth 2.0 授权服务器元数据 (RFC8414)
   • OpenID Connect Discovery 1.0
   MCP 客户端必须 (MUST) 支持这两种发现机制，以获取与授权服务器交互所需的信息。

​

授权服务器发现

​

授权服务器位置

​

受保护资源元数据发现要求

1. WWW-Authenticate 响应头：在返回 401 Unauthorized 响应时，在 WWW-Authenticate HTTP 响应头的 resource_metadata 下包含资源元数据 URL，如 RFC9728 第 5.1 节所述。
2. 周知 (Well-Known) URI：在 RFC9728 指定的周知 URI 提供元数据。这可以是：
   • 在服务器 MCP 端点的路径：https://example.com/public/mcp 可以在 https://example.com/.well-known/oauth-protected-resource/public/mcp 托管元数据
   • 在根目录：https://example.com/.well-known/oauth-protected-resource

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

​

授权服务器元数据发现

1. 路径插入式的 OAuth 2.0 授权服务器元数据：https://auth.example.com/.well-known/oauth-authorization-server/tenant1
2. 路径插入式的 OpenID Connect Discovery 1.0：https://auth.example.com/.well-known/openid-configuration/tenant1
3. 路径追加式的 OpenID Connect Discovery 1.0：https://auth.example.com/tenant1/.well-known/openid-configuration

1. OAuth 2.0 授权服务器元数据：https://auth.example.com/.well-known/oauth-authorization-server
2. OpenID Connect Discovery 1.0：https://auth.example.com/.well-known/openid-configuration

​

授权服务器发现时序图

​

客户端注册方式

• 客户端 ID 元数据文档：当客户端和服务器没有事先关系时（最常见）
• 预注册：当客户端和服务器已有现有关系时
• 动态客户端注册：用于向后兼容或特定需求

1. 如果客户端有可用的预注册客户端信息，则使用该信息
2. 如果授权服务器指示支持（通过 OAuth 授权服务器元数据中的 client_id_metadata_document_supported），则使用客户端 ID 元数据文档
3. 如果授权服务器支持（通过 OAuth 授权服务器元数据中的 registration_endpoint），则使用动态客户端注册作为备选
4. 如果没有其他选项可用，提示用户输入客户端信息

​

客户端 ID 元数据文档

​

实现要求

• 客户端必须 (MUST) 按照 RFC 要求在 HTTPS URL 上托管其元数据文档
• client_id URL 必须 (MUST) 使用 “https” 协议并包含路径组件，例如 https://example.com/client.json
• 元数据文档必须 (MUST) 至少包含以下属性：client_id、client_name、redirect_uris
• 客户端必须 (MUST) 确保元数据中的 client_id 值与文档 URL 完全匹配
• 客户端可以 (MAY) 使用 private_key_jwt 进行客户端身份验证（例如，针对令牌端点的请求），并按照 客户端 ID 元数据文档第 6.2 节 所述配置适当的 JWKS

• 应当 (SHOULD) 在遇到 URL 格式的 client_id 时获取元数据文档
• 必须 (MUST) 验证获取到的文档的 client_id 与 URL 完全匹配
• 应当 (SHOULD) 遵循 HTTP 缓存头缓存元数据
• 必须 (MUST) 将授权请求中提供的重定向 URI 与元数据文档中的进行对比验证
• 必须 (MUST) 验证文档结构为有效的 JSON 并包含必需字段
• 应当 (SHOULD) 遵循 客户端 ID 元数据文档第 6 节 中的安全考虑

​

元数据文档示例

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "logo_uri": "https://app.example.com/logo.png",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback",
    "https://:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

​

客户端 ID 元数据文档流程

​

发现

{
  "client_id_metadata_document_supported": true
}

​

预注册

1. 专门为 MCP 客户端硬编码一个客户端 ID（以及适用的客户端凭据），用于与该授权服务器交互，或者
2. 向用户提供一个界面，允许他们在自己注册 OAuth 客户端后（例如通过服务器托管的配置界面）输入这些详细信息。

​

动态客户端注册

​

范围 (Scope) 选择策略

1. 使用 scope 参数：如果 401 响应中初始的 WWW-Authenticate 响应头提供了该参数，则使用它
2. 如果 scope 不可用：使用受保护资源元数据文档中 scopes_supported 定义的所有范围；如果 scopes_supported 未定义，则省略 scope 参数。

​

授权流程步骤

​

资源参数实现

1. 必须 (MUST) 同时包含在授权请求和令牌请求中。
2. 必须 (MUST) 标识客户端打算使用该令牌的 MCP 服务器。
3. 必须 (MUST) 使用 RFC 8707 第 2 节 定义的 MCP 服务器规范 URI。

​

规范服务器 URI

• https://mcp.example.com/mcp
• https://mcp.example.com
• https://mcp.example.com:8443
• https://mcp.example.com/server/mcp（当需要路径组件来识别单个 MCP 服务器时）

• mcp.example.com（缺少协议）
• https://mcp.example.com#fragment（包含片段）

注意： 虽然根据 RFC 3986，https://mcp.example.com/（带尾部斜杠）和 https://mcp.example.com（不带尾部斜杠）在技术上都是有效的绝对 URI，但为了更好的互操作性，实现应当 (SHOULD) 一致地使用不带尾部斜杠的形式，除非尾部斜杠对特定资源具有语义意义。

&resource=https%3A%2F%2Fmcp.example.com

​

访问令牌使用

​

令牌要求

1. MCP 客户端必须 (MUST) 使用 OAuth 2.1 第 5.1.1 节 定义的 Authorization 请求头字段

Authorization: Bearer <access-token>

2. 访问令牌不得 (MUST NOT) 包含在 URI 查询字符串中

GET /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

​

令牌处理

​

错误处理

​

范围挑战 (Scope Challenge) 处理

​

运行时范围不足错误

• HTTP 403 Forbidden 状态码（根据 RFC 6750 第 3.1 节）
• 带有 Bearer 方案和额外参数的 WWW-Authenticate 响应头：
  • error="insufficient_scope" - 指明具体的授权失败类型
  • scope="required_scope1 required_scope2" - 指定该操作所需的最小范围
  • resource_metadata - 受保护资源元数据文档的 URI（与 401 响应保持一致）
  • error_description (可选) - 错误的易读描述

• 最小化方法：仅包含该特定操作新要求的范围。如果也需要任何现有的已授予范围，请一并包含，以防止客户端丢失之前已授予的权限。
• 推荐方法：同时包含相关的现有范围和新要求的范围，以防止客户端丢失之前已授予的权限
• 扩展方法：包含现有范围、新要求的范围，以及通常协同工作的相关范围

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                         scope="files:read files:write user:profile",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         error_description="Additional file write permission required"

​

升级授权流程

1. 从授权服务器响应或 WWW-Authenticate 响应头中解析错误信息
2. 按照 范围选择策略 中的概述确定所需范围。
3. 使用确定的范围集发起（重新）授权
4. 使用新的授权重试原始请求（重试次数不超过几次），并将其视为永久性授权失败

​

安全注意事项

​

令牌受众绑定与验证

• MCP 客户端必须 (MUST) 按照 资源参数实现 章节的规定，在授权请求和令牌请求中包含 resource 参数
• MCP 服务器必须 (MUST) 验证向其出示的令牌是专门为其使用而颁发的

​

令牌窃取

​

通信安全

1. 所有授权服务器端点必须 (MUST) 通过 HTTPS 提供服务。
2. 所有重定向 URI 必须 (MUST) 为 localhost 或使用 HTTPS。

​

授权码保护

• OAuth 2.0 授权服务器元数据：如果缺失 code_challenge_methods_supported，则说明授权服务器不支持 PKCE，MCP 客户端必须 (MUST) 拒绝继续流程。
• OpenID Connect Discovery 1.0：虽然 OpenID 提供者元数据 未定义 code_challenge_methods_supported，但该字段通常由 OpenID 提供者包含。MCP 客户端必须 (MUST) 验证提供者元数据响应中是否存在 code_challenge_methods_supported。如果该字段缺失，MCP 客户端必须 (MUST) 拒绝继续流程。

​

开放重定向

​

客户端 ID 元数据文档安全

​

授权服务器滥用保护

​

Localhost 重定向 URI 风险

1. 提供合法客户端的元数据 URL 作为其 client_id
2. 绑定到任意 localhost 端口，并将该地址作为 redirect_uri 提供
3. 当用户批准时，通过重定向接收授权码

• 应当 (SHOULD) 对仅限 localhost 的重定向 URI 显示额外警告
• 可以 (MAY) 为了增强安全性而要求额外的证明 (attestation) 机制
• 必须 (MUST) 在授权期间清晰显示重定向 URI 的主机名

​

信任策略

• 受信任域名的白名单（针对受保护服务器）
• 接受任何 HTTPS client_id（针对开放服务器）
• 对未知域名进行声誉检查
• 基于域名年龄或证书验证的限制
• 突出显示 CIMD 和其他关联的客户端主机名以防止钓鱼

​

混淆代理问题

​

访问令牌权限限制

1. 受众验证失败。 当 MCP 服务器不验证令牌是否专门用于它时（例如，通过 RFC9068 中提到的受众声明），它可能会接受最初为其他服务颁发的令牌。这破坏了基本的 OAuth 安全边界，允许攻击者在非预期的不同服务之间重用合法令牌。
2. 令牌透传。 如果 MCP 服务器不仅接受受众错误的令牌，还将这些未经修改的令牌转发给下游服务，则可能会导致 “混淆代理”问题，下游 API 可能会错误地信任该令牌，就像它直接来自 MCP 服务器一样，或者假设该令牌已被上游 API 验证。有关其他详细信息，请参阅安全最佳实践指南的 令牌透传章节。

​

MCP 授权扩展

• 可选的 - 实现可以选择采用这些扩展
• 增量式的 - 扩展不会修改或破坏核心协议功能；它们在保留核心协议行为的同时增加了新功能
• 可组合的 - 扩展是模块化的，旨在协同工作而不产生冲突，允许实现同时采用多个扩展
• 独立版本控制 - 扩展遵循核心 MCP 版本周期，但也可以根据需要采用独立版本号