GitHub OAuth 支持多个回调地址后怎么改造：刷新令牌与白名单核对

GitHub 最近给 OAuth App 新增了多个回调地址配置、通配符匹配，还有访问令牌过期+刷新的配套能力。对做第三方授权对接的开发团队来说，这个更新的核心价值根本不是“多填几个跳转地址”这么表面，你完全可以把测试、预发布、生产整套部署环境都归集到同一个OAuth应用下管理，还能把之前永久生效的长时效访问令牌，换成可自动轮换的令牌对。

改造时先把每个环境的回调地址做成明确白名单，再让授权请求和换票请求携带同一个 redirect_uri；启用过期令牌后，数据库必须原子替换旧刷新令牌，否则下一次轮换很容易把用户踢回登录页。

这次 GitHub OAuth 更新解决了什么

过去一个 OAuth App 的回调配置通常只围绕一个地址展开。开发环境换域名、预发布环境换入口时，团队要么临时修改配置，要么为每个环境单独注册应用。GitHub 现在允许在应用设置中继续点击 Add callback URL，最多录入 10 个回调地址，授权请求可以根据当前环境选择对应的 redirect_uri。

这次同步上线的还有两项安全相关的配套能力：访问令牌可以设置为固定过期时长，并通过刷新令牌换取新的令牌对；每个回调地址还可以单独配置通配匹配规则。这里要注意区分开两个功能的使用场景：多个精确地址解决多环境授权切换的需求，通配匹配仅服务于完全受控的子域场景，二者是完全独立的开关，不要混为一谈。

先把回调地址整理成可审计的白名单

建议先在配置文件中维护环境到回调地址的映射，不要在登录按钮逻辑里临时拼接当前域名生成跳转地址。下面的例子只展示基础结构，里面的域名要全部替换成你自己实际控制的站点地址：

oauth:
  callbacks:
    dev: https://dev.example.com/auth/github/callback
    staging: https://staging.example.com/auth/github/callback
    prod: https://app.example.com/auth/github/callback

在 GitHub 应用设置页逐条录入这些地址，同步记录三项核对结果：协议是否为 HTTPS、跳转路径是否完全匹配、有没有遗留的旧域名躺在配置列表里。不要把支持用户上传自定义内容的域名直接放进回调地址列表，也不要用一个可变查询参数代替固定跳转路径。

通配匹配的安全边界很容易被低估。它可以覆盖你完全可控的子域或者额外路径，但如果同一主域下存在用户自主提交内容、可自定义跳转或者不受开发团队管控的路由，拿到的授权码就可能被带到你完全意料之外的位置。没有明确的路由隔离和完整域名控制权的时候，保持这个功能关闭会稳妥很多。

授权与换票必须使用同一条 redirect_uri

多回调地址不会改变 OAuth 授权码流程。应用发起授权时选择一个已登记的地址，GitHub 回调时带回 code 和 state，服务端再把授权码换成令牌。换票请求中再次发送同一个 redirect_uri，可以让服务端确认这次换票对应的回调位置。

const callback = callbackByEnv[process.env.APP_ENV];
const authorizeUrl = new URL("https://github.com/login/oauth/authorize");
authorizeUrl.searchParams.set("client_id", clientId);
authorizeUrl.searchParams.set("redirect_uri", callback);
authorizeUrl.searchParams.set("state", signedState);
authorizeUrl.searchParams.set("scope", "read:user user:email offline_access");

// 回调处理时再次使用同一个 callback
const token = await exchangeCode({ code, redirect_uri: callback });

state 仍然要做服务端校验，不能因为回调地址变多就省掉。若使用 PKCE，换票时还要带回原始的 code_verifier。登录成功后，再用访问令牌重新核对当前用户身份，避免把不同账号的会话混在一起。

启用过期令牌后，存储逻辑要从“覆盖一次”改成轮换

GitHub 官方文档里标注，过期访问令牌的有效时长是 8 小时，刷新令牌如果连续 6 个月没有使用就会自动过期。每次调用刷新接口都会返回新的访问令牌和新的刷新令牌，旧的刷新令牌和旧访问令牌后续都无法继续使用。因此数据库不能只存一个长期有效的 access token，至少要预留字段保存当前在用的访问令牌、刷新令牌、过期时间和最后一次轮换时间。

POST https://github.com/login/oauth/access_token
Content-Type: application/json

{
  "client_id": "应用的 Client ID",
  "client_secret": "服务端保存的 Client Secret",
  "grant_type": "refresh_token",
  "refresh_token": "数据库中的当前刷新令牌"
}

收到新令牌后，用单条数据库事务完成全量替换，同时做好并发控制，保证同一时间同一个用户的多并发请求里只有一个刷新动作能执行成功。一个简单的实现逻辑是：更新条件里带上旧刷新令牌的校验摘要，如果执行后受影响行数为 0 就重新读取数据库里的最新值，不要拿着已经失效的旧值重复发起刷新请求。

如果响应是 bad_refresh_token，不要无限重试。刷新令牌可能已过期、已被使用过，或用户撤销了授权；此时清理本地令牌，让用户重新走授权流程更符合真实状态。

用三条路径验收，而不是只看“能登录”

调整完配置后，至少覆盖下面三组检查项：

1. 环境切换：分别从 dev、staging、prod 发起授权，确认每次回调都回到预期地址，且换票请求中的 redirect_uri 与授权请求一致。
2. 安全边界：用未登记的域名、错误路径和不受控子域发起授权请求，确认请求直接被GitHub侧拒绝；如果启用了通配匹配，再单独验证规则的覆盖范围完全符合预期。
3. 令牌轮换：等访问令牌临近过期时间时，执行一次刷新操作，确认新旧刷新令牌的状态符合预期；随后用已经失效的旧刷新令牌再次发起刷新请求，服务端要正常进入重新授权或者明确报错的分支。

运行日志里绝对不要记录 Client Secret、访问令牌或者刷新令牌的明文。可以保存环境名、回调地址的短摘要、授权结果、令牌过期时间和轮换结果这些信息，既能快速定位哪套环境出了问题，也不会把高敏感的凭据直接写入排查日志。

哪些场景不适合立刻打开新能力

如果你的应用还没有集中管理所有回调地址、没有做刷新令牌的安全存储，或者多个服务节点可能同时刷新同一个用户的令牌，先把这些基础能力补齐，再开启过期令牌相关的功能。功能开关本身不会自动帮你解决并发刷新和会话迁移的问题。

如果团队只是想支持一个新的固定域名，登记第二个精确回调地址即可，不必顺手开启通配匹配。若应用同时支持 GitHub Enterprise Server，还要确认目标实例是否支持过期令牌；官方文档提示，某些实例可能返回非过期访问令牌且不返回刷新令牌，代码不能假设 refresh_token 一定存在。

相关问题

多个回调地址是否需要为每个环境注册一个 OAuth App？

不一定。GitHub OAuth App 最多可以登记 10 个回调地址，同一个应用完全可以覆盖多个受控的开发测试环境。只有在权限边界、数据隔离或者团队责任划分完全不同的场景下，才有必要拆成多个独立的应用单独配置。

刷新令牌能不能重复使用？

不要按长期有效凭据的逻辑来使用。每次刷新操作完成后要立刻保存响应里返回的新刷新令牌，旧的令牌值直接标记为失效；并发请求场景下要用条件更新或者单飞机制，避免两个请求同时消费同一个还未作废的旧值。

只增加一个回调地址，需要改代码吗？

如果代码已经把授权请求和换票请求的 redirect_uri 统一管理，通常只需要新增配置并补一组环境验收。若地址散落在前端、服务端和部署变量中，应先集中配置，避免只改了其中一处。

最后的落地清单

• 精确登记每个环境的 HTTPS 回调地址，所有配置变更都保留可追溯记录。
• 没有强路由隔离的前提下不要随便开启通配匹配。
• 授权和换票使用同一个 redirect_uri，并继续校验 state 与 PKCE。
• 启用过期令牌之前，提前准备好刷新令牌的安全存储、原子轮换逻辑和重新授权的异常处理分支。
• 完成环境切换、越界地址拦截、旧令牌复用拦截三组验收测试后，再逐步扩大功能的开放范围。