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將能夠抵禦泄漏、重復和濫用,同時保持高性能和可管理性。