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 转接给客户端。业务账号需要对应到网关用户,调用费用才有明确归属。
使用内置授权服务器
Section titled “使用内置授权服务器”- 准备应用目录:在「OAuth 访问令牌」区的「应用」中点击「导入预设」,按需导入 ChatGPT、Claude、Codex、豆包、WorkBuddy,或手工添加应用。客户端注册时按回调地址归属应用,没有匹配应用的客户端无法注册。
- 准备登录与同意页:在业务系统中提供一个页面,接收 Gateway 附带的
request_id,确认用户已登录后,用带oauth.consent权限的集成密钥把用户的同意或拒绝回传给 Gateway,再按返回的地址跳回客户端。不想接入自己的站点时,可以留空,使用内置确认页(用户用自己的 API Key 确认)。 - 转发授权路径:反向代理把
/oauth/*与/.well-known/oauth-authorization-server转发到 Proxy,与/mcp使用同一公开域名。 - 保存设置:选择「内置授权服务器」,填写「本 Gateway 的公开地址(issuer)」和「登录与同意页(可选)」,保存。
- 用真实客户端验收:逐个完成授权、工具调用、刷新和撤销,确认请求日志中显示的应用名与所属用户正确。
从外部授权服务器切换过来时,已有授权会在访问令牌过期后失效,用户需要重新授权。完整步骤见 0036 迁移说明。
令牌、刷新与撤销
Section titled “令牌、刷新与撤销”- MCP 访问令牌以
oat_开头,与用户 API Key 分开存储,只能访问/mcp和其子路径,默认有效期 1 小时。 - 内置模式会同时签发刷新令牌(30 天、只能用一次)。客户端到期后自动刷新,用户不必每小时重新登录;同一刷新令牌被重复使用会被视为泄露,整个授权立即撤销。
- 「OAuth 访问令牌」区按应用汇总用户数、实例数和授权,可停用应用、撤销某个应用的全部授权,也可按应用、用户或状态(有效、可续期、已过期、已撤销)查看明细。用户详情的 API Keys 页签下方也能看到该用户的授权。
- 由外部授权服务器签发的旧授权显示为「未归属」,可单独撤销。
- 切换到「关闭」只会停止 OAuth 发现,不会自动撤销已签发的令牌;要立刻阻止使用,请撤销对应授权。
排查授权问题
Section titled “排查授权问题”- 客户端提示无法注册:检查「应用」中是否有启用的应用,回调地址与客户端实际使用的一致。
- 跳转后停在同意页:确认同意页能读取
request_id,集成密钥具有oauth.consent权限;授权请求 10 分钟内有效,过期后需要从客户端重新发起。 - 401 表示需要重新取得或刷新令牌;用 MCP 令牌调用聊天等其他接口会因作用域不匹配被拒绝(403)。
端点、对象模型和同意页接口见 OAuth 技术参考。