Skip to main content
这是用户决定是否允许你的应用访问其 Fluz 账户的步骤。你将他们重定向到 Fluz,他们批准后,Fluz 会携带短期有效的授权码将他们重定向回你这边。 本页之前的都是配置。本页之后的是令牌处理。这是用户唯一能看到的步骤。

所处位置

注意图中 Fluz 在中间承担的内容:账户创建、登录、双重验证,以及在用户尚未验证身份时的身份核验。你无需构建这些,也永远无法看见其凭证。

开始之前

1

你的应用已配置完成

Permissions 选项卡设置了作用域上限,在 OAuth 选项卡注册了重定向 URI,并将 client_idclient_secret 存入机密存储。参见 Configure OAuth App
2

你的回调路由已存在且可访问会话存储

它需要读取 state,并与重定向前你持久化的值进行比较。
3

你清楚此流程需要哪些作用域

完整列表见 Authentication。只请求最小必要集合——同意屏是流失最高的步骤,其长度取决于此列表。

第 1 步 — 构建 authorize URL

将用户引导至 /authorize 端点,并携带以下查询参数。
参数名是 scopes,复数形式——不是 OAuth 2.0 基础规范中的 scope。如果你使用通用 OAuth 客户端库,这就是你需要覆盖的字段。

环境

编码规则

作用域之间的空格必须编码为 %20。同时也要对 redirect_uri 的值进行 URL 编码;用你语言自带的 URL 编码器构建查询字符串,而不是字符串拼接,这些问题自然就解决了。 完整的 staging 示例:

用户会看到什么

Sample OAuth permissions page 你的应用名称、头像与描述直接来自 Overview 选项卡,权限行则是你选择的作用域,按可读的分组标题展示。如果此页面显示不正确,请在 Configure OAuth App 修正,而不是在你的代码里。

第 2 步 — 用 state 保护流程

参考表将 state 标为可选。在基于重定向的授权流程中,它是你唯一的防线,可防止他人的授权码被植入到你用户的会话中。因此从第一版提交就应纳入,不要事后补加。
1

生成不可猜测的值

至少 128 位,来自加密安全的随机源。不是时间戳、不是用户 ID、不是计数器。
2

在服务端存储,并绑定到浏览器会话

会话存储、签名 Cookie,或以会话为键、TTL 较短的缓存。不要放在全局变量里。
3

回调时进行比较,不匹配则拒绝

缺失、无法识别或已使用过的 state 都意味着放弃该请求——不要去兑换授权码。使用常量时间比较。
4

消费它

成功匹配后删除它,防止同一回调被重放。
state 会通过用户的浏览器传递。你可以用它携带一个查找键——是哪位用户、哪个流程、要返回哪个页面——但绝不要在值本身放入任何敏感或受信任的信息。

第 3 步 — 处理回调

获批后,Fluz 会将用户重定向到你的 redirect_uri,并携带: 如果请求配置有误,重定向会带有错误信息,描述不匹配之处。
立即、且仅一次、从你的服务器兑换授权码。它是一次性、短期有效的。让你的回调路由具备幂等性——用户刷新页面、链接预取器或浏览器重试都会第二次命中它,第二次尝试不得破坏状态或向已成功的用户显示错误。
下一步:Exchange an OAuth authorization code

第 4 步 — 对齐你实际获得的内容

兑换响应会包含用户批准的作用域数组。该数组,才是你的集成能做什么的事实依据,而不是你的请求。 你请求的某个作用域可能缺失,原因可能是用户拒绝了它,或它未在应用的 Permissions 选项卡启用——此时它会被静默丢弃,而非被拒绝。无论哪种情况,流程都会成功完成,但你的 API 调用会在之后失败。 读取返回的作用域,将其与令牌一同持久化,并据此控制你的功能。如果缺少了关键内容,请清楚地告知用户并提供重新运行流程的选项。

设计这一时刻

当用户理解他们为何看到同意屏时,转化率会显著提升。
  • 在重定向前先解释。 在你自己的页面上一句话——“连接你的 Fluz 账户以便我们向你发放款项”——远胜于把人直接丢到权限页面。
  • 在情境中触发。 在首次发放款项或首次发卡时触发,而不是埋在账户设置里。
  • 优先整页重定向而非弹窗。 弹窗可能被拦截,且流程包含 2FA,甚至可能包含身份验证,这些在小窗口里会很糟糕。如果你需要保持在页面内,请改用嵌入式组件,它正是为此而生的托管内嵌流程。
  • 处理好回程。 将用户带回他们所在的位置,并让他们当时想做的事已经能正常运作。state 是你知道他们当时位置的方式。
  • 准备好重新授权路径。 刷新令牌会过期,用户也会撤销访问权限。与“连接”流程同时构建“重新连接”流程,而不是在第一张支持工单后才补。
  • 考虑直接跳过。 如果你的用户尚未拥有 Fluz 账户,组件可以在一个托管流程中一次性处理注册、验证和同意,无需重定向。参见 Embedded Widgets

故障排查


后续步骤

兑换授权码

将授权码转换为 access token 和 refresh token。

刷新 access token

保持连接,而无需再次让用户经过同意流程。

配置 OAuth 应用

修复同意屏上显示不正确的内容。

嵌入式组件

通过托管的页内流程完全跳过重定向。