Autentificare API: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT este un standard pentru aplicațiile client și integrarea serverelor cu autorizație complexă (scopuri/roluri/chiriași), SSO și jetoane TTL scurte.
Semnăturile HMAC sunt cea mai bună alegere pentru cărțile web și apelurile simple ale partenerilor „server→server” cu verificare deterministă și protecție puternică împotriva reluării.
Consolidarea securității: mTLS sau DPoP (jetoane constrânse de expeditor), TTL scurt (5-15 min), rotație cheie (JWKS), token-uri actualizate cu rotație/anti-reutilizare, validare strictă 'aud/iss/exp/nbf/kid' și policy-as Codul de pe poarta de acces.

1) Harta soluției: ce să se aplice în cazul în care

2) OAuth2/OIDC: fluxuri și clienți

2. 1 Fluxuri

Codul de autorizare + PKCE (Web/Mobile) - Protejează codul de autorizare de interceptare.
Acreditări client: server↔server fără utilizator; scopuri - minim necesar.
Cod dispozitiv: pentru dispozitive fără browser.
Refresh Token: numai pentru clienții de încredere; rotiți și activați detectarea reutilizării.

2. 2 Tipuri de clienți

Confidential (servere, BFF): păstrați secrete; utilizați mTLS.
Public (SPA/mobil): secretul nu poate fi stocat → PKCE, DPoP, TTL scurt și scopuri limitate.

3) JWT: structură, sincronizare, verificare

3. 1 Câmpuri (creanțe)

Obligatoriu: „iss”, „sub”, „aud”, „exp”, „iat”, „nbf”, „jti”, „scope ”/„ permisiuni”, „chiriaș” (dacă există mai multe contracte de închiriere), „kid”.

3. 2 Durata de viaţă

Acces token: 5-15 minute.
Refresh token: zile/săptămâni, rotiți cu fiecare schimb; când îl reintroducem pe cel vechi, blocăm sesiunea.

Înclinare ceas: toleranță ≤ 60 s

3. 3 JWKS și chei

Stocarea cheilor în KMS/Vault, „copil” este necesară.
Două chei active (rulare), reeditate o dată la 60-90 de zile sau într-un incident.
JWKS cache pe gateway ≤ 5 minute, cu auto-handicap.

3. 4 Verificarea gateway-ului/serviciilor

Verificați: semnătură, "aud" (servicii aprobate), "iss'," exp/nbf ", listă de încuietori (revocare).
Nu aveți încredere în câmpurile din corp fără a verifica semnătura; ignore 'alg = none'.

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

4) Token obligatoriu pentru client: mTLS, DPoP

mTLS (certificate de client TLS): tokenul este emis și validat numai dacă există un certificat de client → tokenul este inutil în afara combinației de chei + certificat.
DPoP (Demonstration of Proof-of-Possession): clientul semnează fiecare cerere cu o singură cheie → protecție împotriva reluării și furtului de token în clienții publici.
Pentru rutele critice (mutații de plată) - necesită unul dintre mecanisme.

5) Autorizare: scopuri, roluri, ABAC

Scopuri - acțiuni minime ('plăți: scriere', 'plăți: stare: citire').
Roluri - unități pentru administratori; nu le utilizați direct fără scopuri.
ABAC - atribute din token ('chiriaș', 'țară', 'kyc _ level', 'risc _ steaguri') → politici privind gateway/OPA.
Politica la nivel de traseu/câmp (GraphQL) și la nivel de operare domeniu (REST/gRPC).

6) Semnături HMAC: broșuri web și parteneri

6. 1 Concept

Fiecare integrare are propriul secret.

Legendă deasupra liniei canonice: "timestamp + "\n' + metodă + "\n' + cale + "\n' + sha256 (corp)"

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

Fereastra de timp: ≤ 300 secunde; Respinge cererile cu expirat/viitor „X-Timestamp”.
Idempotence: Păstraţi "X-Event-Id' pe TTL (24h) - eliminaţi duplicatele.

6. 2 Cele mai bune practici

Secretele în KMS/Vault, rotativ la fiecare 90 de zile.
Pentru clienții publici, HMAC nu este potrivit (scurgerile secrete); utilizaţi OAuth2/DPoP.

7) Protecție împotriva reluării, forței brute și scurgerilor

Nonce/„ jti ”pentru operațiuni sensibile; lista neagră a identificatorilor utilizați.
Tarif/cote: dupa cheie/client/chirias/ruta; operațiunile „scumpe” sunt cote separate.
IP/ASN/Geo permite-liste pentru parteneri și webhook-uri.
Tipul de conținut permite („aplicare/json”), limita dimensiunii corpului.
PII mascarea în jurnale; interdicția de a înregistra jetoane/secrete.

8) Erori și răspunsuri (format unic)

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

• '401' - no/nevalid token (WWW-Authenticate).
• „403” - drepturi insuficiente (domeniul de aplicare/ABAC).
• „429” - limite/cote.
• gRPC: „NEAUTENTICAT ”/„ PERMISIUNE _ REFUZAT ”/„ RESURSĂ _ EPUIZAT”.

9) Politica pe termen și sesiune

Acces ≤ 15 min; Reîmprospătare - rotație + detecție reutilizare (trimis vechi - rechemare sesiune).
Webhooks HMAC: semnături TTL ≤ 5 min; livrare repetată cu backoff exponențial.
Revocarea sesiunii/cheii → intrarea imediată în lista de revocare (memoria cache de pe poarta de acces ≤ 1 min).

10) Observabilitate și audit

Corelarea prin 'trace _ id'/' span _ id'.
Valori: rata de succes auth, '401/403/429', latența OIDC/JWKS, frecvența de rotație, refresh reutilizare, cota de trafic DPoP/mTLS.
Jurnal de audit: „cine, când, cu care” sub/chiriaș/domeniu de aplicare „a cauzat ceea ce”, modificări cheie/secrete, semnături HMAC eșuate.

11) Încorporarea în API-ul Gateway

Validarea JWT (memoria cache JWKS) și OPA/ABAC pe poarta de acces.
Profiluri mTLS pentru clienti/parteneri de incredere.
Verificarea HMAC a cârligelor web pe margine (înainte de serviciile interne).
Politica de rată/cotă, întrerupător de circuit pe furnizorul OIDC (cache JWK).
Feature-flags: deconectarea rapidă a clientului/cheii, schimbarea algoritmului de semnătură.

12) Mini fragmente

Pseudo: Verificarea 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]

Pseudo: verificarea 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)

Exemplu de politică de aplicare (ideea OPA/Rego)

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

13) Registrele de redare incidente

Private key leak/JWT-signer: cheie de reemitere, actualizare JWKS, dezactivarea imediată a vechiului („copil” → nega), reîmprospătarea dizabilității, deconectare forțată.
Înlocuirea cârligelor web: rotirea secretelor, lista de permisiuni IP, amplificarea ferestrei „X-Timestamp”, livrarea repetată a evenimentelor pierdute.
Replay/brute-force: activați DPoP/mTLS pe rutele critice, cote înguste, blocuri temporare de IP/ASN, activați lista „jti” -block.
Întreruperea OIDC: degradarea tokenurilor în cache (grație), furnizorul de circuit-breaker, notificarea clientului.

14) Liste de verificare a implementării

• OAuth2: Cod + PKCE (Web/Mobile), Acreditări client (server-to-server)
• TTL: Acces ≤ 15 min, Reîmprospătare cu rotație și detecție reutilizare
• JWKS: două chei active, 'kid', memorie cache ≤ 5 min
• Webhooks: HMAC v1, 'X-Timestamp', 'X-Event-Id', fereastră ≤ 300 sec, idempotency
• Expeditor-constrâns: mTLS/DPoP pe rutele critice
• ABAC/OPA: scopuri + chiriaș/risc în politicile gateway
• Rata/Cota и 429; Liste permise IP/ASN pentru parteneri
• Audit și alerte (401/403/429, refresh reutilizare, semnături HMAC)

• Nu logați jetoane/secrete/corpuri full card
• PII mascare; Suport DSAR; perioada de valabilitate a jurnalelor este limitată

15) Anti-modele

'alg = none' sau încredere într-un token fără verificarea semnăturii/JWKS.
Jetoane de acces cu durată lungă de viață (ore/zi).
Un secret comun HMAC pentru toți partenerii.
Cârlige web fără marcaj temporal/idempotență.
Reîmprospătați jetoanele fără rotație și fără detectarea reutilizării.
Lipsa validării "aud "/" iss' şi a rotaţiei" kid ".
Stocarea secretelor în variabilele de mediu fără KMS/Vault.

16) NFT/SLO (repere)

Disponibilitate OIDC/JWKS ≥ 99. 95% (memoria cache reduce dependența).
Aditiv de validare JWT pe gateway ≤ 2-5 ms p95.
Erori de autentificare ('401') ≤ 0. 5% din traficul total (cu excepția roboților).
Cărți web semnate: cota de ≥ verificate cu succes 99. 9%, întârziere medie de livrare ≤ 3 s.

Rezumat

Combinați mecanisme: OAuth2/OIDC + JWT pentru utilizatori și scripturi de server bogate, HMAC pentru webhook-uri/parteneri simpli și pentru operațiuni critice - mTLS/DPoP. Păstrați scurte TTL-uri, rotații cheie (JWKS), politici stricte ABAC/OPA, protejați buclele de reluare și scurgeri și automatizați totul la nivelul API Gateway. Deci autentificarea va deveni previzibilă, scalabilă și sigură - fără compromisuri pentru UX și monetizare.