所处位置
注意图中 Fluz 在中间承担的内容:账户创建、登录、双重验证,以及在用户尚未验证身份时的身份核验。你无需构建这些,也永远无法看见其凭证。
开始之前
1
你的应用已配置完成
在 Permissions 选项卡选好了权限,在 OAuth 选项卡注册了重定向 URI,并将
client_id 和 client_secret 存入机密存储。参见 Configure OAuth App。2
你的回调路由已存在且可访问会话存储
它需要读取
state,并与重定向前你持久化的值进行比较。3
Permissions 选项卡中正好是此流程所需的作用域
同意屏由你的应用配置生成,而不是由 authorize 请求生成。Permissions 选项卡中勾选的内容,就是用户被要求批准的内容,因此在把用户引入流程之前先精简它——这是流失最高的步骤,其长度完全取决于该选项卡。完整目录见 Application Scopes。
第 1 步 — 构建 authorize URL
将用户引导至/authorize 端点,并携带以下查询参数。
不存在
scopes 参数。 早期版本的此流程会接受 scopes 查询参数并与你的应用配置取交集。该参数现已被忽略:同意屏上显示的权限完全来自你应用的 Permissions 选项卡。从现有 authorize URL 中移除 scopes 会得到完全相同的同意屏——你可以在方便时随时删除它。环境
编码规则
请对redirect_uri 和 external_id 的值进行 URL 编码。用你语言自带的 URL 编码器构建查询字符串,而不是字符串拼接,这个问题自然就解决了。
完整的 staging 示例:
用户会看到什么
你的应用名称、头像与描述直接来自 Overview 选项卡,权限行则是你选择的作用域,按可读的分组标题展示。如果此页面显示不正确,请在 Configure OAuth App 修正,而不是在你的代码里。
权限列表为只读。用户查看后要么整体接受,要么无法完成授权——没有逐项取消勾选的复选框。如果你的应用使用消费账户选择,那是一个独立控件,仍会显示。
账户选择
在同意屏之前,系统可能会询问用户本次授权适用于哪个 Fluz 账户:个人账户、已有的企业账户,或一个他们想要注册的新企业。具体出现哪一种,取决于应用配置以及用户已有的账户。 对于仅面向个人用户的集成,一切照旧:用户只有一个账户,选择器会被跳过,流程与以往完全相同。如果你传入external_id 且它已解析到此前授权的某个账户,选择器同样会被跳过。
如果你的应用已面向企业启用,请在动手之前阅读 Business Accounts in OAuth——authorize URL 不变,但授权码所解析到的账户可能不是用户的个人账户。
第 2 步 — 用 state 保护流程
参考表将 state 标为可选。在基于重定向的授权流程中,它是你唯一的防线,可防止他人的授权码被植入到你用户的会话中。因此从第一版提交就应纳入,不要事后补加。
1
生成不可猜测的值
至少 128 位,来自加密安全的随机源。不是时间戳、不是用户 ID、不是计数器。
2
在服务端存储,并绑定到浏览器会话
会话存储、签名 Cookie,或以会话为键、TTL 较短的缓存。不要放在全局变量里。
3
回调时进行比较,不匹配则拒绝
缺失、无法识别或已使用过的
state 都意味着放弃该请求——不要去兑换授权码。使用常量时间比较。4
消费它
成功匹配后删除它,防止同一回调被重放。
state 会通过用户的浏览器传递。你可以用它携带一个查找键——是哪位用户、哪个流程、要返回哪个页面——但绝不要在值本身放入任何敏感或受信任的信息。第 3 步 — 处理回调
获批后,Fluz 会将用户重定向到你的redirect_uri,并携带:
如果请求配置有误,重定向会带有错误信息,描述不匹配之处。
第 4 步 — 对齐你实际获得的内容
兑换响应会包含用户批准的作用域数组。该数组,才是你的集成能做什么的事实依据,而不是你的假设。 同意现在是全有或全无,因此某个作用域缺失的常见原因不再是用户拒绝了它,而是它未在应用的 Permissions 选项卡启用,从而根本没有被提供。流程仍会成功完成,但你的 API 调用会在之后失败。在你扩充 Permissions 选项卡之前签发的授权,也要等该用户重新授权后才会包含新增的作用域。 读取返回的作用域,将其与令牌一同持久化,并据此控制你的功能。如果缺少了关键内容,请清楚地告知用户并提供重新运行流程的选项。设计这一时刻
当用户理解他们为何看到同意屏时,转化率会显著提升。- 在重定向前先解释。 在你自己的页面上一句话——“连接你的 Fluz 账户以便我们向你发放款项”——远胜于把人直接丢到权限页面。
- 在情境中触发。 在首次发放款项或首次发卡时触发,而不是埋在账户设置里。
- 优先整页重定向而非弹窗。 弹窗可能被拦截,且流程包含 2FA,甚至可能包含身份验证,这些在小窗口里会很糟糕。如果你需要保持在页面内,请改用嵌入式组件,它正是为此而生的托管内嵌流程。
- 处理好回程。 将用户带回他们所在的位置,并让他们当时想做的事已经能正常运作。
state是你知道他们当时位置的方式。 - 准备好重新授权路径。 刷新令牌会过期,用户也会撤销访问权限。与“连接”流程同时构建“重新连接”流程,而不是在第一张支持工单后才补。
- 考虑直接跳过。 如果你的用户尚未拥有 Fluz 账户,组件可以在一个托管流程中一次性处理注册、验证和同意,无需重定向。参见 Embedded Widgets。
故障排查
后续步骤
兑换授权码
将授权码转换为 access token 和 refresh token。
刷新 access token
保持连接,而无需再次让用户经过同意流程。
配置 OAuth 应用
修复同意屏上显示不正确的内容。
嵌入式组件
通过托管的页内流程完全跳过重定向。