MCP 授权服务器的 iss 校验为何影响客户端实现

MCP 授权回调里的 iss 不是可以随手忽略的附加字段。客户端在发起 OAuth 授权前，应该先从已验证的授权服务器元数据中记录 issuer，并把它和同一次授权尝试的 PKCE 校验器、状态值放在一起。回调返回后，客户端再根据规范比较 iss 与这份已记录的 issuer，只有匹配时才把授权码送到 token endpoint。

官方地址：https://modelcontextprotocol.io/

一、iss 为什么会影响 MCP 客户端

MCP 的 HTTP 授权流程里有三个角色：MCP 客户端负责发起授权并使用令牌，MCP 服务器作为受保护资源服务器接收令牌，授权服务器负责让用户授权并签发令牌。客户端可能连接到此前没有预置配置的 MCP 服务器，因此必须通过受保护资源元数据发现授权服务器，再通过授权服务器元数据确认端点和发行者。

如果客户端只保存一个全局授权服务器地址，或者只验证 state 与 PKCE，却不把回调绑定到预期发行者，多个授权服务器之间就可能出现混淆。攻击者不需要伪造一个合法授权码，只要让客户端把“来自另一个发行者的响应”送进当前流程，就可能把后续令牌交换带到错误的信任边界。

因此，iss 校验的实际影响不在于多比较一个参数，而在于客户端的数据模型必须从“全局配置”变成“按授权尝试保存预期发行者”。它还会改变回调处理顺序：先验证发行者，再决定是否继续交换授权码。

二、旧写法的问题：只看 state 或只拼接回调参数

很多 OAuth 客户端的早期实现大致是：生成 state 和 PKCE 参数，打开授权页面，回调时检查 state，然后把 code 直接发给令牌端点。这条链路在单一固定身份提供商环境里看起来够用，但 MCP 的服务发现是动态的，授权服务器也可能带有租户路径或不同发行者。

另一个常见问题是把 URL 当成“可以规范化后再比较”的普通地址。例如把 https://AUTH.example/tenant 变成小写、把默认端口删掉，或者自动补一个尾斜杠。对一般导航链接来说这类处理可能有帮助，对 OAuth 发行者比较却会改变规范要求的字符串语义，客户端反而可能接受不应接受的响应，或把合法响应误判为不同发行者。

正确的旧代码改造方向不是删除原有的 state 和 PKCE 检查，而是在它们旁边增加一次发行者绑定。state 解决的是请求与回调的关联，PKCE 解决的是授权码被截获后的交换保护，iss 解决的是回调来自哪个授权服务器的问题，三者承担的边界不同。

三、四种组合决定客户端动作

授权服务器元数据中的 authorization_response_iss_parameter_supported 表示服务器是否声明会在授权响应中返回 iss。客户端需要把这个标志和回调中 iss 是否存在一起判断，不能只看其中一个。

第三行是最容易漏掉的兼容边界：即使授权服务器没有在元数据里声明支持，回调一旦带有 iss，客户端也不能直接跳过比较。这样可以容纳“服务器已经开始返回 iss，但元数据还没有同步更新”的过渡状态。

四、代码实现：把 issuer 和 PKCE 绑定到同一次授权尝试

下面的 TypeScript 片段是客户端侧的最小实现示意。它不负责发现元数据，也不实现完整 OAuth 客户端，而是突出两个关键点：保存授权尝试时记录已验证的 issuer，解析回调时先做发行者判断，再读取授权码或错误信息。

type AuthorizationAttempt = {
  issuer: string;
  issParameterSupported: boolean;
  codeVerifier: string;
  state: string;
};

type CallbackResult =
  | { kind: "continue"; code: string; attempt: AuthorizationAttempt }
  | { kind: "reject"; reason: string };

function compareIssuer(expected: string, received: string): boolean {
  // 发行者比较使用简单字符串比较，不做大小写、端口或斜杠归一化。
  return expected === received;
}

function handleCallback(
  attempt: AuthorizationAttempt,
  params: URLSearchParams,
): CallbackResult {
  const receivedIss = params.get("iss");

  // 元数据声明支持 iss 时，缺失参数必须拒绝本次回调。
  if (attempt.issParameterSupported && receivedIss === null) {
    return { kind: "reject", reason: "authorization response missing iss" };
  }

  // 只要响应带有 iss，就必须和已验证元数据中的 issuer 比较。
  if (receivedIss !== null && !compareIssuer(attempt.issuer, receivedIss)) {
    return { kind: "reject", reason: "authorization response issuer mismatch" };
  }

  // issuer 不匹配时在这里结束，不能继续交换授权码。
  const code = params.get("code");
  if (!code) {
    // 只有通过发行者检查后，才读取错误或缺少 code 的业务结果。
    return { kind: "reject", reason: params.get("error") ?? "missing code" };
  }
  return { kind: "continue", code, attempt };
}

这段代码里的 attempt.issuer 必须来自经过校验的授权服务器元数据，不能来自未经验证的回调参数、用户可编辑配置或跳转地址。实现时通常会把它和 state、PKCE 的 code_verifier 一起放入短期存储，并在一次成功或失败的回调处理后删除。

真正调用令牌端点时，还需要把 code_verifier 和 MCP 资源的 resource 参数按授权规范发送。iss 校验通过只代表回调发行者匹配，不等于令牌已经有效，也不替代资源服务器对 access token 的受众校验。

五、兼容注意：错误回调和 URI 细节也要覆盖

1. 错误回调不能绕过 iss 检查

授权服务器可能返回 error、error_description 或 error_uri，而不是 code。客户端仍要先按同一规则校验 iss。如果发行者不匹配，就不要把错误描述展示给用户，也不要根据错误 URI 自动跳转，因为这些字段本身也属于未经确认的响应内容。

2. 不要做“看起来合理”的 URI 归一化

比较时只做表单解码后的简单字符串比较。不要主动进行以下转换：

• 把 scheme 或 host 做大小写折叠；
• 删除 :443 或其他默认端口；
• 自动删除或补上末尾斜杠；
• 重新编码百分号转义后再比较。

这不是说所有 URL 场景都不能规范化，而是 iss 的校验规则明确要求保留比较所需的原始字符串语义。发现不一致时，宁可让用户重新发起授权，也不要在客户端猜测两个发行者“其实应该一样”。

3. STDIO 不要套用 HTTP 授权回调

MCP 授权规范面向 HTTP 传输。STDIO 场景通常从进程环境或本地配置取得凭据，不应该为了统一代码结构而强行模拟远程 OAuth 回调。客户端可以复用安全存储和凭据清理原则，但传输方式与认证入口要分别实现。

六、落地采用清单：先改数据结构，再改回调分支

如果已有 MCP 客户端，建议按下面顺序改造：

1. 发现阶段：从授权服务器已验证元数据读取 issuer，同时记录 authorization_response_iss_parameter_supported。
2. 发起阶段：为每次授权尝试生成独立记录，把 issuer、state 和 PKCE verifier 绑定，不要使用全局共享变量。
3. 回调阶段：先检查 iss 缺失或不匹配，再读取 code、error 等结果字段。
4. 交换阶段：仅对通过检查的授权码请求 token endpoint，并继续发送正确的 resource 与 PKCE 参数。
5. 清理阶段：无论成功、拒绝还是超时，都删除短期授权尝试记录，日志只保留请求标识和失败原因，不记录授权码、令牌或完整回调查询串。

发布前至少覆盖四个表格分支，再增加“issuer 不同但仅差尾斜杠”“issuer 不同但仅差默认端口”“错误回调带不匹配 iss”三个用例。测试的重点不是让所有 URL 都被改写成同一种形式，而是证明客户端会在应该停止的位置停止。

相关问题

iss 和 state 是同一个东西吗？

不是。state 用于把回调关联到发起的授权请求，iss 用于确认响应的授权服务器发行者。两者都应校验，不能互相替代。

授权服务器不返回 iss，客户端一定要拒绝吗？

只有当元数据中的 authorization_response_iss_parameter_supported 为 true 时，缺失 iss 才是规范要求的拒绝条件。如果元数据没有声明支持且回调也没有 iss，客户端可以按既有流程继续，但仍需检查 state、PKCE 和其他授权条件。

iss 匹配后就可以信任 access token 吗？

不可以。iss 只绑定授权响应的发行者。MCP 服务器仍要验证令牌签名、有效期、权限和面向自身资源的受众；客户端也不能把一个资源的令牌转发给另一个资源。

为什么不把比较做得更宽松一点？

因为宽松比较会把不同的授权服务器标识合并到同一信任判断中。对 issuer 来说，明确拒绝比猜测 URL 等价关系更容易审计，也更符合协议的互操作边界。

总结

MCP 引入 iss 校验后，客户端实现的核心变化是“每次授权尝试都绑定一个经过验证的 issuer”。回调带 iss 就比较，声明支持却缺少 iss 就拒绝，不匹配时不要触碰授权码或错误字段；比较本身使用简单字符串语义，不做额外 URI 归一化。把这组规则放进授权尝试的数据结构和回调状态机，客户端才不会在动态服务发现环境中把不同授权服务器混为一谈。