跳转到内容

MCP OAuth 授权

OAuth 适用于把 Gateway 的 MCP 服务提供给外部用户、又不希望他们手动粘贴 API Key 的场景。用户在 ChatGPT、Claude、Codex 等客户端里点击连接,跳到你的业务系统登录并同意,客户端就拿到一个只能访问 MCP 的令牌。现有 API Key 接入不受影响。

在 MCP 服务页的「客户端接入」分区找到「OAuth 2.0 授权登录(可选)」卡片,选择一种模式:

模式适用场景
内置授权服务器推荐。Gateway 自己登记客户端、签发和刷新令牌;你的业务系统只负责登录与同意,不保存任何 OAuth 状态。
外部授权服务器已经有一套授权服务器,并通过 Admin API 为 Gateway 签发令牌时选它。Gateway 只提供资源元数据。
关闭不公开 OAuth 发现,客户端只能用 API Key 接入。

OAuth 只用于 MCP 入口,不是模型接口的通用登录方式,也不会把上游服务的 OAuth 转接给客户端。业务账号需要对应到网关用户,调用费用才有明确归属。

  1. 准备应用目录:在「OAuth 访问令牌」区的「应用」中点击「导入预设」,按需导入 ChatGPT、Claude、Codex、豆包、WorkBuddy,或手工添加应用。客户端注册时按回调地址归属应用,没有匹配应用的客户端无法注册。
  2. 准备登录与同意页:在业务系统中提供一个页面,接收 Gateway 附带的 request_id,确认用户已登录后,用带 oauth.consent 权限的集成密钥把用户的同意或拒绝回传给 Gateway,再按返回的地址跳回客户端。不想接入自己的站点时,可以留空,使用内置确认页(用户用自己的 API Key 确认)。
  3. 转发授权路径:反向代理把 /oauth/* 与 /.well-known/oauth-authorization-server 转发到 Proxy,与 /mcp 使用同一公开域名。
  4. 保存设置:选择「内置授权服务器」,填写「本 Gateway 的公开地址(issuer)」和「登录与同意页(可选)」,保存。
  5. 用真实客户端验收:逐个完成授权、工具调用、刷新和撤销,确认请求日志中显示的应用名与所属用户正确。

从外部授权服务器切换过来时,已有授权会在访问令牌过期后失效,用户需要重新授权。完整步骤见 0036 迁移说明。

  • MCP 访问令牌以 oat_ 开头,与用户 API Key 分开存储,只能访问 /mcp 和其子路径,默认有效期 1 小时。
  • 内置模式会同时签发刷新令牌(30 天、只能用一次)。客户端到期后自动刷新,用户不必每小时重新登录;同一刷新令牌被重复使用会被视为泄露,整个授权立即撤销。
  • 「OAuth 访问令牌」区按应用汇总用户数、实例数和授权,可停用应用、撤销某个应用的全部授权,也可按应用、用户或状态(有效、可续期、已过期、已撤销)查看明细。用户详情的 API Keys 页签下方也能看到该用户的授权。
  • 由外部授权服务器签发的旧授权显示为「未归属」,可单独撤销。
  • 切换到「关闭」只会停止 OAuth 发现,不会自动撤销已签发的令牌;要立刻阻止使用,请撤销对应授权。
  • 客户端提示无法注册:检查「应用」中是否有启用的应用,回调地址与客户端实际使用的一致。
  • 跳转后停在同意页:确认同意页能读取 request_id,集成密钥具有 oauth.consent 权限;授权请求 10 分钟内有效,过期后需要从客户端重新发起。
  • 401 表示需要重新取得或刷新令牌;用 MCP 令牌调用聊天等其他接口会因作用域不匹配被拒绝(403)。

端点、对象模型和同意页接口见 OAuth 技术参考。