博客
你的应用需要哪种 OAuth 流程?
Web 服务器、单页应用、手机应用、电视、定时任务还是 AI 智能体:每种情况需要哪种 OAuth 流程,以及 FoxAuth 指南如何帮你完成设置。
作者 FoxAuth ·
「我只是想给我的 React 应用加个登录。」对这个请求的回答,通常是一串规范:OAuth 本身是 RFC 6749,PKCE 是 RFC 7636,上面再加 OpenID Connect;如果是移动应用,还有 RFC 8252;如果是电视,有 RFC 8628;如果你有 API,还有 RFC 8707。清单上的每一项都没错,可没有一项告诉你,你的应用需要哪种流程。
我在做 FoxAuth,一个 OAuth 2.1 和 OpenID Connect 服务器。新用户最先提出的,往往就是这个请求。不该从那串清单入手:你需要的 OAuth 流程取决于你所处情况的两个事实,一旦知道了它们,整串清单里你只需要其中一行。下面是这两个问题、每种组合得到的答案,以及我们在 FoxAuth 网站上做的页面,它会替你提出这两个问题。
OAuth 流程取决于谁在操作,以及对人而言代码运行在哪里
第一个问题是谁在操作:一个登录的人、背后没有人的程序,还是 AI 智能体。第二个问题取决于第一个。对人来说,问的是你的代码运行在哪里,因为这决定了每个流程都围绕着的两件事:有没有地方保存密钥,以及能不能打开浏览器。对程序来说,问的是你在构建什么。对智能体来说,问的是它需要访问什么。
在这棵树里,两个编号问题下面的方框是常见的答案,以及各自对应的流程。
同样的决策写成表格,并列出每个答案所依据的规范:
| 谁在操作 | 回答 | 流程 | 规范 |
|---|---|---|---|
| 一个人 | 在服务器上 | 授权码 + PKCE,带密钥 | OpenID Connect、RFC 7636 |
| 一个人 | 在浏览器中 | 授权码 + PKCE,公开应用 | OpenID Connect、RFC 7636 |
| 一个人 | 手机、桌面或终端 | 在系统浏览器中使用授权码 + PKCE | RFC 8252 |
| 一个人 | 没有键盘 | 设备码 | RFC 8628 |
| 一个人 | 在反向代理后面 | Forward auth,在代理处使用 OpenID Connect | OpenID Connect |
| 程序 | 调用 API | Client Credentials | OAuth 2.1 |
| 程序 | 需要保护的 API | 绑定受众的令牌 | RFC 8707 |
| 程序 | 面向开发者的平台 | 动态客户端注册 | RFC 7591、RFC 7592 |
| AI 智能体 | 连接到你的 MCP 服务器 | 客户端元数据文档,令牌只对你的服务器有效 | MCP 授权、RFC 9728 |
| AI 智能体 | 在用户的 Google 中操作 | 令牌交换 | RFC 8693 |
| AI 智能体 | 管理 FoxAuth | 管理 MCP | MCP 授权 |
人这一支的大部分都是同一个流程,即带 PKCE 的授权码流程;各行之间变化的是密钥放在哪里,或者根本没有密钥。在智能体这一支,「智能体需要 OAuth」根据它要访问的东西不同,有三种不同的意思。
在服务器上,你的代码可以保管密钥
有自己服务器的网站,比如 Next.js、Django、Rails 或 Laravel,是最简单也最安全的情况,因为服务器可以保存浏览器永远看不到的密钥。用户点击「登录」,你的服务器把浏览器转到登录页面,用户在那里登录,然后浏览器带着一个一次性授权码回到你的回调地址。接着,你的服务器直接向授权服务器用这个授权码换取令牌,整个过程不经过浏览器,并用自己的密钥证明自己是谁。它还会发送一个 PKCE 校验,下一节会讲到;FoxAuth 默认要求这样做,而密钥额外证明了是哪个应用在请求。
你的服务器不保存任何人的密码;只有授权服务器能看到密码。把密钥放在服务器的环境变量中,绝不要写进代码。只有 localhost 可以使用普通的 http。
在浏览器或手机上,没有密钥,由 PKCE 保护授权码
用 React、Vue 或 Angular 写的单页应用没有地方保存密钥:浏览器代码里的任何东西都是公开的。改由 PKCE 来保护授权码。应用生成一个随机字符串(code_verifier),在登录请求中发送它的哈希(code_challenge),用授权码换取令牌时再出示这个字符串本身。在返回途中被盗的授权码,没有这个字符串就毫无用处,而这个字符串只有那个浏览器标签页知道。应用注册为公开应用,没有密钥。任何人都能使用公开应用的 ID,所以把登录和你的应用绑在一起的,是你登记的回调地址。如果你的库能把令牌保存在内存中,就不要把令牌放进 localStorage。
手机、桌面或终端里的应用使用同一个流程,只有一个区别:登录在系统浏览器中打开,而不是在你应用内部的 WebView 中。用户在自己信任的浏览器里输入密码,你的应用永远看不到它。在桌面或终端上,授权码会回到 http://127.0.0.1,端口就是你的应用此刻监听的那个(RFC 8252 第 7.3 节),所以登记一个回调地址就能覆盖所有端口。手机应用通常通过它声明拥有的 HTTPS 链接,或它自己的 URL scheme(例如 com.example.app:/callback)拿回授权码(第 7.1 和 7.2 节)。
运行在用户自己电脑上、以用户身份登录的 AI 智能体也属于这一类。对 OAuth 来说,它就是一个桌面或终端应用,设置方式也一样。
没有键盘时,用户在手机上登录
电视、机顶盒或自助终端没法合理地要求用户输入密码。设备码流程(RFC 8628)把登录移到第二块屏幕上。设备向授权服务器申请一个简短的代码,把它和一个地址一起显示出来。用户在手机上打开这个地址,输入代码,然后照常登录。与此同时,设备每隔几秒就询问一次代码是否已确认,确认之后就拿到令牌。这个短代码很快就会过期;设备保存的是最后拿到的令牌。轮询不要比响应中给出的间隔更频繁,服务器每回答一次 slow_down,就把间隔再加五秒。
自己没有登录功能的应用,放到你的代理后面
Prometheus 或 Jaeger 的界面、内部仪表盘、某个同事为团队写的工具:很多应用本身没有登录功能,而给它们加上登录也不是你的工作。不如把应用放在 Caddy、Traefik 或 nginx 后面。每个请求到来时,代理都会询问授权服务器这个请求能否通过。还没登录的人会被送到登录页面再送回来;登录之后,代理把请求放行,并在 X-Auth-* 请求头中带上这个人是谁。应用本身不需要改动。
只有当应用只能通过代理访问时,这种做法才安全:从其他途径到达应用的请求会跳过检查。具体步骤见在 Web 应用前加上登录。
没有人参与时,程序以自己的身份登录
后台任务、cron 任务或调用你 API 的另一个服务,都没有人来登录。Client Credentials 就是为它准备的流程:程序出示自己的 ID 和密钥,以自己的名义拿到访问令牌。缓存令牌直到它过期,而不是每次调用都申请新的;如果密钥泄露,就签发一个新的。
面向外部开发者的平台比较少见:开发者通过动态客户端注册(RFC 7591)用一个请求注册自己的应用,再用返回的令牌修改或删除它们。这是整个服务器的设置,所以在 FoxAuth 上,它需要你自己的服务器,而不是 Cloud 项目。
你的 API 拒绝发给另一个 API 的令牌
程序这一情况的另一半,是被调用的 API。签名有效的令牌,不一定是发给你的令牌。如果你的 API 接受授权服务器签发的任何令牌,那么为其他某个 API 签发的令牌也能打开你的 API。资源指示符(RFC 8707)解决了这个问题:客户端在申请令牌时指明 API,服务器把这个 API 写进令牌的 aud 声明,而你的 API 拒绝 aud 是别人的令牌,即使它的签名没有问题。
「AI 智能体需要 OAuth」指的是三件事之一
当智能体连接到你的 MCP 服务器时,你的服务器就是一个普通的 OAuth 资源服务器,关键的检查和任何 API 一样,是受众检查。跳过这项检查会怎样,我在MCP 服务器必须检查令牌是给谁的里详细写过。新的是智能体如何介绍自己。当前的 MCP 授权规范更推荐客户端元数据文档;支持这种文档的智能体宿主不需要事先注册。它给出一份描述自己的文档的地址,用户登录并看到是哪个智能体在请求,然后智能体拿到一个只在你的服务器上有效的令牌。无法发布这种文档的宿主,需要事先在控制台为它注册一个应用,或者使用动态注册;在你自己的服务器上,动态注册由超级管理员开启。步骤见保护你的 MCP 服务器。
如果你不想在 MCP 服务器里写这些代码,就把它放到你的代理后面:每个请求到来时,代理都会请授权服务器检查令牌,以及被调用的工具需要的 scope,MCP 服务器本身不需要为此写任何代码。指南把这列为一个单独的答案,文档里也有在代理处保护 MCP 服务器。
当智能体需要在用户的 Google、GitHub 或 Slack 中操作时,问题就不同了:智能体不应该握着用户的钥匙。用户连接一次自己的账户并表示同意;授权服务器把提供商的令牌加密保存;当智能体需要那个令牌时,它用自己的令牌换取(RFC 8693)这位用户的 Google 令牌,这个令牌应当只用于一次请求,不要保留。用户能看到自己已连接的账户,并可以断开其中任何一个,智能体会立即失去访问权限。
第三种情况是智能体管理授权服务器本身:在你的编程智能体里输入「为我的新应用创建一个应用」。在 FoxAuth 中,这就是管理 MCP。智能体在你登录后连接,以与你完全相同的权限操作,经过与控制台相同的检查和方案限额,它做的每项更改都会写入审计日志,同时记下你的名字和智能体的名字。最危险的操作,例如删除项目,仍然只能在控制台中进行。智能体通过 FoxAuth 自带的 MCP 客户端连接,或者作为超级管理员许可的应用连接;自行注册的应用永远无法连接。FoxAuth Cloud 已经开启了管理 MCP,MCP 工具参考列出了它能做什么。
指南页面替你提出这两个问题
在支持帖里一次一次地解释这棵树,没法规模化,所以我们把它做成了一个页面:FoxAuth 网站上的你需要什么?。它提出同样的两个问题。对每个答案,它会展示这个流程消除的问题以及随之改变的东西、流程本身的每一步、用户会看到什么(登录页面、写明智能体名称的授权同意页面、电视上的一个短代码),以及一份简短的「注意事项」清单,列出值得避开的错误,比如上面提到的 WebView 和 localStorage。
大多数答案最后给出两种设置方式。一种是一个按钮,它会打开你的 FoxAuth Cloud 项目,并已选好这种情况,所以你创建的东西一开始就带着正确的设置。另一种是一段提示词,可以粘贴到 Claude、Cursor 或其他编程智能体中。它写明了流程和你的代码必须做的检查,在有回调地址时给出回调地址,并且在某一步有对应的管理 MCP 工具时,告诉智能体该调用哪一个,这样智能体也能完成控制台那部分工作。
页面还会说明每个答案能在哪里运行。「Cloud 上可用」表示免费的 Cloud 项目现在就能设置它。「自己的服务器」表示它需要一项只有超级管理员才能进行的设置或操作,而 Cloud 租户永远不是超级管理员;开发者自行注册就是其中之一。在两个问题下面,还有一份接下来常见任务的清单,比如添加「使用 Google 登录」、要求第二因素,或者查明某人为什么进不去;另外还有一个单独的选项卡,用于你的客户是一家公司、它的 IT 部门开始要求公司登录和 SCIM 的时候。
先用免费的 Cloud 方案起步,生产环境运行在你自己的服务器上
FoxAuth 当前版本是 2.0.0。上面这棵树里的每个流程它都有,除了动态注册,其余都能在免费的 Cloud 方案上运行。如果你想要以后能迁移到其他服务器的标准流程,如果你要把 MCP 服务器或内部应用放到登录后面,或者你更愿意让编程智能体来完成设置,它就适合你。你可以用两种方式运行它。
FoxAuth Cloud 在测试期间免费,无需信用卡。免费方案的每月活跃用户、应用和 API 数量不限,包含每位管理员最多十个项目,每个项目的地址由你选择,可以通过 Google、Apple、GitHub、Microsoft 或任意 OpenID 提供方登录,还有机器对机器令牌、设备登录、DPoP 和 PAR,以及管理 MCP。你自己的域名可应要求设置。在测试期间加入的团队,付费方案推出后还可以再免费使用一年。它目前还没有 SLA,所以它是起步的地方,而不是生产环境可以依赖的地方。
或者你自己运行同一个服务器。源代码以 FSL-1.1-ALv2 许可证提供,这不是开源许可证:你可以阅读、修改、自托管和再分发它,也可以在它之上开展业务,但不能把它放进与 FoxAuth 竞争的商业产品或服务中提供给他人;每个版本在发布两年后都会变为 Apache 2.0。
在 Cloud 提供 SLA 之前,生产环境请运行在你自己的服务器上。需要独立实例的公司,无论由我们运行还是部署在自己的基础设施上,并带有针对缺陷的响应时间 SLA,都可以在同一个价格页面上申请 Enterprise 邀请。
想得到你的流程和一套可以测试的设置,就在指南上回答这两个问题。