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