授权

​

引言

​

目的和范围

​

协议要求

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

​

标准合规性

• 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)
• OpenID Connect 动态客户端注册 1.0 (OpenID Connect Registration)

​

角色

​

概述

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

​

授权服务器发现

​

授权服务器位置

​

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

1. WWW-Authenticate 头：在返回 401 Unauthorized 响应时，如 RFC9728 第 5.1 节 所述，在 WWW-Authenticate HTTP 头下的 resource_metadata 中包含资源元数据 URL。
2. Well-Known URI：如 RFC9728 所述，在 well-known 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_ids 时获取元数据文档
• 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",
    "http://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

​

客户端 ID 元数据文档流程

​

发现

{
  "client_id_metadata_document_supported": true
}

​

预注册

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

​

动态客户端注册

​

应用类型和重定向 URI 约束

• 原生应用（桌面应用、移动应用、CLI 工具和通过 localhost 访问的本地托管 Web 应用）SHOULD 使用 application_type: "native"
• Web 应用（从非本地主机提供的远程基于浏览器的应用）SHOULD 使用 application_type: "web"

​

Scope 选择策略

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

​

授权流程步骤

​

资源参数实现

1. 必须包含在授权请求和令牌请求中。
2. 必须标识客户端打算与其一起使用令牌的 MCP 服务器。
3. 必须使用 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（包含片段）

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

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

​

访问令牌使用

​

令牌要求

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

Authorization: Bearer <access-token>

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

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

​

令牌处理

​

刷新令牌

• 必须按照 OAuth 2.1 第 4.3 节 的规定在传输和存储中保持刷新令牌的机密性
• 应该在其 grant_types 客户端元数据中包含 refresh_token
• 当授权服务器元数据在 scopes_supported 中包含 offline_access 时，可以在授权和令牌请求的 scope 参数中添加 offline_access
• 不得假设将颁发刷新令牌；AS 保留酌情权

​

错误处理

​

范围挑战处理

​

运行时范围不足错误

• 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:write",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         error_description="File write permission required for this operation"

​

升级授权流程

1. 解析错误信息 来自授权服务器响应或 WWW-Authenticate 头
2. 确定所需范围 通过计算客户端先前请求的范围集和当前挑战中的范围的并集。这确保当服务器根据 RFC 6750 第 3.1 节 发出每操作范围挑战时，先前授予的权限得以保留。 客户端可以还咨询 范围选择策略 以获取初始范围选择指导。
3. 发起（重新）授权 使用确定的范围集
4. 重试原始请求 使用新授权不超过几次，并将其视为永久授权失败

​

安全考虑

​

Token 受众绑定与验证

• MCP 客户端 必须 在授权和令牌请求中包含 resource 参数，如 资源参数实现 部分所指定
• MCP 服务器 必须 验证呈现给它们的令牌是专门为其使用而颁发的

​

令牌盗窃

​

通信安全

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

​

授权码保护

• OAuth 2.0 授权服务器元数据：如果 code_challenge_methods_supported 缺失，则授权服务器不支持 PKCE，MCP 客户端 必须 拒绝继续。
• OpenID Connect Discovery 1.0：虽然 开放身份提供者元数据 未定义 code_challenge_methods_supported，但开放身份提供者通常包含此字段。MCP 客户端 必须 验证提供者元数据响应中 code_challenge_methods_supported 的存在。如果该字段缺失，MCP 客户端 必须 拒绝继续。

​

开放重定向

​

客户端 ID 元数据文档安全

​

授权服务器滥用保护

​

Localhost 重定向 URI 风险

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

• 应该 为仅限 localhost 的重定向 URI 显示额外警告
• 可以 要求额外的证明机制以增强安全性
• 必须 在授权期间清晰显示重定向 URI 主机名

​

信任策略

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

​

混淆代理问题

​

访问令牌权限限制

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

​

MCP 授权扩展

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