OAuth 回调 HTML 桥页:Provider 只能 GET,换票靠 POST,绑定靠 state

Hello,我是小兔大白糖。 某社交 OAuth 授权成功后,Provider 只肯 302 GET 到你登记过的 redirect URI——App / SPA 却往往接不住这一下。写成这篇,给要做 OAuth 回调收口选型 的初中级后端与客户端同学:业界常见模式对比,不是某家仓库说明书。
估计阅读时间:8 分钟
目录
为什么现在要关心
Provider 只会 GET 到登记过的 redirect URI;业务换票与「绑到哪次登录」是你自己的合同,别指望快递进客厅。
第三方 OAuth(1.0a / 2.0)授权完成后,Provider 把 code / oauth_verifier 等挂在 query 上,302 到你预先登记的地址。麻烦通常不在协议本身,而在渠道错位:
| 场景 | 卡住点 |
|---|---|
| 原生 App / WebView | 系统浏览器打开了回调 URL,App 进程拿不到结果 |
| SPA | 期望走 POST /auth/callback 换票,不愿让 GET 回调直接碰业务 |
| 纯前端读 query 再打 API | 要处理同站 Cookie、CORS 与凭证策略 |
一种常见折中:回调 URI 先返回一张 HTML「桥页」(HTML Bridge)——地址栏仍是 Provider 回来的 URL;页内 JS 读一次性句柄,再 POST 到自家换票接口,最后 deep link / 关窗 / 跳回 App。
心智模型:快递柜与前台代签
快递员只送到你填的柜;桥页是小区前台;state 是取件码。
- Provider = 快递员:只送到登记过的柜(redirect URI),不会跑进你家客厅(App 进程)。
- HTML 桥页 = 小区前台:先签收(渲染页、读单号),再打电话叫你来取(POST 换票 / deep link)。
state= 取件码:证明「这是你发起的那一单」,不是别人塞进来的单号。
类比局限:快递柜解释「谁能收、怎么转交」;解释不了各 Provider 对 state 长度、PKCE、以及 OAuth1.0a 字段名的细节差异——字段按协议分,模式可以通用。
硬规则:GET、POST、state
三条硬规则:登记 URI 只接 GET;换票尽量 POST 且密钥在服务端;绑定意图用 state,禁止 redirect query 塞稳定 user_id。
- Provider 只能 GET 到登记过的 redirect URI。 业务换票尽量用服务端或桥页发起的 POST;长期密钥(client secret 等)别放进前端。
- 绑定登录意图用
state(或不透明服务端 session),不要把稳定user_id明文塞进 redirect query。 Query 会进浏览器历史、Referer、CDN / 接入层 access log——稳定身份一旦进 URL,就按「公开面」处理。 - 桥页只做「搬运 + 换票触发」: 读一次性 verifier / code → POST 自家 API → 清理地址栏或立刻跳转。不要在 HTML 里硬编码环境主机名与密钥。
为什么反对 ?user_id=...:它可预测、可篡改、还会进日志与截图。正确做法是授权开始时由后端生成不可猜测的 state,与当前会话绑定;回调时校验「这张单是不是你发起的」。
四种收口模式
Web 优先服务端整段换票;必须在浏览器里「看见」回调再回 App 时用桥页;原生优先 App Link;禁止把「前端纯读 query」当生产默认。
| 模式 | 做法 | 代价 / 副作用 | 适用 |
|---|---|---|---|
| A. 服务端整段换票 | redirect 打到后端;后端用 code 换 token,再 302 到前端成功页 | 实现集中;必须正确处理 CSRF / state | 纯 Web 主流默认 |
| B. HTML 桥页 + POST | GET 回 HTML;JS 读 query → POST 换票接口 | 多一张静态页;要防 XSS、禁止硬编码环境域名 | App WebView、需前端收口再回 App |
| C. Custom URL Scheme / App Link | redirect 到 myapp://oauth?... 或 Universal / App Link | 系统与商店配置重;伪造 scheme 有风险 | 原生 App |
| D. 前端纯读 query | SPA 路由直接吃 code | code 易进日志;刷新易重复换票 | 仅短时 demo |
教学倾向:Web → A;浏览器中转再回 App → B;原生尽量 C(仍建议 state)。D 不当生产默认。
桥页模式的代价要说清楚:多一次渲染与一次同源 POST;若桥页被 XSS,一次性 code 可能被偷走——所以 CSP、短时 code、服务端校验 state 不是可选项。
桥页伪流程(教学)
完整链路:发起时存 state → Provider GET 回桥页 → POST 换票 → 立刻清 URL / 跳转。
1. App/Web 已有会话 → 向自家后端要 authorize URL
后端生成 state,写入会话;redirect_uri 仅用已登记路径
2. 用户在 Provider 同意授权
3. Provider 302 → GET /oauth/callback?code=...&state=...
4. 该路径返回 callback.html(200 text/html) // 桥页
5. JS 读 code/state → POST /oauth/exchange { code, state }
6. 后端校验 state、换 token、绑定用户 → 返回成功
7. 桥页 location.replace(deepLink) 或展示「可关闭」反例(不要照着做):
redirect_uri?...&user_id=<稳定用户 id> // 身份进公开 URL
HTML 写死 https://env-host/api/... // 环境耦合
桥页长期展示 access_token / 挂在 hash // 截图即泄露OAuth1.0a 常见是 oauth_token + oauth_verifier,OAuth2 常见是 code(可加 PKCE)。桥页「GET 收 → POST 换」的模式通用,字段名按协议分,不要混谈成一套参数。
与 PII / 日志红线
callback URL 上的 code / oauth_verifier 是高敏感一次性句柄;日志只记 state 哈希或 request_id,不记全文 query。
access log、错误页、客服截图都可能带走整段 URL。桥页与后端应默认按「查询串含秘密」处理:成功后立刻 history.replaceState 或跳转;错误响应不要回显完整 query。同站姊妹篇:PII 别进 Logs/URL/Error。
常见坑
多数事故来自「身份绑错」和「秘密留在地址栏」,不是 Provider 抽风。
| 坑 | 为什么危险 | 怎么改 |
|---|---|---|
把业务 user_id 当 state | 可预测、可篡改、进日志 | 用不透明随机 state,服务端会话绑定 |
| 换票成功后地址栏仍留 code | 分享 / 截图即泄露 | replaceState 或立刻 deep link |
只校验「有 code」、不校验 state | CSRF:code 绑到攻击者会话 | 发起与回调成对校验 |
| 桥页 / 仓库硬编码环境主机名 | 一环境一改;易把 secret 一并写死 | 相对路径或构建期注入 |
| 前端持有 client secret | 密钥等于公开 | 换票只在服务端 |
选型结论
- 先问渠道: 纯 Web → A;WebView / 系统浏览器中转回 App → B 或 C。
- 一律用
state(或服务端 session)绑定发起方; redirect query 不放稳定用户标识。 - 桥页配置用相对路径或构建注入;禁止仓库硬编码环境主机名。
- 换票只在服务端持 client secret; 桥页最多持一次性 code / verifier。
- 成功后立刻清 URL; 日志按 PII 红线处理 query——详见 PII 别进 Logs/URL/Error。
一句话带走:快递员只送到柜;前台代签可以,但取件码必须是你发出去的那一枚——别把自家门牌号写在运单公开栏上。