Authentification API : OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT est la norme pour les applications clients et les intégrations de serveurs avec autorisation complexe (scopes/roles/tenants), SSO et tokens TTL courts.
Les signatures HMAC sont le meilleur choix pour les webhooks et les appels de partenaires simples « server→server » avec vérification déterministe et protection contre le replay rigide.
Renforcer la sécurité : mTLS ou DPoP (sender-constrained tokens), court TTL (5-15 min), rotation de clé (JWKS), refresh tokens avec rotation/anti-reuse, validation stricte 'aud/iss/bou/nbf/kid' et policy-as-code sur gateway.

1) Carte des solutions : où appliquer

2) OAuth2/OIDC : flux et clients

2. 1 Flux

Code d'autorisation + PKCE (Web/Mobile) : protège le code d'autorisation contre l'interception.
Client Credentials : server↔server sans utilisateur ; scopes - minimum nécessaire.
Code de périphérique : pour les appareils sans navigateur.
Refresh Token : uniquement pour les clients de confiance ; tournez et allumez la détection de la reuse.

2. 2 Types de clients

Confidentiel (serveurs, BFF) : gardent des secrets ; utilisez mTLS.
Public (SPA/mobile) : vous ne pouvez pas stocker de secret → PKCE, DPoP, TTL courts et scopes limités.

3) JWT : structure, échéancier, vérification

3. 1 Champs (claims)

Obligatoire : 'iss', 'sub', 'aud', 'bou', 'iat', 'nbf', 'jti', 'scope '/' permissions', 'tenant' (si multiarend), 'kid'.

3. 2 Durée de vie

Access token : 5-15 minutes.
Refresh token : jours/semaines, on tourne à chaque échange ; Si vous remettez l'ancien, nous bloquons la session.
Clock skew : tolérance ≤ 60 secondes.

3. 3 JWKS et clés

Le stockage des clés dans KMS/Vault, 'kid' est obligatoire.
Deux clés actives (rolling), transférées une fois tous les 60 à 90 jours ou en cas d'incident.
Cache JWKS sur la passerelle ≤ 5 minutes, avec auto-invalide.

3. 4 Vérification sur gateway/services

Vérifiez : signature, 'aud' (services admis),' iss ',' bou/nbf ', liste des verrous (revocation).
Ne faites pas confiance aux champs du corps sans vérifier la signature ; ignorer 'alg = none'.

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

4) Jeton de liaison au client : mTLS, DPoP

mTLS (certificats client TLS) : le jeton n'est émis et validé que s'il existe un certificat client → le jeton ne sert à rien en dehors du lien clé/certificat.
DPoP (Demonstration of Proof-of-Possession) : le client signe chaque demande avec une clé unique → protection contre le replay et le vol de token dans les clients publics.
Pour les itinéraires critiques (mutations de paiement) - exiger l'un des mécanismes.

5) Autorisation : scopes, roles, ABAC

Scopes est l'action minimale ('payments : write', 'payouts : status : read').
Roles - unités pour amiraux ; ne pas les utiliser directement sans scopes.
ABAC - attributs dans le token ('tenant', 'country', 'kyc _ level', 'risk _ flags') de la politique → sur gateway/OPA.
Stratégie au niveau de l'itinéraire/du champ (GraphQL) et au niveau de l'opération de domaine (REST/gRPC).

6) Signatures HMAC : Webhooks et partenaires

6. 1 Concept

Chaque intégration a son propre secret.

Signature sur la chaîne canonique : '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...

Fenêtre temporelle : ≤ 300 secondes ; "X-Timestamp'demandes avec retard/futur refuser.
Idempotence : stocker 'X-Event-Id'sur TTL (24 h) - jeter les doublons.

6. 2 Meilleures pratiques

Secrets dans KMS/Vault, rotation tous les 90 jours.
Pour les clients publics, HMAC n'est pas approprié (secret fuite) ; Utilisez le OAuth2/DPoP.

7) Protection contre le replay, la force brute et les fuites

Nonce/' jti 'pour les opérations sensibles ; liste noire des identifiants utilisés.
Taux/quotas : par clé/client/tenant/route ; les opérations « coûteuses » sont des quotas distincts.
IP/ASN/Geo allow-lists pour les partenaires et les webhooks.
Content-type allow ('application/json'), limite de taille du corps.
Masquer le PII dans les logs ; interdiction de loger les tokens/secrets.

8) Erreurs et réponses (format unique)

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

• '401' est un jeton non-valide (WWW-Authenticate).
• « 403 » - droits insuffisants (scope/ABAC).
• « 429 » - limites/quotas.
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9) Politiques relatives aux dates et aux sessions

Accès ≤ 15 min ; Refresh - rotation + reuse detection (a déposé l'ancienne - révocation de session).
Webhooks HMAC : Signature TTL ≤ 5 min ; refonte avec backoff exponentiel.
Révocation de session/clé → entrée immédiate dans la liste de revocation (cache sur gateway ≤ 1 min).

10) Observation et audit

Corrélation par 'trace _ id '/' span _ id'.
Métriques : taux de réussite auth, '401/403/429', latence OIDC/JWKS, taux de rotation, reuse refresh, part de trafic DPoP/mTLS.
Audit-log : « qui, quand, avec quel 'sub/tenant/scope' a appelé quoi », les changements de clés/secrets, les signatures échouées du HMAC.

11) Intégration dans l'API Gateway

Validation JWT (cache JWKS) et OPA/ABAC sur la passerelle.
Profils mTLS pour les clients/partenaires de confiance.
Vérification HMAC des webhooks sur edge (jusqu'aux services internes).
Taux/Quota polices, circuit-breaker sur le fournisseur OIDC (mettre en cache JWK).
Feature-flags : Désactivation rapide du client/clé, changement de l'algorithme de signature.

12) Mini-extraits

Pseudo : vérification 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 : vérification HMAC du 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)

Exemple de politiques scope (OPA/Rego idée)

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

13) Pleybooks d'incidents

Fuite de clé privée/signataire JWT : transfert de clé, mise à jour JWKS, désactivation immédiate de l'ancien ('kid' → deny), invalidité refresh, connexion forcée.
Substitution de webhooks : rotation de secrets, IP allow-list, renforcement de la fenêtre 'X-Timestamp', remise répétée des événements manqués.
Replay/Brutforce : Activer DPoP/mTLS sur les itinéraires critiques, réduire les quotas, les blocs temporels IP/ASN, activer la liste « jti ».
Outage OIDC : dégradation des jetons cachés (grace), circuit-breaker du fournisseur, notification des clients.

14) Chèques-feuilles de mise en œuvre

• OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)
• TTL : Accès ≤ 15 min, Refresh avec rotation et détection de reuse
• JWKS : deux clés actives, 'kid', cache ≤ 5 min
• Webhooks : HMAC v1, "X-Timestamp", "X-Event-Id', fenêtre de ≤ 300 secondes, idempotence
• Sender-constrained : mTLS/DPoP sur les routes critiques
• ABAC/OPA : scopes + tenant/risk dans les politiques de la passerelle
• Rate/Quota и 429; IP/ASN allow-lists pour les partenaires
• Audit et alertes (401/403/429, reuse refresh, signatures HMAC)

• Ne pas loger les tokens/secrets/corps de cartes complets
• Masquage des IPI ; Appui DSAR ; la durée de conservation des logs est limitée

15) Anti-modèles

'alg = none 'ou une approbation de token sans vérification de signature/JWKS.
Tokens d'accès à longue durée de vie (heures/24 heures).
Un secret HMAC commun pour tous les partenaires.
Webhooks sans timstamps/idempotence.
Les tokens Refresh sont sans rotation et sans détection de reuse.
Absence de validation de 'aud'/' iss' et de rotation de 'kid'.
Stockez des secrets dans des variables d'environnement sans KMS/Vault.

16) NFT/SLO (repères)

OIDC/JWKS disponibilité ≥ 99. 95 % (le cache edge réduit la dépendance).
Supplément de validation JWT sur gateway ≤ 2-5 ms p95.
Erreurs d'authentification ('401') ≤ 0. 5 % du trafic total (hors bots).
Webhooks signés : proportion de ≥ vérifiés avec succès 99. 9 %, délai de livraison moyen ≤ 3 s.

Résumé

Combinez les mécanismes : OAuth2/OIDC + JWT pour les utilisateurs et les scripts serveur riches, HMAC pour les webhooks/partenaires simples, et mTLS/DPoP pour les opérations critiques. Gardez des TTL courts, des rotations de clés (JWKS), des politiques ABAC/OPA strictes, protégez les circuits contre les replay et les fuites, et automatisez tout au niveau de l'API Gateway. Ainsi, l'authentification deviendra prévisible, évolutive et sûre - sans compromis pour l'UX et la monétisation.