> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SEP-2207: OIDC 风格刷新令牌指南

> OIDC 风格刷新令牌指南

<div className="flex items-center gap-2 mb-4">
  <Badge color="green" shape="pill">
    最终版
  </Badge>

  <Badge color="gray" shape="pill">
    标准轨道
  </Badge>
</div>

| 字段            | 值                                                                               |
| ------------- | ------------------------------------------------------------------------------- |
| **SEP**       | 2207                                                                            |
| **Title**     | OIDC 风格刷新令牌指南                                                                   |
| **Status**    | 最终版                                                                             |
| **Type**      | 标准轨道                                                                            |
| **Created**   | 2026-02-04                                                                      |
| **Author(s)** | Wils Dawson ([@wdawson](https://github.com/wdawson))                            |
| **Sponsor**   | Paul Carleton ([@pcarleton](https://github.com/pcarleton))                      |
| **PR**        | [#2207](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2207) |

***

## 摘要

本提案为 MCP 实现提供关于刷新令牌颁发和请求的指南，特别是当授权服务器支持 `offline_access` scope 时。`offline_access` scope 起源于 OIDC，但可以被任何 OAuth 2.1 授权服务器采用，作为一种让客户端显式请求刷新令牌的机制。本 SEP 阐明了授权服务器和 MCP 客户端在使用此模式时的预期行为。

## 动机

MCP 的授权机制基于 OAuth 2.1，但许多现实世界的部署使用同时也实现 OpenID Connect (OIDC) 的授权服务器。纯 OAuth 和 OIDC 之间的一个关键区别在于如何处理刷新令牌：

* 在**纯 OAuth 2.1** 中，没有标准机制让客户端显式请求刷新令牌。授权服务器根据客户端的能力（例如，客户端元数据中的 `refresh_token` 授予类型）及其自身的策略来决定是否颁发刷新令牌。
* 在**OIDC**（以及采用此约定的授权服务器）中，存在 `offline_access` scope 以允许客户端显式请求刷新令牌，作为 OAuth 逻辑的补充。

这在 MCP 生态系统中造成了几个问题：

1. **客户端未请求刷新令牌**：主要 MCP 客户端（Cursor、Claude、VS Code 等）未通过 `offline_access` scope 显式请求刷新令牌，因为它们不知道授权服务器是否支持、期望或需要它。

2. **资源服务器不应指定 `offline_access`**：`offline_access` scope 不是特定于资源的 scope——它是客户端和授权服务器之间的问题。将其包含在 `WWW-Authenticate` 头部的 `scope` 参数中或受保护资源元数据的 `scopes_supported` 中在语义上是不正确的，因为它暗示资源\_需要\_刷新令牌，而实际上永远不会需要。

3. **授权服务器可能不一致**：在处理授权码授予时，不同的授权服务器在向不同客户端颁发刷新令牌时可能有不同的行为，特别是当客户端未指定 `refresh_token` 作为授予类型或未请求 `offline_access` scope 时。

4. **互操作性差距**：如果没有此指南，实现的行为可能不一致，导致用户体验不佳（频繁重新认证）或安全问题（向无法安全存储它们的客户端颁发刷新令牌）。

## 规范

### MCP 客户端要求

打算使用刷新令牌且能够安全存储它们的 MCP 客户端**应该**遵循以下指南：

1. **声明能力**：客户端**应该**在其 `grant_types` 客户端元数据中包含 `refresh_token`，以表明它们支持刷新令牌。

2. **Scope 增强**：当客户端需要刷新令牌且授权服务器元数据的 `scopes_supported` 字段中包含 `offline_access` 时，客户端**可以**在向授权服务器发出授权请求之前，将 `offline_access` scope 添加到资源服务器的 scope 列表中。

3. **无保证**：客户端**不得**假设声明支持或请求 `offline_access` 就能保证收到刷新令牌。授权服务器保留根据其策略进行裁量的权利。

### MCP 服务器（资源服务器）要求

MCP 服务器（作为 OAuth 2.0 受保护资源）：

1. **不应该**在 `WWW-Authenticate` 头部的 `scope` 参数中包含 `offline_access`，因为刷新令牌不是资源要求。

2. **不应该**在受保护资源元数据的 `scopes_supported` 中包含 `offline_access`，因为它不是特定于资源的 scope。

## 理由

### 为什么不在 401 响应中要求 `offline_access`？

`offline_access` scope 与特定于资源的 scope  fundamentally 不同。它代表客户端对长期访问的愿望，而不是资源的要求。根据 [OAuth 2.1 第 5.3.1 节](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5.3.1)，`WWW-Authenticate` 中的 `scope` 属性表示“访问请求资源所需的访问令牌 scope"。由于资源不需要 `offline_access`，包含它在语义上是不正确的。

### 为什么要检查客户端元数据中的授予类型？为什么不总是颁发刷新令牌？

OAuth 2.1 要求客户端注册其支持的授予类型。不支持 `refresh_token` 授予的客户端：

* 无法安全存储刷新令牌
* 没有使用它们的机制

向此类客户端颁发刷新令牌会浪费授权服务器资源（跟踪永远不会使用的令牌），并且如果令牌泄露，可能会构成安全风险。

### 为什么允许 `offline_access` 作为替代信号？

一些授权服务器（无论是完全符合 OIDC 还是仅采用此约定）仅在显式请求 `offline_access` 时才颁发刷新令牌。支持此模式为此类部署提供了兼容路径。客户端可以通过检查授权服务器元数据中的 `scopes_supported` 是否包含 `offline_access` 来检测支持此约定的授权服务器，并相应地调整其行为。

### 考虑的替代方法

1. **在资源响应中强制要求 `offline_access`**：被拒绝，因为它歪曲了资源的要求并创建了反模式。

2. **总是颁发刷新令牌**：被拒绝，因为它忽略了客户端能力和授权服务器安全策略。

3. **单独的 OIDC 特定规范**：被拒绝，倾向于采用适用于纯 OAuth 和 OIDC 部署的统一方法。

4. **为授权服务器提供指南**：被拒绝，倾向于依赖 OAuth 和 OIDC 规范作为此指南，因为它可能有所不同。

## 向后兼容性

本提案完全向后兼容：

* 已经请求 `offline_access` 的客户端继续工作
* 已经检查客户端能力的授权服务器继续工作
* MCP 服务器不需要进行任何更改
* 指南是附加的，不改变现有的必需行为

不遵循此指南的实现可能会经历次优行为（缺少刷新令牌或不必要的令牌颁发），但仍将保持功能正常。

## 安全影响

### 积极的安全影响

1. **降低令牌泄露风险**：通过不向未声明支持的客户端颁发刷新令牌，我们降低了长期令牌被不安全存储的风险。

2. **深度防御**：基于风险的评估步骤使授权服务器能够灵活地实施额外的安全控制。

### 注意事项

1. **客户端元数据可能不足**：由于客户端元数据是自我报告的，恶意行为者可以注册声称支持 `refresh_token` 授予的客户端以获取长期令牌。授权服务器**可以**使用基于风险的评估步骤（参见规范）来应用额外的限制——例如域名允许列表、信誉检查或验证要求——而不是在决定是否颁发刷新令牌时仅依赖客户端元数据声明。

2. **Scope 注入**：添加 `offline_access` 的客户端应确保这不会干扰其他 scope 相关逻辑或创建意外的授权提示。

## 参考实现

展示此指南的参考实现将在官方 MCP SDK 中提供：

* **TypeScript SDK**：客户端侧 `offline_access` scope 处理
* **Python SDK**：客户端侧 `offline_access` scope 处理
* **授权服务器示例**：客户端能力检查演示
* **客户端一致性测试**：允许轻松验证 SDK 实现

一旦 SEP 被接受，将添加实现链接。

## 致谢

本提案是通过 MCP Discord 的授权频道讨论开发的，输入来自：

* Aaron Parecki (OAuth/OIDC 专业知识)
* Paul Carleton (MCP 授权指南)
* Simon Russell (OIDC 部署经验)