API身份验证：OAuth2、JWT、HMAC

TL;DR

OAuth2/OIDC+JWT是具有复杂授权（scopes/roles/tenants），SSO和短TTL令牌的客户端应用程序和服务器集成的标准。
HMAC签名是webhook和简单的"server→server"合作伙伴呼叫的最佳选择，具有确定性验证和严格的重播保护。
增强安全性：mTLS或DPoP （sender-constrained tokens）、短TTL （5-15分钟）、钥匙旋转（JWKS）、带旋转/反重置的refresh令牌、严格验证'aud/iss/exp/nbf/kid'和gateway上的策略代码。

1）解决方桉图： 在哪里应用

2）OAuth2/OIDC： 线程和客户

2.1个线程

授权代码+PKCE （Web/Mobile）：保护授权代码免受拦截。
Client Credentials：没有用户的server↔server；scopes-最低要求。
设备代码：对于没有浏览器的设备。
Refresh Token：仅适用于值得信赖的客户；浏览并启用reuse检测。

2.2个客户端类型

机密（服务器，BFF）：存储秘密；使用mTLS。
Public （SPA/mobile）：无法→ PKCE、DPoP、短TTL和有限的范围存储秘密。

3） JWT： 结构，时限，验证

3.1个字段（claims）

强制性的："iss"，"sub"，"aud"，"exp"，"iat"，"nbf"，"jti"，"scope"/"permissions"，"tenant"（如果是多功能），"kid"。

3.2生命周期

Access token： 5-15分钟。
Refresh令牌：每天/周，每次交换时轮换；重新提交旧文件时-我们阻止会议。
Clock skew：公差≤ 60秒。

3.3个JWKS和钥匙

将密钥存储在KMS/Vault中，"kid"是必需的。
两个活动密钥（滚动），每60-90天或发生事件时超过一次。
Gateway上的JWKS缓存≤ 5分钟，有自动残疾。

3.4在网关/服务上进行验证

检查：标题，"aud"（允许的服务），"iss"，"exp/nbf"，锁定列表（revocation）。
无需签名验证即可信任身体中的字段；忽略'alg=none'。

Authorization: Bearer <JWT>
X-Trace-Id: <uuid>

4）令牌绑定到客户端： mTLS, DPoP

mTLS （TLS客户端证书）：只有在有客户端证书的情况下才能签发和验证令牌→令牌在key+证书捆绑包之外是无用的。
DPoP（上市证明的演示）：客户端以一次性密钥签署每个请求→以防止公共客户中的重播和代币盗窃。
对于关键路线（支付突变），需要一种机制。

5）授权： scopes, roles, ABAC

Scopes-最小动作（"payments： write","payouts： status： read"）。
Roles是海军上将的单位；不要直接使用它们而不使用scopes。
ABAC是→ 网关/OPA策略的令牌（"tenant"，"country"，"kyc_level"，"risk_flags"）中的属性。
路由/字段级别（GraphQL）和域操作级别（REST/gRPC）策略。

6） HMAC签名： webhooks和合作伙伴

6.1个概念

每个集成都有自己的秘密。

规范字符串上的签名： "timestamp +"\n"+method+"\n"+path+"\n"+sha 256（body）"

X-Signature: v1=base64(hmac_sha256(secret, canonical_string))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF...

时间窗口：≤ 300秒；逾期/未来"X-Timestamp"拒绝的请求。
相似性：在TTL （24小时）上存储"X-Ivent-Id"-丢弃重复内容。

6.2最佳实践

KMS/Vault中的秘密，每90天轮换一次。
对于公共客户，HMAC不合适（秘密泄露）；使用OAuth2/DPoP。

7）复制保护，brute force和泄漏

用于敏感操作的Nonce/"jti"；使用的标识符黑名单。
Rate/quotas：按键/客户/tenant/路线；"昂贵"的操作是单独的配额。
针对合作伙伴和网络手册的IP/ASN/Geo allow-lists。
内容类型联盟（"application/json"），体型限制。
在日志中掩盖PII；禁止伪造令牌/秘密。

8）错误和响应（单一格式）

json
{
"error": "invalid_token",
"error_description": "expired",
"trace_id": "4e3f-..."
}

• "401"是无/非验证令牌（WWW-Authenticate）。
• "403"-没有足够的权限（scope/ABAC）。
• "429"-限制/配额。
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9）会期和会议的政策

Access ≤ 15分钟；Refresh-轮换+reuse检测（提交旧的会议召回）。
HMAC Webhooks：TTL签名≤ 5分钟；用指数后端重新交付。
召回会话/密钥→立即击中revocation list （gateway缓存≤ 1分钟）。

10）可观察性和审计

"trace_id"/"span_id"上的相关性。
度量标准：成功率，"401/403/429"，OIDC/JWKS潜伏率，旋转频率，reuse refresh，流量的DPoP/mTLS份额。
审核日志："谁,什么时候,什么"sub/tenant/scope"导致什么,密钥更改,HMAC签名失败。

11）嵌入到Gateway API中

JWT验证（JWKS kesh）和OPA/ABAC在网关上。
可信赖的客户/合作伙伴的mTLS配置文件。
HMAC对边缘的webhook进行验证（直到内部服务）。
Rate/Quota保单，OIDC提供商的电路断路器（缓存JWK）。
功能闪光灯：快速关闭客户端/密钥,更改签名算法。

12）迷你嗅探

伪： JWT验证

pseudo jwks = cache. getOrFetch(iss + "/.well-known/jwks. json")
key = jwks[kid]
assert verify_signature(jwt, key)
assert aud in ALLOWED_AUDIENCES and iss in TRUSTED_ISSUERS assert now in [nbf-60s, exp+60s]

伪： HMAC webhook验证

pseudo canonical = timestamp + "\n" + method + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
assert abs(now - timestamp) <= 300 assert not seen(event_id)
assert timingSafeEqual(sig, header["X-Signature"].split("v1=")[1])
markSeen(event_id, ttl=86400)

scope策略示例（OPA/Rego想法）

rego allow {
input. jwt. scope[_] == "payments:write"
input. jwt. tenant == input. route. tenant
}

13）事件花花公子

私钥泄漏/JWT签名：过度释放密钥、JWKS更新、立即关闭旧密钥（"kid "→ deny）、残障退货、强制登录。
取代webhooks：秘密轮换，IP allow-list，"X-Timestamp"窗口增强，重复传递遗漏的事件。
Replay/野蛮：在关键路由上启用DPoP/mTLS,缩小配额,通过IP/ASN临时块,启用"jti"块列表。
Outage OIDC：缓存令牌（grace）降级,电路断路器提供商,客户通知。

14）实施支票

[] OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)

• TTL：Access ≤ 15分钟，Refresh轮换和重复检测
• JWKS：两个活动密钥，"kid"，缓存≤ 5分钟
• Webhooks：HMAC v1，"X-Timestamp"，"X-Ivent-Id"，窗口≤ 300秒，等距
• Sender-constrained： mTLS/DPoP在关键路线
• ABAC/OPA：网关策略中的scopes+tenant/risk

[] Rate/Quota и 429;IP/ASN allow-lists for partners

• 审核和Alerta (401/403/429，reuse refresh，HMAC签名）

• 不要用令牌/保密/卡全身
• 伪装PII；DSAR支持；log的保留期受到限制

15）反模式

"alg=none" 或没有签名验证/JWKS的令牌信任。
长寿访问令牌（小时/天）。
所有合作伙伴共享一个HMAC密码。
Webhooks没有Taymstamp/IP。
Refresh令牌无需旋转或重复检测。
缺乏"aud"/"iss"验证和"kid"旋转。
在没有KMS/Vault的环境变量中存储秘密。

16）NFT/SLO（地标）

OIDC/JWKS可用性≥ 99。95%（边缘缓存减少依赖性）。
JWT验证网关上的添加剂≤ 2-5 ms p95。
身份验证错误（"401"）≤ 0。占总流量的5％（不包括机器人）。
已签署的网页：已成功核实的≥ 99的百分比。9%，平均交货延迟≤ 3秒。

总结

结合以下机制：用户和丰富的服务器脚本的OAuth2/OIDC+JWT、网络手册/简单合作伙伴的HMAC和关键操作的mTLS/DPoP。保持短的TTL、密钥轮换（JWKS）、严格的ABAC/OPA策略、保护轮廓免受重置和泄漏,并自动执行Gateway API级别的所有操作。因此，身份验证将变得可预测，可扩展和安全-对UX和货币化没有妥协。