Autenticazione API OAuth2, JWT, HMAC

TL; DR

OAUTh2/OIDC + JWT è uno standard per applicazioni client e integrazioni server complesse (scopes/roles/tenants), SSO e TTL brevi di token.
Le firme HMAC sono la scelta migliore per i siti Web e per le semplici chiamate di partner «server→server», con controlli determinati e protezione da replay rigida.
Aumentare la sicurezza: mTLS o DPoP (sender-constrained tokens), TTL brevi (5-15 min), rotazione chiavi (JWKS), token refresh/anti-reuse, validazione rigorosa dì aud/iss/exp/nbf/kid "e policy-as-code su gateway.

1) Mappa delle soluzioni: dove applicare

2) OAuth2/OIDC: flussi e client

2. 1 Flussi

Autenticazione Code + PKCE (Web/Mobile) - Protegge il codice di autorizzazione dall'intercettazione.
Client Credentials: server↔server senza utente scopes è il minimo necessario.
Device Code per dispositivi senza browser.
Refresh Token: solo per i clienti fidati; rotazione e attivazione della reuse detection.

2. 2 Tipi di client

Confidential (server, BFF) - Memorizza i segreti; Usa il mTLS.
Public (SPA/mobile) - Il segreto non può essere memorizzato con PKCE, , TTL brevi e scopes limitati.

3) JWT: struttura, tempistica, verifica

3. 1 Campi (clims)

Obbligatori: «iss», «sub», «aud», «exp», «iat», «nbf», «jti», «scope »/« persimazioni», «tenant», «kid».

3. 2 Tempi di vita

Access token: 5-15 minuti.
Refresh token: giorni/settimane, rotabile a ogni scambio; Se il vecchio viene riprodotto, blocchiamo la sessione.
Clock skew: tolleranza ≤ 60 secondi.

3. 3 JWKS e chiavi

KMS/Vault, kid è obbligatorio.
Due chiavi attive (rolling), reimpostazione ogni 60-90 giorni o in caso di incidente.
Cash JWKS su gateway per 5 minuti, con disabilità automatica.

3. 4 Verifica su gateway/servizi

Controlla la firma, «aud» (servizi ammessi), «iss», «exp/nbf», l'elenco dei blocchi (revocation).
Non fidarsi dei campi del corpo senza la convalida della firma; Ignora alg = none.

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

4) Allega il token al client: mTLS, DPoP

(certificati client TLS) - Il token viene rilasciato e convalidato solo in presenza di un certificato client. Il token non è utile al di fuori del collegamento chiave + certificato.
(Demonstration of Proof-Position) - Il client firma ogni richiesta con una chiave monouso per la protezione da replay e il furto di token nei clienti pubblici.
Per le rotte critiche (mutazioni di pagamento) - richiedere uno dei meccanismi.

5) Autorizzazioni: scopes, roles, ABAC

Scopes - Azioni minime ('payments: write', 'payouts: status: read').
Unità Roles per Ammiraglio; non usarli direttamente senza scopes.
ABAC - Attributi nel token («tenant», «country», «kyc _ level», «risk _ flags») del criterio di gateway/OPA.
Criteri a livello di percorso/campo (GraphQL) e a livello di dominio (REST/gRPC).

6) Firme HMAC: webhoop e partner

6. 1 Concept

Ogni integrazione ha un segreto.

Firma sopra la linea canonica: «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...

Finestra di tempo: 300 secondi; Chiedi scadute/future «X-Timestamp» di rifiutare.
Idempotenza: memorizzare X-Event-ID su TTL (24 ore) - Scartare i duplicati.

6. 2 Migliori pratiche

Segreti in KMS/Vault, rotazione ogni 90 giorni.
Per i clienti pubblici, HMAC non è adatto (il segreto scompare); Usa il OAuth2/DPoP.

7) Protezione contro replay, brute force e fuoriuscite

Nonce/« jti »per operazioni sensibili; la lista nera degli identificatori usati.
Rate/quote: su chiave/client/tenante/percorso; Le operazioni costose sono quote separate.
IP/ASN/Geo allow-lists per partner e siti web.
Content-type allow ('application/json'), limite di dimensione del corpo.
Occultamento del PII nei cassetti il divieto di logorare token/segreti.

8) Errori e risposte (formato unico)

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

• «401» - No/nefalide token (WWW-Authenticate).
• '403' - diritti insufficienti (scope/ABAC).
• «429» - limiti/quote.
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9) Regole di scadenza e sessioni

Access ≤ 15 min; Refresh - rotazione + reuse detection (presentato vecchio - recensione sessione).
HMAC: firma TTL 5 min; nuova consegna con backoff esponenziale.
Il ritiro della sessione/chiave consente di accedere immediatamente alla revocation list (cache per gateway da 1 min).

10) Osservazione e verifica

Correlazione per «trace _ id »/« span _ id».
Metriche: auth success rate, '401/403/429', latitanza OIDC/JWKS, frequenza di rotazione, reuse refresh, quota di traffico DPoP/mTLS.
«Chi, quando, con quale» sub/tenant/scope «ha causato cosa», modifiche a chiavi/segreti, firme HMAC fallite.

11) Incorporazione in API Gateway

Convalida JWT (JWKS kesh) e OPA/ABAC nel gateway.
profili mTLS per clienti/partner fidati.
Verifica HMAC dei webhoop su edge (prima dei servizi interni).
Rate/Quote polizze, circuito-breaker sul provider OIDC (cache JWK).
Feature-flags: disattivazione rapida del client/chiave, modifica dell'algoritmo di firma.

12) Mini snippet

Pseudonimo: verifica 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-test 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)

Esempio di regole scope (OPA/Rego idea)

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

13) Playbook incidenti

Scollegamento della chiave privata/JWT: reimpostazione delle chiavi, aggiornamento JWKS, disattivazione immediata del vecchio ('kid', deny), disabilità refresh, logout forzato.
Turing dei segreti, IP allow-list, rafforzamento della finestra X-Timestamp, reimpostazione degli eventi mancanti.
Replay/Brutal Force: abilita il DPoP/mTLS su percorsi critici, restringe le quote, blocchi temporali su IP/ASN, abilita «jti» è un blocco.
Outage OIDC - Degrado dei token nella cache (grace), circuito-breaker del provider, notifica ai clienti.

14) Assegni di implementazione

• OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)
• TTL: Access ≤ 15 min, Refresh con rotazione e reuse detection
• JWKS: due chiavi attive, 'kid', cache 5 min
• Webhook: HMAC v1, 'X-Timestamp', 'X-Event-ID', finestra ≤ 300 secondi, idimpotenza
• Sender-constrained: mTLS/DPoP su percorsi critici
• ABAC/OPA: scopes + tenant/risk nelle policy gateway
• Rate/Quota и 429; IP/ASN allow-lists per i partner
• Controllo e alert di (401/403/429, reuse refresh, firme HMAC)

• Non logica token/segreti/mappe completi
• Maschera PII; Supporto DSAR Tempo di conservazione limitato

15) Anti-pattern

«alg = none» o la fiducia in un token senza la conferma della firma/JWKS.
Token access a lunga vita (ore/ore).
Un segreto HMAC condiviso su tutti i partner.
Webhookie senza timestamp/idempotenza.
Token refresh senza rotazione e senza reuse detection.
Nessuna «aud »/« iss» - convalida e «kid» - rotazione.
Memorizza i segreti nelle variabili di ambiente senza KMS/Vault.

16) NFL/SLO (punti di riferimento)

OIDC/JWKS disponibilità ≥ 99. 95% (la cache edge riduce la dipendenza).
JWT validazione integratore su gateway 2-5 ms p95.
Errori di autenticazione ('401') ≤ 0. 5% del traffico totale (esclusi i bot).
I webhoop firmati sono una percentuale di 99. 9%, ritardo medio di consegna 3 c.

Riepilogo

Combinare i meccanismi: OAuth2/OIDC + JWT per gli utenti e i ricchi script server, HMAC per i web hook/semplici partner, e per le operazioni critiche per i server. Tieni la TTL corta, le rotazioni delle chiavi (JWKS), le rigide regole ABAC/OPA, proteggi i tracciati da replay e fuoriuscite e automatizza tutto a livello di API Gateway. In questo modo l'autenticazione diventerà prevedibile, scalabile e sicura - senza compromessi per UX e monetizzazione.