# OAuth2 grant 选错了，集成今天能跑，日后就会断

> 先问谁在调用 API，再把密钥挡在仓库之外，最后做到轮换密钥时夜间任务不中断。

原文: https://fdetimes.net/zh/guides/oauth2-grant-choice-secret-rotation/

到客户现场的第二天，IT 团队在聊天里发来一个 `client_id` 和一个 `client_secret`，只附了一句话：“这是订单 API，每天晚上拉一次数据就行。”写第一行代码之前，你要先做两个决定：用哪种 OAuth2 授权模式，以及这串密钥放在哪里。

授权模式选错，集成今天能跑，等客户收紧策略就会出问题。密钥一旦混进仓库，一次误推就足以毁掉你花几周建立起来的信任。

下文以一个订单同步任务为例，从头走到尾：选择授权模式，编写客户端，存放密钥，再在不中断夜间任务的前提下完成轮换。

## 选择授权模式，先问一个问题：谁在调用 API？

OAuth2 的授权模式有很多，但在现场只需要问一个问题：这个请求背后有没有用户？RFC 6749 把客户端凭证模式（client credentials）描述为客户端代表自身操作时使用的授权模式。Microsoft 文档说得更直白：它是后台运行、没有用户直接参与的服务器到服务器交互的常见选择。

凌晨 2 点拉订单的任务正好符合。没有人登录，只有你的服务。这种模式只适合能保管密钥的客户端，也就是运行在你可控服务器上的代码，而不是装在用户电脑上的应用。

如果有真实用户，比如仓库员工登录使用的内部看板，情况就完全不同了，这时要用授权码模式（authorization code）。下表列出了你会遇到的几种情况：

| 客户现场的情况 | 使用的授权模式 | 说明 |
|---|---|---|
| 后台任务、守护进程、服务账号 | 客户端凭证模式 | 没有 refresh token；过期后重新申请令牌 |
| 有用户登录的 Web 应用 | 授权码 + PKCE | 重定向 URI 必须完全匹配 |
| SPA 或移动应用（公共客户端） | 授权码 + PKCE | refresh token 必须绑定发送方，或启用轮换 |
| 客户建议“直接用用户名/密码” | 不要用密码模式 | 这种模式会把用户凭证暴露给客户端 |
| 旧文档描述了隐式流程 | 不要用隐式模式 | RFC 9700 建议客户端不要使用 |

最后两行往往需要你礼貌地说“不”。RFC 9700 是 OAuth 2.0 安全的最佳当前实践文档，其中明确指出，密码模式会以不安全的方式把资源所有者的凭证暴露给客户端。客户把它当作捷径提出来时，你手里有一份标准文档可以引用。

## 有用户时：PKCE、重定向 URI 与 refresh token

仓库看板使用授权码模式。oauth.net 建议所有这类流程都使用 PKCE，包括运行在服务器上的 Web 应用。但要记住，PKCE 不是客户端认证，也不能替代 client secret。服务器端 Web 应用依然要像后台任务一样小心保管密钥。

RFC 9700 要求授权服务器对重定向 URI 做精确匹配。因此在客户那边注册应用时，要把开发、预发布和生产环境的每个 URI 完整列出，不要申请通配符。对于 SPA 这类公共客户端，refresh token 必须绑定发送方，或启用轮换。

## 从头写一个客户端凭证模式的客户端

回到订单同步任务。下面是一个最简的 Python 客户端，注意文件里没有出现任何凭证字符串：

```python
import os, time, requests

TOKEN_URL = os.environ["CUSTOMER_TOKEN_URL"]
CLIENT_ID = os.environ["CUSTOMER_CLIENT_ID"]
CLIENT_SECRET = os.environ["CUSTOMER_CLIENT_SECRET"]
SCOPE = os.environ.get("CUSTOMER_SCOPE", "")

_cache = {"token": None, "exp": 0.0}

def get_token(force=False):
    if not force and _cache["token"] and time.time() < _cache["exp"] - 60:
        return _cache["token"]
    resp = requests.post(TOKEN_URL, data={
        "grant_type": "client_credentials",
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
        "scope": SCOPE,
    }, timeout=10)
    resp.raise_for_status()
    body = resp.json()
    _cache["token"] = body["access_token"]
    _cache["exp"] = time.time() + body.get("expires_in", 300)
    return _cache["token"]

def call_api(url):
    r = requests.get(url, headers={"Authorization": f"Bearer {get_token()}"}, timeout=30)
    if r.status_code == 401:
        r = requests.get(url, headers={"Authorization": f"Bearer {get_token(force=True)}"}, timeout=30)
    r.raise_for_status()
    return r.json()
```

客户端凭证模式不提供 refresh token。Microsoft 文档说明，令牌过期后，再次调用 `/token` 端点获取新的访问令牌即可。上面的代码正是这样做的，并加了两个习惯：在过期前 60 秒申请新令牌；遇到 401 时只重试一次。

只重试一次，真正的错误才不会被掩盖。如果新令牌仍被拒绝，问题出在权限或 scope 上，日志应当立刻反映出来，而不是半夜有个循环不停地请求 `/token`。

## 密钥不该出现在仓库里

Microsoft 明确规定，应用凭证绝不能发布在源代码中、嵌入网页，或随广泛分发的原生应用一起发布。这听起来理所当然，但 OWASP 指出，仍有许多组织把明文密钥直接硬编码在源代码里。在客户项目中，你遇到这种情况的次数会比预想的多。

十二要素应用（twelve-factor app）给出了一个简单做法：把配置（包括凭证）存放在环境变量中。它附带的检验标准很实用：代码库能否随时开源，而不暴露任何一个凭证？上面的代码能通过这项检验。

在开发机上，把变量写进 `.env` 文件，并在第一次提交时就把这个文件加入 `.gitignore`。在生产环境中，问清客户用的是哪种密钥管理器，让平台在运行时注入环境变量。

集成稳定之后，可以提议升级。Microsoft 允许服务用证书或联合凭证代替共享密钥进行认证。对于长期运行的任务，值得和安全团队讨论一下。

## 夜间任务照常运行，同时轮换密钥

OWASP 建议定期轮换密钥，让被盗的凭证只在很短时间内可用。难点在于轮换时不能中断凌晨 2 点的任务。方法是始终留出一段重叠期，让新旧密钥同时有效。

设想订单任务的一份轮换计划，前提是客户的身份系统允许一个应用同时持有两个密钥（需向 IT 确认）。周一，IT 在密钥 A 仍有效时签发密钥 B。你在密钥管理器中把 `CUSTOMER_CLIENT_SECRET` 更新为 B，然后重新部署。

周二和周三是并行运行期。新实例使用 B；掉队的实例或尚未重启的实例仍能用 A 正常工作。你每晚查看日志，确认每个发往 `/token` 的请求都成功。

周四，确定已经没有任何地方在用 A 之后，请 IT 吊销它。然后你特意用 A 调用一次 `/token`，确认请求被拒绝。这一步证明 A 确实已经失效，而不是“应该已经吊销了”。

如果代码从环境变量读取密钥，整个过程不需要改动一行代码。这是把密钥移出代码最实际的回报。

## 现场常见错误

最常见的错误是：当前文件已经干净，密钥却还留在提交历史里。运行 `git log -p -S "client_secret"` 就能找出来。一旦发现，第一件事是通知客户吊销并签发新密钥；清理仓库历史放在后面，因为泄露的密钥必须当作已不可用。

其次是仅仅因为客户想快，就接受密码模式。解决办法：引用 RFC 9700，然后对后台任务提议客户端凭证模式，有用户登录时则提议授权码 + PKCE。

还有不少人把 PKCE 当作能替代密钥的护盾。解决办法：对于服务器端 Web 应用，依然像后台任务那样把 client secret 放在密钥管理器中，PKCE 只作为额外的一层保护。

最后一种是缓存了令牌却忘了它的有效期，结果上线第一晚就遇到一波 401。解决办法：根据 `expires_in` 记录过期时间，在过期前申请新令牌，遇到 401 只重试一次，就像上面的代码那样。

**要点:** 写在代码里的密钥迟早会泄露；无法轮换的密钥，一旦泄露就会长期处于泄露状态。

## 向雇主证明你会这些

如果你做过客户系统集成，并通过了对方安全团队的审查，就要把这段经历写具体。

简历上不要写“熟悉 OAuth2”，而要写一句具体的话。例如：“使用客户端凭证模式构建同步任务，密钥从密钥管理器加载，并按计划零停机轮换”。面试时，讲清上面那份四天的轮换计划，比背诵各种授权模式的定义有说服力得多。

下次再有人在聊天里发给你 client secret，把它当作第一件要清理的事：先移进密钥管理器，再和 IT 约定轮换日期。

**本周动手试试:**

- 在你手头的某个集成仓库上运行 git log -p -S "secret"（也试试 "client_secret" 和 "password"），记录每一个曾经包含凭证的提交。
- 做一次十二要素检验：如果这个仓库明天早上公开，会不会泄露任何凭证？逐一列出这些位置，把它们移进环境变量。
- 为一个真实的集成写一页密钥轮换手册：谁签发新密钥，在哪里加载，新旧并行多长时间，何时吊销旧密钥。

## 信源

- [OAuth 2.0 client credentials flow on the Microsoft identity platform - Microsoft Learn](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow)

- [RFC 6749: The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749)

- [RFC 9700: Best Current Practice for OAuth 2.0 Security](https://datatracker.ietf.org/doc/html/rfc9700)

- [PKCE — OAuth 2.0](https://oauth.net/2/pkce/)

- [Secrets Management - OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html)

- [III. Config: Store config in the environment](https://12factor.net/config)
