跳到正文
FoxAuth

博客

你的应用需要哪种 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 智能体。第二个问题取决于第一个。对人来说,问的是你的代码运行在哪里,因为这决定了每个流程都围绕着的两件事:有没有地方保存密钥,以及能不能打开浏览器。对程序来说,问的是你在构建什么。对智能体来说,问的是它需要访问什么。

在这棵树里,两个编号问题下面的方框是常见的答案,以及各自对应的流程。

用两个问题选择 OAuth 流程。谁在操作:一个人、一个程序或一个 AI 智能体。对人来说,代码运行在哪里:服务器使用带 PKCE 和密钥的授权码流程;浏览器应用使用带 PKCE、没有密钥的授权码流程;手机、桌面或终端应用通过系统浏览器使用 PKCE;没有键盘的设备使用设备码流程;反向代理后面的应用在代理处使用 forward auth。对程序来说,你在构建什么:调用 API 的程序使用 Client Credentials;需要保护的 API 使用绑定受众的令牌;面向其他开发者的平台使用动态客户端注册。对智能体来说,它需要什么:直接或通过你的代理连接你的 MCP 服务器,使用客户端元数据文档和只对你的服务器有效的令牌;在用户的 Google 中操作,使用令牌交换;管理 FoxAuth,使用管理 MCP。1 谁在操作?一个人没有人参与的程序AI 智能体2 你的代码运行在哪里?2 你在构建什么?2 智能体需要什么?在服务器上授权码 + PKCE,带密钥在浏览器中授权码 + PKCE,没有密钥手机、桌面或终端在系统浏览器中使用授权码 + PKCE没有键盘的设备设备码(RFC 8628)在反向代理后面在代理处做 forward auth调用 API 的程序Client Credentials需要保护的 API绑定受众的令牌(RFC 8707)面向开发者的平台动态注册(RFC 7591)连接到你的 MCP 服务器元数据 URL,令牌只给你的服务器在用户的 Google 中操作令牌交换(RFC 8693)管理 FoxAuth 本身管理 MCP运行在用户自己电脑上、以用户身份登录的智能体,就是桌面或终端应用除设备码流程外,每个面向人的流程都是基于授权码 + PKCE 的 OpenID Connect。

同样的决策写成表格,并列出每个答案所依据的规范:

谁在操作 回答 流程 规范
一个人 在服务器上 授权码 + 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 邀请。

想得到你的流程和一套可以测试的设置,就在指南上回答这两个问题。