OAuth2 grant 选错了,集成今天能跑,日后就会断
先问谁在调用 API,再把密钥挡在仓库之外,最后做到轮换密钥时夜间任务不中断。
要点速览
- 没有用户的后台任务用客户端凭证模式;有用户参与的流程用授权码 + PKCE;隐式模式和密码模式彻底弃用。
- 密钥绝不放在源代码里:从环境变量读取,仓库应当随时可以开源而不泄露任何东西。
- 轮换密钥要留重叠期:签发新密钥,新旧并行运行,完全切换后,再吊销旧密钥。
到客户现场的第二天,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 客户端,注意文件里没有出现任何凭证字符串:
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 约定轮换日期。
这篇文章对你有帮助吗?
感谢你的反馈!
6 个信源
- OAuth 2.0 client credentials flow on the Microsoft identity platform - Microsoft Learn · 2026-01-30
- RFC 6749: The OAuth 2.0 Authorization Framework · 2012-10
- RFC 9700: Best Current Practice for OAuth 2.0 Security · 2025-01
- PKCE — OAuth 2.0
- Secrets Management - OWASP Cheat Sheet Series
- III. Config: Store config in the environment