API kimlik doğrulaması: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT, karmaşık yetkilendirme (kapsamlar/roller/kiracılar), SSO ve kısa TTL belirteçleri ile istemci uygulamaları ve sunucu entegrasyonları için bir standarttır.
HMAC imzaları, web kitapları ve basit iş ortağı çağrıları için en iyi seçimdir "sunucu - sunucu" deterministik doğrulama ve tekrarlamaya karşı güçlü koruma ile.
Güvenliği güçlendirin: mTLS veya DPoP (gönderici kısıtlamalı belirteçler), kısa TTL (5-15 dakika), anahtar döndürme (JWKS), rotasyon/yeniden kullanım karşıtı, katı doğrulama 'aud/iss/exp/nbf/kid'ile belirteçleri yenile ve ağ geçidinde kod olarak ilke.

1) Çözüm haritası: nereye ne uygulanacak

2) OAuth2/OIDC: akışlar ve müşteriler

2. 1 Akışlar

Yetkilendirme Kodu + PKCE (Web/Mobil) - Yetkilendirme kodunu müdahaleye karşı korur.
Müşteri Kimlik Bilgileri: Kullanıcı olmadan server↔server; kapsamlar - minimum gereklidir.
Cihaz Kodu: Tarayıcısı olmayan cihazlar için.
Refresh Token: yalnızca güvenilir müşteriler için; Döndürün ve yeniden kullanım algılamasını etkinleştirin.

2. 2 Müşteri tipleri

Gizli (sunucular, BFF): sır tutmak; mTLS kullanın.
Public (SPA/mobile): Sır saklanamaz - PKCE, DPoP, kısa TTL ve sınırlı kapsamlar.

3) JWT: yapı, zamanlama, doğrulama

3. 1 Alanlar (iddialar)

Zorunlu: 'Iss', 'sub', 'aud', 'exp', 'iat', 'nbf', 'jti', 'scope'/' permissions', 'tenant' (if multi-lease), 'kid'.

3. 2 Ömür

Erişim belirteci: 5-15 dakika.
Yenileme belirteci: günler/haftalar, her değişimle döndürün; Eski olanı yeniden gönderirken, oturumu engelleriz.

Saat eğriliği: tolerans ≤ 60 s

3. 3 JWKS ve anahtarlar

Anahtarların KMS/Vault'ta saklanması,'çocuk 'gereklidir.
İki aktif tuş (yuvarlanma), her 60-90 günde bir veya bir olayda yeniden yayınlanır.
Ağ geçidinde JWKS önbelleği ≤ 5 dakika, otomatik engelli.

3. 4 Ağ geçidi/hizmetlerinde doğrulama

Onay: imza, 'aud' (onaylanmış hizmetler), 'iss', 'exp/nbf', kilitlerin listesi (iptal).
İmzayı doğrulamadan vücuttan alanlara güvenmeyin; 'alg = none'u yoksay.

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

4) İstemciye bağlama belirteci: mTLS, DPoP

mTLS (TLS istemci sertifikaları): Belirteç yalnızca bir istemci sertifikası varsa verilir ve doğrulanır - belirteç anahtar + sertifika kombinasyonu dışında işe yaramaz.
DPoP (Proof-of-Possession Demonstration): Müşteri her isteği bir kerelik bir anahtarla imzalar - kamu istemcilerinde tekrarlama ve belirteç hırsızlığına karşı koruma.
Kritik yollar için (ödeme mutasyonları) - mekanizmalardan birini gerektirir.

5) Yetkilendirme: kapsamlar, roller, ABAC

Kapsamlar - minimum eylemler ('ödemeler: yazma', 'ödemeler: durum: okuma').
Roller - yöneticiler için birimler; Kapsamlar olmadan doğrudan kullanmayın.
ABAC - belirteçteki öznitelikler ('kiracı', 'ülke', 'kyc _ level', 'risk _ flags') - gateway/OPA'daki politikalar.
Rota/alan düzeyinde (GraphQL) ve etki alanı işlem düzeyinde (REST/gRPC) politika.

6) HMAC imzaları: webhook'lar ve ortaklar

6. 1 Konsept

Her birleşmenin kendi sırrı vardır.

Kanonik çizginin üstündeki resim yazısı: 'zaman damgası + "\n "+ yöntem + "\n "+ yol + "\n "+ sha256 (gövde) '

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

Zaman penceresi: ≤ 300 saniye; Süresi dolmuş/gelecekteki 'X-Timestamp'ile istekleri reddedin.
Idempotence: 'X-Event-Id'yi TTL'de (24 saat) saklayın - kopyaları atın.

6. 2 En iyi uygulamalar

KMS/Vault sırlar, her 90 günde dönen.
Kamu müşterileri için HMAC uygun değildir (gizli sızıntılar); OAuth2/DPoP kullanın.

7) Tekrar, kaba kuvvet ve sızıntılara karşı koruma

Hassas işlemler için nonce/' jti '; Kullanılan tanımlayıcıların kara listesi.
Oran/kotalar: anahtar/müşteri/kiracı/rota ile; "Pahalı" işlemler ayrı kotalardır.
İş ortakları ve webhook'lar için IP/ASN/Geo allow-lists.
Content-type allow ('application/json'), vücut büyüklüğü sınırı.
PII günlüklerde maskeleme; Belirteçleri/sırları kaydetme yasağı.

8) Hatalar ve cevaplar (tek formatta)

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

• '401' - no/invalid token (WWW-Authenticate).
• '403' - yetersiz haklar (kapsam/ABAC).
• '429' - limitler/kotalar.
• gRPC: 'UNAUTHENTICATED'/' PERMISSION _ DENIED'/' RESOURCE _ BITKIN'.

9) Dönem ve oturum politikaları

Erişim ≤ 15 dk; Yenileme - rotasyon + yeniden kullanım algılama (gönderilen eski - oturum hatırlama).
Webhooks HMAC: TTL imzaları ≤ 5 dk; üstel geri tepme ile tekrarlanan teslimat.
Oturum/anahtar iptali - İptal listesine anında giriş (ağ geçidindeki önbellek ≤ 1 dakika).

10) Gözlemlenebilirlik ve denetim

'Trace _ id'/' span _ id'ile korelasyon.
Metrikler: auth başarı oranı, '401/403/429', OIDC/JWKS gecikme süresi, döndürme sıklığı, yeniden kullanım yenilemesi, DPoP/mTLS trafiğinin paylaşımı.
Denetim günlüğü:'kim, ne zaman, hangi 'alt/kiracı/kapsam'ile neye neden oldu ", anahtar/gizli değişiklikler, HMAC imzaları başarısız oldu.

11) Ağ Geçidi API'sine gömme

Ağ geçidinde JWT doğrulama (JWKS önbelleği) ve OPA/ABAC.
Güvenilir müşteriler/iş ortakları için mTLS profilleri.
Kenardaki web kitaplarının HMAC doğrulaması (dahili hizmetlerden önce).
Oran/Kota politikaları, OIDC sağlayıcısında devre kesici (önbellek JWK).
Özellik bayrakları: istemci/anahtarın hızlı bir şekilde kesilmesi, imza algoritmasının değiştirilmesi.

12) Mini snippet'ler

Pseudo: JWT doğrulaması

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]

Sözde: HMAC webhook kontrol

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)

Örnek kapsam-politikası (OPA/Rego fikri)

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

13) Olay oyun kitapları

Özel anahtar sızıntısı/JWT-imzalayıcı: anahtar yeniden yayınlanması, JWKS güncellemesi, eskinin derhal devre dışı bırakılması ('çocuk '- reddetme), sakatlık yenileme, zorla çıkış.
Webhook'ların değiştirilmesi: sırların döndürülmesi, IP izin listesi, 'X-Timestamp' penceresinin amplifikasyonu, kaçırılan olayların tekrarlanan teslimatı.
Replay/brute-force: Kritik rotalarda DPoP/mTLS'yi etkinleştirin, dar kotalar, IP/ASN tarafından geçici bloklar, 'jti' -block listesini etkinleştirin.
Kesinti OIDC: Önbelleğe alınmış belirteçlerin bozulması (grace), devre kesici sağlayıcısı, müşteri bildirimi.

14) Uygulama kontrol listeleri

• OAuth2: Kod + PKCE (Web/Mobil), İstemci Kimlik Bilgileri (sunucudan sunucuya)
• TTL: Erişim ≤ 15 dakika, Rotasyon ve yeniden kullanım algılama ile yenileyin
• JWKS: iki aktif anahtar,'çocuk ', önbellek ≤ 5 dk
• Webhooks: HMAC v1, 'X-Timestamp', 'X-Event-Id', pencere ≤ 300 sn, idempotency
• Gönderici kısıtlı: Kritik rotalarda mTLS/DPoP
• ABAC/OPA: ağ geçidi politikalarında kapsamlar + kiracı/risk
• Oran/Kota и 429; İş ortakları için IP/ASN izin listeleri
• Denetim ve uyarılar (401/403/429, yeniden kullanım yenileme, HMAC imzaları)

• Belirteçleri/sırları/tam kart gövdelerini kaydetmeyin
• PII maskeleme; DSAR desteği; kütüklerin raf ömrü sınırlıdır

15) Anti-desenler

'alg = none' veya imza doğrulaması/JWKS olmadan bir jetona güvenme.
Uzun ömürlü erişim belirteçleri (saat/gün).
Tüm ortaklar için ortak bir HMAC sırrı.
Zaman damgası/idempotency olmadan Webhooks.
Jetonları rotasyonsuz ve yeniden kullanım algılaması olmadan yenileyin.
'Aud'/' iss' doğrulama ve'çocuk 'rotasyon eksikliği.
KMS/Vault olmadan ortam değişkenlerinde sırların saklanması.

16) NFT/SLO (yer işaretleri)

OIDC/JWKS kullanılabilirliği ≥ 99. %95 (kenar önbelleği bağımlılığı azaltır).
Ağ geçidinde JWT doğrulama katkı maddesi ≤ 2-5 ms p95.
Kimlik doğrulama hataları ('401') ≤ 0. Toplam trafiğin %5'i (botlar hariç).
İmzalı webhook'lar: Başarıyla doğrulanmış ≥ 99'un paylaşımı. %9, ortalama teslimat gecikmesi ≤ 3 s.

Özet

Mekanizmaları birleştirin: Kullanıcılar ve zengin sunucu komut dosyaları için OAuth2/OIDC + JWT, webhooks/basit ortaklar için HMAC ve kritik işlemler için - mTLS/DPoP. Kısa TTL'leri, anahtar dönüşlerini (JWKS), sıkı ABAC/OPA politikalarını koruyun, döngüleri tekrar ve sızıntılardan koruyun ve API Gateway düzeyinde her şeyi otomatikleştirin. Böylece kimlik doğrulama, UX ve para kazanma için ödün vermeden öngörülebilir, ölçeklenebilir ve güvenli hale gelecektir.