FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

技能指南 · 指南

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

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

分享微博

要点速览

  • 没有用户的后台任务用客户端凭证模式;有用户参与的流程用授权码 + PKCE;隐式模式和密码模式彻底弃用。
  • 密钥绝不放在源代码里:从环境变量读取,仓库应当随时可以开源而不泄露任何东西。
  • 轮换密钥要留重叠期:签发新密钥,新旧并行运行,完全切换后,再吊销旧密钥。
选择 OAuth2 授权模式的决策树。根节点问题:是否有用户登录?没有则使用客户端凭证模式(橙色高亮),适用于没有 refresh token 的后台任务,例如凌晨 2 点的订单同步任务;有则使用授权码 + PKCE,且重定向 URI 必须完全匹配。底部横条写着:依据 RFC 9700,不要使用密码模式或隐式模式。
选择 OAuth2 授权模式,先看请求背后是否有用户。来源:RFC 6749、RFC 9700、Microsoft 文档和 oauth.net,详见正文引用。

到客户现场的第二天,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 个信源
路线图上的下一篇 · 阶段 2: 全栈工程能力笔记本里跑通的模型,还不是客户能用的产品从版本管理到受控重训练,五件事让 FDE 接得住第一通投诉电话,Palantir 已写进招聘要求。