API Autentification: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT - müştəri tətbiqləri və mürəkkəb avtorizasiya (scopes/roles/tenants), SSO və qısa TTL tokenləri ilə server inteqrasiyaları üçün standart.
HMAC imzaları determinize edilmiş yoxlama və replay-dən sərt qorunma ilə vebhuk və sadə partnyor zəngləri üçün ən yaxşı seçimdir.
Təhlükəsizliyi artırın: mTLS və ya DPoP (sender-constrained tokens), qısa TTL (5-15 dəq), açar rotasiyası (JWKS), rotasiya/anti-reuse refresh tokenləri, ciddi validasiya 'aud/iss/exp/nbf/kid' və gateway-də policy-as-code.

1) Həll xəritəsi: harada tətbiq etmək

2) OAuth2/OIDC: axınlar və müştərilər

2. 1 axınlar

Authorization Code + PKCE (Web/Mobile): avtorizasiya kodunu ələ keçirmədən qoruyur.
Client Credentials: istifadəçi olmadan server server; scopes - minimal zəruri.
Device Code: brauzersiz cihazlar üçün.
Refresh Token: yalnız etibarlı müştərilər üçün; rotasiya və reuse detection.

2. 2 Müştəri növləri

Confidential (serverlər, BFF): sirləri saxlamaq; mTLS istifadə edin.
Public (SPA/mobile): gizli saxlamaq olmaz → PKCE, DPoP, qısa TTL və məhdud scopes.

3) JWT: struktur, vaxt, yoxlama

3. 1 Sahələr (claims)

Məcburi: 'iss', 'sub', 'aud', 'exp', 'iat', 'nbf', 'jti', 'scope '/' permissions', 'tenant' (əgər multiarenta varsa), 'kid'.

3. 2 Həyat müddəti

Access token: 5-15 dəqiqə.
Refresh token: günlər/həftələr, hər mübadilə zamanı rotasiya; köhnə təqdim edildikdə - sessiyanı bloklayırıq.
Clock skew: tolerantlıq ≤ 60 san.

3. 3 JWKS və açarları

Açarların KMS/Vault-da saxlanması tələb olunur.
İki aktiv açar (rolling), 60-90 gündə bir dəfə və ya hadisə baş verdikdə.
Gateway-də JWKS cache ≤ 5 dəqiqə, avto əlilliyi ilə.

3. 4 gateway/xidmətlərdə yoxlama

Müqayisə edin: imza, 'aud' (icazə verilən xidmətlər), 'iss', 'exp/nbf', bloklama siyahısı (revocation).
İmza yoxlamadan bədən sahələrinə etibar etməyin; 'alg = none'.

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

4) Tokenin müştəriyə bağlanması: mTLS, DPoP

mTLS (TLS müştəri sertifikatları): token yalnız müştəri sertifikatı olduqda verilir və təsdiqlənir → token «açar + sertifikat» bağı xaricində faydasızdır.
DPoP (Proof-of-Possession Demonstration): müştəri hər sorğunu birdəfəlik açarla imzalayır → ictimai müştərilərdə replay və token oğurluğuna qarşı qorunma.
Kritik marşrutlar üçün (ödəniş mutasiyaları) - mexanizmlərdən birini tələb etmək.

5) Avtorizasiya: scopes, roles, ABAC

Scopes - minimum hərəkətlər ('payments: write', 'payouts: status: read').
Roles - adminks üçün aqreqatlar; scopes olmadan birbaşa istifadə etməyin.
ABAC - token atributları ('tenant', 'country', 'kyc _ level', 'risk _ flags') → gateway/OPA siyasətləri.
Marşrut/sahə səviyyəsində (GraphQL) və domen əməliyyatı səviyyəsində (REST/gRPC) siyasət.

6) HMAC imzaları: vebhuk və tərəfdaşlar

6. 1 Konsepsiya

Hər bir inteqrasiyanın öz sirri var.

Kanonik sətrin üstündəki imza: 'timestamp + «\n »+ method + «\n» + path + «\n »+ sha256 (body)'

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

Vaxt pəncərəsi: ≤ 300 san; vaxtı keçmiş/gələcək 'X-Timestamp' sorğuları rədd.
İdempotentlik: TTL-də 'X-Event-Id' saxlayın (24 saat) - dublikatları atın.

6. 2 Ən yaxşı təcrübələr

KMS/Vault sirləri, hər 90 gün rotasiya.
HMAC ictimai müştərilər üçün uyğun deyil (sirr sızır); OAuth2/DPoP istifadə edin.

7) replay, brute force və sızma qarşı müdafiə

həssas əməliyyatlar üçün Nonce/' jti '; istifadə olunan identifikatorların qara siyahısı.
Rate/quotas: açar/müştəri/tenant/marşrut; «bahalı» əməliyyatlar - ayrı-ayrı kvotalar.
IP/ASN/Geo allow-lists partnyorlar və vebhuk üçün.
Content-type allow ('application/json'), bədən ölçüsü limiti.
Yuvalarda PII maskalanması; tokenlərin/sirlərin loqotipinin qadağan edilməsi.

8) Səhvlər və cavablar (vahid format)

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

• '401' - No/Nevalid Token (WWW-Authenticate).
• '403' - yetərli hüquqlar (scope/ABAC).
• '429' - limitlər/kvotalar.
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9) Müddət və sessiya siyasəti

Access ≤ 15 dəq; Refresh - rotasiya + reuse detection (köhnə təqdim - seans rəy).
HMAC vebhukları: TTL imzaları ≤ 5 dəq; eksponent backoff ilə təkrar çatdırılma.
Sessiyanın/açarın geri çağırılması → revocation list-ə dərhal daxil olmaq (gateway ≤ 1 dəq).

10) Müşahidə və audit

'trace _ id '/' span _ id' ilə korrelyasiya.
Metriklər: auth success rate, '401/403/429', OIDC/JWKS gecikmə, rotasiya tezliyi, reuse refresh, DPoP/mTLS trafik payı.
Audit-log: «kim, nə vaxt, hansı 'sub/tenant/scope' nə səbəb oldu», açar/sirr dəyişiklikləri, uğursuz imzalar HMAC.

11) API Gateway daxil

JWT-validasiya (JWKS cache) və OPA/ABAC şlüzdə.
Etibarlı müştərilər/tərəfdaşlar üçün mTLS profilləri.
HMAC-vebhukların edge-də yoxlanılması (daxili xidmətlərə qədər).
Rate/Quota siyasətləri, OIDC-provayder circuit-breaker (JWK cache).
Feature-flags: müştəri/açarın tez bağlanması, imza alqoritminin dəyişdirilməsi.

12) Mini snippet

Psevdo: JWT verifikasiyası

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]

Psevdo: HMAC vebhuk testi

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 siyasəti nümunəsi (OPA/Rego ideya)

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

13) Hadisə pleybukları

Şəxsi açar sızması/JWT abunəçisi: açarların yenidən buraxılması, JWKS yenilənməsi, köhnənin dərhal bağlanması ('kid' → deny), refresh əlilliyi, məcburi logout.
Vebhukların dəyişdirilməsi: sirlərin dəyişdirilməsi, IP allow-list, 'X-Timestamp' pəncərəsinin gücləndirilməsi, qaçırılan hadisələrin yenidən çatdırılması.
Replay/brutfors: kritik marşrutlarda DPoP/mTLS aktiv, kvota daralması, IP/ASN müvəqqəti bloklar, 'jti' -blocklist aktiv.
Outage OIDC: cached token deqradasiya (grace), circuit-breaker provayder, müştəri bildiriş.

14) Giriş yoxlama vərəqləri

• OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)
• TTL: Access ≤ 15 dəq, rotasiya və reuse detection ilə Refresh
• JWKS: iki aktiv açar, 'kid', cache ≤ 5 dəq
• Vebhuki: HMAC v1, 'X-Timestamp', 'X-Event-Id', pəncərə ≤ 300 san, idempotent
• Sender-constrained: kritik marşrutlarda mTLS/DPoP
• ABAC/OPA: şlüz siyasətlərində scopes + tenant/risk
• Rate/Quota и 429; Partnyorlar üçün IP/ASN allow-lists
• Audit və alert (401/403/429, reuse refresh, imzalar HMAC)

• No log token/sirləri/tam bədən kartları
• PII maskalanması; DSAR dəstəyi; qeydlərin saxlama müddəti məhduddur

15) Anti-nümunələr

'alg = none' və ya imzanı yoxlamadan/JWKS.
Uzun ömürlü access-tokenlər (saat/gün).
Bütün tərəfdaşlar üçün bir ümumi HMAC sirri.
Zaman damğası/idempotentlik olmadan vebhuki.
Refresh-tokenlər rotasiya olmadan və reuse detection olmadan.
'aud '/' iss' -validasiya və 'kid' -rotasiya yoxdur.
KMS/Vault olmadan mühit dəyişənlərində sirləri saxlayın.

16) NFT/SLO

OIDC/JWKS mövcudluğu ≥ 99. 95% (edge cache asılılığı azaldır).
JWT validasiya qatqısı gateway ≤ 2-5ms p95.
Autentifikasiya səhvləri ('401') ≤ 0. Ümumi trafikin 5% -i (botlar istisna olmaqla).

Imzalanmış vebhuklar: 99 müvəffəqiyyətlə təsdiqlənmiş ≥ payı. 9%, orta çatdırılma gecikməsi ≤ 3 s

Xülasə

Mexanizmi birləşdirin: istifadəçilər və zəngin server ssenariləri üçün OAuth2/OIDC + JWT, vebhuk/sadə tərəfdaşlar üçün HMAC, kritik əməliyyatlar üçün isə mTLS/DPoP. Qısa TTL, açar rotasiyaları (JWKS), ciddi ABAC/OPA siyasətləri saxlayın, dövrələri replay və sızmalardan qoruyun və hər şeyi API Gateway səviyyəsində avtomatlaşdırın. Beləliklə, identifikasiya proqnozlaşdırıla bilən, ölçülə bilən və təhlükəsiz olacaq - UX və monetizasiya üçün kompromis olmadan.