API和令牌安全

简短摘要

API安全性是身份验证，授权，密码保护，反滥用和可观察性的机制的集合，可确保请求在预期上下文中将预期对象执行到预期资源。关键工件是令牌（或请求签名），可证明呼叫权。良好的体系结构依赖于短寿命令牌，清晰的漏洞，最低特权，重复保护，限制等级和操作程序（轮换，审计，事件）。

API身份验证模型： 何时以及如何选择

API键（静态密钥）

易于B2B集成和低风险场景。不带上下文,需要存储在服务端。
仅适用于IP/ASN allow-list、固定配额、短TTL和轮换。

OAuth 2.1 / OIDC

用户和合作伙伴集成的标准：access token（短寿命）+refresh token（旋转）+scopes。
公共客户-使用PKCE；机密客户端-具有客户端秘密/mTLS。

Client Credentials (m2m)

Mashina→mashina：通过严格设定的漏洞和听众访问服务,通常没有refresh（重新获取）。

mTLS（相互的TLS）

将身份绑定到通道。适用于高风险或支付集成（TLS之上的PoP）。
可以与OAuth（仅mTLS客户端的令牌）结合使用。

查询签名（HMAC/EdDSA）

当需要独立于传输的PoP时：签名标题、timestamp和nonce。方便使用webhooks和离线检查。

令牌格式和类型

JWT （JWS签名）

自给自足，在当地进行测试；强制性的"iss"，"sub"，"aud"，"exp"，"iat"，"jti"，"scope"。
风险-召回更加困难：在事件中使用短TTL（5-15分钟）+召回的"jti"列表。

JWE（加密JWT）

如果付费是敏感的（PII），则需要。成本-复杂性和开销更高。

Reference tokens

不透明的标识符,通过Authorization Server的introspection进行验证-更容易召回/集中化。

PoP/DPoP

将令牌绑定到客户密钥或TLS会话会降低被盗令牌的价值。

令牌内容： 最低限度

推荐标记（JWT）：

"iss"（issuer），"sub"（主题），"aud"（目标系统/资源），"exp"（学期），"iat"，"nbf"（可选）和"jti"。
"scope"/"permissions"（最低要求），"tenant"（对于多元化），"device_compliant"/"amr"（身份验证方法），"ip"/"asn"（如果适用于策略）。

规则：

用于访问（5-15分钟）的短TTL，refresh-12-48小时（旋转旋转）。
观众（"aud"）是严格特定的资源，否则令牌是"可重复使用的"。
Scopes是动作和对象（例如'payments：withdraw。read`).
大小≤ 2-4 KB用于标题和代理；否则，gateway可能会出现问题。

授权和政策

RBAC+ABAC：角色+上下文（组织，地理，风险，设备状态）。
PEP/PDP：在应用程序之前验证令牌并在API网关/代理（Envoy/OPA）上做出决策。
声明性规则：存储在Git,通过CI的策略测试。

Rego示例（简化）：

rego package policy. withdraw

default allow = false

allow {
input. token. aud == "wallet-api"
input. token. scope[_] == "payments:withdraw. create"
input. device. compliant == true input. risk. score < 70
}

查询签名（HMAC）和反回复

需要时：webhooks，没有OAuth的集成，对关键操作的双重验证。

标题图（示例）：


X-Client-Id: <id>
X-Timestamp: 2025-11-05T13:20:10Z
X-Nonce: 4d1f...a2
X-Signature: base64(HMAC_SHA256(secret, method + "\n" + path + "\n" + sha256(body) + "\n" + timestamp + "\n" + nonce))

规则：

以>± 300秒的时间同步拒绝请求。
Nonce存储5-15分钟，并且不接受重播（重复缓存）。
签署规范化查询视图（方法、路径、查询、主体哈希）。

异步性和事务保护

注销/支付/创建操作的Idempotency-Key：相同的密钥→相同的效果。
钥匙的寿命是业务时间≥时间（通常为24-72小时）。
服务器端逻辑：将查询设置与先前为此键指定的设置进行比较。

浏览器和移动客户端

PKCE是必需的（公共客户）。
浏览器中的Refresh令牌-避免；如果需要-ROTATION+重复响应（replay detection）。
存储：会话存储>本地存储；更好-前端后端（BFF）负责令牌。
SameSite, Secure, HttpOnly для cookie;CORS-显式allow-lists，标题和方法；安全地预飞。

m2 m和高风险集成

mTLS+OAuth2 Client Credentials with scops and 'aud'。
网关上的IP/ASN allow-list。
TLS顶部的PoP/DPoP或HMAC签名用于关键操作。
每个组织/客户/密钥的配额和等级限制。

轮换、滚动和事件响应

机密和签名密钥轮换（JWKS）：按计划+在事件中强制执行。
双键滚动：提前发布新的关键对（kid2）,签名令牌,保持旧（kid1）验证直至TTL耗尽。
Refresh-rotation：每个refresh交换都→新的令牌，旧代币立即无效；重复是损害信号。
Revocation：对于JWT，短暂召回的"jti"列表；引用令牌-立即锁定AS。
破玻璃脚本：具有最小权限和刚性TTL的临时静态信条,记录在日志中。

Rate limiting, bot保护和超频保护

三层限制：per-key/per-IP/per组织。
Burst+sustained：令牌罐/滑动窗口。
复杂的检查：设备指纹,行为提示,geo/ASN异常,CAPTCHA仅适用于UI。
在签名/NMAS打破和不成功的身份验证尝试时锁定/慢动作。

逻辑、度量和SLO

最小的日志集是："request_id"，"client_id"，"sub"，"aud"，"scope"，"decision"，"reason"，"jti"，"ip"，"asn"，"latency"，"quota_state"。

度量标准：

令牌验证成功（%），p95验证时间。
重复偏差的频率，重复到Idempotency-Key。
使用PoP/DPoP/mTLS的查询比例。
"exp"过期的"aud/scope"错误，时间转移（NTP）。

SLO（示例）：

Auth/AS可用性≥ 99。95%/多月；p95 introspection ≤ 50 мс.
TTL小于60 c的零令牌（安全度量）。
小于0。每天有1％的"aud/scope"错误（集成质量）。

配置示例

Envoy： JWT检查和听力

yaml http_filters:
- name: envoy. filters. http. jwt_authn typed_config:
providers:
as:
issuer: https://auth. example. com/
audiences: ["wallet-api"]
remote_jwks:
http_uri:
uri: https://auth. example. com/.well-known/jwks. json cluster: jwks_cluster cache_duration: 600s rules:
- match: { prefix: "/v1/withdraw" }
requires:
provider_and_audiences:
provider_name: as audiences: ["wallet-api"]

NGINX: mTLS к backend

nginx proxy_ssl_server_name on;
proxy_ssl_name wallet. internal;
proxy_ssl_certificate   /etc/nginx/mtls/client. crt;
proxy_ssl_certificate_key /etc/nginx/mtls/client. key;
proxy_ssl_trusted_certificate /etc/nginx/mtls/ca. crt;
proxy_ssl_verify on;
proxy_ssl_verify_depth 2;

签名标题示例（webhooks）


X-Signature: t=1730803210,n=ac12...,s=base64(HMAC_SHA256(secret, "POST\n/webhook\nsha256(body)\n1730803210\nac12..."))

如果"t"大于300 c，"n"已经相遇或"s"没有被击中，则服务器会拒绝。

数据保护和隐私

尽量减少污名（尤其是PII）和寿命。
为第三方集成加密敏感污泥（JWE）。
Mask/DLP在日志中：不要用PAN/PII书写身体,令牌只是"kid"/标志,不是秘密本身。

典型错误

长距离访问令牌和"永恒"refresh。
没有"aud"/"scope" →令牌是多用途的。
没有"timestamp"/"nonce"的webhook签名。
JWT仅在应用程序中验证，而不在网关（PEP）上验证。
没有旋转和双键滚动。
CORS""和允许的不安全方法不受标题控制。
将令牌存储在没有BFF的"本地存储"中。

实施路线图

1.API清单和分类（公共/合作伙伴/内部，敏感性）。
2.AuthN模型选择：用于自定义的mTLS+Client Credentials/HMAC的mTLS/Client Credentials/HMAC OAuth2/OIDC。
3.令牌：用于关键操作的短TTL，严格"aud"，漏斗，DPoP/PoP。
4.Gateway上的PEP：将JWT、签名和评级限制验证为应用程序。
5.反重播和幂等性：timestamp/nonce/Idempotency-Key。
6.轮换和JWKS：双键，自动化和差速器。
7.可观察性：度量/SLO，访问日志，UEBA信号。
8.教学：丢下签名密钥，refresh泄漏，配额超载。

iGaming/fintech的细节

付款/付款：仅mTLS+PoP/HMAC，严格的争吵（'withdraw。create'），idempotency是必需的。
合作伙伴（PSP/内容提供商）：按合作伙伴密钥/证书，IP/ASN allow-list，单独的配额和行车记录。
GDPR/PCI DSS：最小化污名，禁止第三方令牌中的PII，编写对敏感资源的访问，定期访问评论。
反借口：行为限制，地理控制，API级别的奖励借口保护。

FAQ

JWT还是参考令牌？
JWT-性能和自主性；reference-集中召回和简单事件响应。通常，混合体：外部-JWT，内部-参考。

需要JWE吗？
仅当付费包含PII/秘密时。否则-JWS的污名最小。

你能活在API密钥上吗?

是的,但只有短的TTL、严格的配额、IP allow-list和请求签名。对于用户-最好是OAuth/OIDC。

DPoP/PoP是必需的吗?

并非总是如此。但是对于高风险的交易（付款，结论），这是非常理想的。

底线

可靠的API安全性建立在短寿命令牌，精确的漏洞和受保护通道（TLS/mTLS）的受众，请求签名以及严格的防重播保护上，并通过限制和可观察性增强。在游戏中添加自动旋转、双键滚动和政治控制-并且API将能够抵御泄漏、重复和滥用,同时保持高性能和可管理性。