多数团队第一次接触 OAuth 和 OpenID Connect,都是因为产品需要一个登录按钮。有人接入授权码流程,API 开始检查 Bearer Token,再加一个 scope 校验,功能就上线了。问题是,这条路径把真正发生安全决策的地方藏了起来。

决定调用者能否获得令牌的,是授权服务器。它决定主体身份、目标 API、认证强度、授权范围、令牌时效,以及客户端怎样证明自己。网关可以检查签名、受众和过期时间,但不应该让每条路由重新发明联邦登录、MFA、租户映射与撤销机制。

核心判断

把身份层当作基础设施运行,而不是登录功能的附属品。 签发策略一旦漂移,即使 OpenAPI 文档没有任何变化,API 行为也会发生变化。

登录完成之前,架构已经做了选择

SSO 和社交登录只是用户体验。登录屏幕背后,身份系统已经为令牌写入了用户、租户、角色或群组、认证方式以及发起请求的客户端。正因如此,真正高风险的默认值通常不在登录页,而在令牌签发策略里。

  • 公共客户端是否强制使用 PKCE,避免授权码被截获后重放?
  • 访问令牌是否绑定到明确的 API 受众,还是所有共享签名密钥的服务都能接受?
  • 机密客户端使用轮换密钥,还是部署流水线里躺着一个长期不变的静态秘密?
  • 一分钟内失效的短期令牌、可刷新令牌,还是能持续数小时的宽泛凭证?

OAuth 2.0 Security Best Current Practice(RFC 9700)可以从“网关建议”读成一个更准确的清单:收紧令牌可以做什么,关闭不安全流程,并在签发源头强化客户端。把签发决策留在身份层,把粗粒度的验签、受众与时效检查放在边缘,职责才会清晰。

身份配置漂移,会以 API 故障出现

没有人会因为“身份提供商”被半夜叫醒。团队通常看到的是 403 突然增加、一个客户看见另一个客户的数据,或者配置变更后支付 API 拒绝所有调用。根因可能不在 API 代码,而在身份映射。

合作伙伴修改群组属性名称、改变 NameID 格式,或停止发送 email claim。代理仍然签发合法令牌,API 也仍然接受签名,但负责租户映射的逻辑读不到预期字段,调用者被放进默认角色。如果 fallback 写得很随意,默认角色甚至可能获得另一个租户的权限。

文档层面的变化

OpenAPI 路径、请求字段和错误码都没有修改,版本看起来完全兼容。

实际发生的破坏性变更

issuer、claim、映射模板、客户端认证方式或认证强度发生变化,调用语义被改写。

这说明:身份配置也是 API 契约的一部分。 任何会影响令牌内容的配置,都应该进入版本控制、变更评审、灰度和回滚流程,而不是被当成控制台里的普通设置。

令牌不是字符串,而是可执行契约

访问令牌把一组业务与安全意图编码成服务可以机械执行的约束。一个可运维的令牌契约至少需要回答这些问题:

iss 谁签发? · aud 给哪个 API? · sub 代表谁?
tenant_id 属于哪个隔离域? · scope 可以做什么?
acr / amr 如何完成认证? · exp 何时失效?

字段存在并不等于约束有效。API 必须联合判断,而不是只验签。例如,“调用者有 invoice:write scope” 不代表它可以编辑任何租户的发票;“令牌受众包含支付 API”也不代表用户刚刚完成了强认证。受众、租户、认证强度和对象级授权必须共同成立。

客户身份管理本质上是隔离问题

一个 OAuth client 经常服务许多企业客户。把客户区分开的往往不是网络,而是令牌中的租户标识。如果身份层不能稳定签发租户,API 又不把租户与受众联合校验,团队实际上只是给共享凭证换了更漂亮的登录界面。

细粒度授权引擎仍有价值,例如回答“这个用户能否编辑这张发票”。但它应该接在身份层之后,消费可信的主体、租户与认证上下文,而不是替代身份层。

像运行基础设施一样运行身份

成熟团队不会只监控“IdP 是否在线”。他们会把身份配置的每个关键决策变成可观测、可测试、可回滚的工程资产。

  1. 把签发策略纳入变更管理。 PKCE 强制、令牌寿命、受众、claim mapper、客户端认证方式和租户 fallback 都需要评审与审计。
  2. 为身份漂移建立检测。 对合作伙伴元数据、证书、claim 结构与客户端配置做差异监控,发现变化时在 API 故障前告警。
  3. 用真实身份路径做回归测试。 测试不应只手工构造 JWT,还要覆盖登录、刷新、轮换、撤销、租户切换和 fallback。
  4. 控制爆炸半径。 缩小受众和 scope,为高风险操作要求更高认证强度,并保证撤销请求能快速传播到边缘。
  5. 保留取证链。 记录 issuer、client、subject、tenant、认证方式与策略版本,同时避免把令牌或敏感 claim 明文写入日志。
下一次 API 返回 403 时,你能否在五分钟内回答:是签名错误、受众错误、映射错误、认证强度不足,还是用户根本没有对象级权限?

如果答案不能从可观测身份上下文中直接得出,团队就仍然在用 API 代码猜测身份问题。把身份层当作控制平面,意味着让这些决策成为明确的策略、可测试的契约和可追踪的运行证据。