跳到主要内容

模型上下文协议规范（2025-03-26）—— 授权

· 阅读需 12 分钟

翻译自：https://spec.modelcontextprotocol.io/specification/2025-03-26/basic/authorization/

ℹ️ 协议修订：2025-03-26

1. 引言​

1.1 目的和范围​

模型上下文协议（MCP）在传输层提供了授权能力，允许MCP客户端代表资源所有者向受限的MCP服务器发出请求。本规范定义了基于HTTP传输的授权流程。

1.2 协议要求​

MCP实施的授权是可选的。当得到支持时：

  • 使用基于HTTP的传输实现应该遵守本规范。
  • 使用STDIO传输的实现不应该遵循这个规范，而是应该从环境中获取凭据。
  • 使用替代传输实现必须遵循其协议的既定安全最佳实践。

1.3 标准合规性​

这种授权机制基于下列已建立的规范，但实现了其特性中的选定子集，以确保在保持简单性的同时，保证安全性和互操作性：

2. 授权流程​

2.1 概述​

  1. MCP授权实现必须为机密客户端和公开客户端实施OAuth 2.1，并采取适当的安全措施。
  2. MCP鉴权实现应该支持OAuth 2.0动态客户端注册协议（RFC7591）。
  3. MCP服务器应该而MCP客户端必须实现OAuth 2.0授权服务器元数据（RFC8414）。不支持授权服务器元数据的服务器必须遵循默认的URI架构。

2.2 基础的 OAuth 2.1 授权​

当授权是必需的而客户端尚未提供证明时，服务器必须以HTTP 401 Unauthorized响应。

客户端在收到HTTP 401 未授权后启动OAuth 2.1 IETF 草案的授权流程。

以下展示了使用PKCE的公共客户端的基本OAuth 2.1流程。

OAuth 2.1 流程

2.3 服务器元数据发现​

服务器能力发现：

  • MCP 客户端必须遵循在 RFC8414 中定义的 OAuth 2.0 授权服务器元数据协议。
  • MCP服务器应当遵循OAuth 2.0授权服务器元数据协议。
  • 不支持 OAuth 2.0 授权服务器元数据协议的MCP服务器，必须支持后备URL。

发现流程如下图所示：

服务器元数据发现流程

2.3.1 服务器元数据发现头部​

在服务器元数据发现过程中，MCP 客户端应该包含头部 MCP-Protocol-Version: <protocol-version>，以便MCP服务器可以根据MCP协议版本进行响应。

例如：MCP-Protocol-Version: 2024-11-05

2.3.2 授权基础网址​

授权基础URL 必须 通过舍弃任何现有的 path 组件从MCP服务器URL确定。例如：

如果MCP服务器的URL是https://api.example.com/v1/mcp，那么：

  • 授权基础 URL 是 https://api.example.com
  • 元数据端点 必须 位于 https://api.example.com/.well-known/oauth-authorization-server

这确保了授权端点始终位于托管MCP服务器的域的根级别，无论MCP服务器URL中的路径组件如何。

2.3.3 没有元数据发现功能的服务器的备选方案​

对于不实现OAuth 2.0授权服务器元数据的服务器，客户端必须使用以下默认的端点路径，相对于授权基础URL（如第2.3.2节中定义）：

端点默认路径描述
授权端点/authorize用于授权请求
令牌端点/token用于令牌交换和刷新
注册端点/register用于动态客户端注册

例如，如果一个MCP服务器托管在https://api.example.com/v1/mcp，那么默认的端点将会是：

客户端必须首先尝试通过元数据文档来发现端点，再回退到默认路径。当使用默认路径时，所有其他协议要求保持不变。

2.3 动态客户端注册​

MCP 客户端和服务器应该支持 OAuth 2.0 动态客户端注册协议，以便 MCP 客户端可以在没有用户交互的情况下获取 OAuth 客户端 ID。这为客户端自动向新服务器注册提供了一种标准化的方式，这对于 MCP 来说至关重要，因为：

  • 客户端无法提前知晓所有可能的服务器。
  • 手动注册会给用户带来不便。
  • 它实现了与新服务器的无缝连接
  • 服务器可以实现自己的注册策略

任何不支持动态客户端注册的MCP服务器需要提供其他方法来获取客户端ID（如果适用，还有客户端密钥）。对于这些服务器之一，MCP客户端将必须选择以下方式之一：

  1. 硬编码一个客户端ID（如果适用，还包括客户端密钥）专门用于那个MCP服务器，或者
  2. 向用户展示一个用户界面，让他们在注册了OAuth客户端后输入这些详细信息（例如，通过服务器托管的配置界面）。

2.4 授权流程步骤​

完整的授权流程如下进行：

授权流程步骤

2.4.1 决策流概述​

决策流概述

2.5 访问令牌的使用​

2.5.1 令牌要求​

访问令牌处理必须符合OAuth 2.1 第5节对资源请求的要求。具体来说：

  1. MCP 客户端必须使用授权请求头字段 第5.1.1节：
Authorization: Bearer <access-token>

请注意，在客户端向服务器发送的每个HTTP请求中都必须包含授权信息，即使它们是同一个逻辑会话的一部分。

  1. 访问令牌必须不能包含在URI查询字符串中。

示例请求：

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

2.5.2 令牌处理​

资源服务器必须按照第5.2节所描述的方式验证访问令牌。如果验证失败，服务器必须根据第5.3节的错误处理要求做出响应。无效或过期的令牌必须收到HTTP 401响应。

2.6 安全考虑​

以下安全要求必须被实施：

  1. 客户端必须根据OAuth 2.0的最佳实践安全地存储令牌。
  2. 服务器应该执行令牌的过期和轮换。
  3. 所有授权终端点必须通过HTTPS服务。
  4. 服务器必须验证重定向URI以防止公开重定向漏洞
  5. 重定向URI 必须 是localhost URLs或HTTPS URLs。

2.7 错误处理​

服务器必须为授权错误返回适当的HTTP状态码。

状态码描述使用场景
401未授权需要授权或令牌无效
403禁止访问权限范围无效或权限不足
400错误的请求授权请求格式错误

2.8 实施要求​

  1. 实现必须遵循OAuth 2.1安全最佳实践
  2. PKCE对所有客户端来说都是必需的
  3. 为了增强安全性，应该实施令牌轮换
  4. 令牌的有效期应该根据安全需求来限定。

2.9 第三方授权流程​

2.9.1 概述​

MCP服务器可以通过第三方授权服务器支持委派授权。在这个流程中，MCP服务器既是OAuth客户端（对第三方授权服务器而言）也是OAuth授权服务器（对MCP客户端而言）。

2.9.2 流程描述​

第三方授权流程包括以下步骤：

  1. MCP客户端与MCP服务器启动标准的OAuth流程
  2. MCP服务器将用户重定向到第三方授权服务器。
  3. 用户授权第三方服务器
  4. 第三方服务器带着授权码重定向回MCP服务器。
  5. MCP服务器交换代码以获取第三方访问令牌
  6. MCP 服务器生成了绑定到第三方会话的自有访问令牌。
  7. MCP服务器完成与MCP客户端的原始OAuth流程

第三方授权流程

2.9.3 会话绑定要求​

MCP服务器实现第三方授权必须：

  1. 维持第三方令牌与发行的MCP令牌之间的安全映射。
  2. 在承认MCP令牌之前验证第三方令牌的状态
  3. 实施适当的令牌生命周期管理
  4. 处理第三方令牌过期和更新

2.9.4 安全性考虑​

在实现第三方授权时，服务器必须：

  1. 验证所有重定向URI
  2. 安全地存储第三方凭据
  3. 实现适当的会话超时处理
  4. 考虑令牌链接的安全隐患
  5. 实现对第三方授权失败的适当错误处理

3. 最佳实践​

3.1 本地客户端作为公共OAuth 2.1 客户端​

我们强烈推荐本地客户端作为公共客户端实施OAuth 2.1：

  1. 利用代码挑战（PKCE）进行授权请求以防止拦截攻击
  2. 为本地系统实现适当的安全令牌存储
  3. 遵循令牌刷新的最佳实践以维持会话
  4. 正确处理令牌过期和续订

3.2 授权元数据发现​

我们强烈建议所有客户端实施元数据发现。这减少了用户手动提供端点的需求，或者客户端回退到定义的默认值。

3.3 动态客户端注册​

由于客户端事先不知道MCP服务器的集合，我们强烈推荐实施动态客户端注册。这允许应用程序自动注册到MCP服务器，并且消除了用户手动获取客户端ID的需求。