Parcourir les aide-mémoire · API
Modèles d’authentification d’API
Choisissez et mettez en œuvre l’authentification d’API en toute sécurité en comprenant les clés d’API, l’authentification Basic, les jetons Bearer, OAuth 2.0, les JWT, les identités de service, le mTLS, la durée de vie des jetons et les défaillances courantes en production.
Sur cette page
- Problème
- Réponse rapide
- Code / commandes
- 1. Clé d’API dans un en-tête de requête
- 2. Préférer les en-têtes aux clés d’API dans la chaîne de requête
- 3. Authentification Basic
- 4. Ne pas intégrer d’identifiants Basic dans les URL
- 5. Jeton d’accès Bearer
- 6. Ne pas journaliser les jetons Bearer
- 7. OAuth 2.0 client credentials
- 8. Préférer l’identité de charge de travail aux secrets client stockés lorsqu’elle est disponible
- 9. Flux OAuth authorization code
- 10. PKCE protège les flux authorization code pour les clients publics
- 11. Modèle du jeton d’actualisation
- 12. Effectuer la rotation des jetons d’actualisation lorsque le fournisseur le permet
- 13. Exemple de jeton Bearer JWT
- 14. Décoder les métadonnées d’un JWT sans le considérer comme validé
- 15. Valider la signature du JWT
- 16. Valider l’émetteur
- 17. Valider l’audience
- 18. Valider l’expiration du jeton
- 19. Valider nbf
- 20. Valider l’autorisation après l’authentification
- 21. Autorisation basée sur les scopes
- 22. Autorisation basée sur les rôles
- 23. Autorisation au niveau de la ressource
- 24. L’isolation des tenants relève de la logique d’autorisation
- 25. Exemple de jeton de service à service
- 26. Ne pas demander de scopes plus larges que nécessaire
- 27. Préférer des jetons d’accès de courte durée
- 28. Mettre en cache les jetons d’accès de façon responsable
- 29. Actualiser avant l’expiration avec une marge de sécurité
- 30. Éviter les rafales d’actualisation de jetons
- 31. Authentification client mTLS
- 32. Le mTLS peut coexister avec des jetons au niveau applicatif
- 33. Protéger les clés privées
- 34. Signature de requêtes HMAC
- 35. Protection contre le rejeu des requêtes signées
- 36. Authentification au niveau de la passerelle d’API
- 37. Le backend doit savoir à quelle identité se fier
- 38. Ne pas faire confiance aux en-têtes d’identité envoyés par des clients arbitraires
- 39. Utiliser correctement 401 et 403
- 40. Renvoyer WWW-Authenticate lorsque c’est approprié
- 41. Ne pas renvoyer de détails d’authentification sensibles
- 42. Garder les erreurs d’authentification observables côté serveur
- 43. Utiliser des identifiants de corrélation
- 44. Tester volontairement un jeton expiré hors production
- 45. Tester des jetons avec une audience incorrecte
- 46. Tester l’accès à un mauvais tenant
- 47. Ne pas utiliser l’authentification comme substitut à l’autorisation
- 48. Préférer les standards à l’authentification maison
- 49. OpenID Connect sert à l’identité au-dessus d’OAuth 2.0
- 50. Jeton d’accès ou ID token
- 51. Ne pas utiliser un jeton d’actualisation comme jeton d’API
- 52. Introspection de jetons
- 53. La validation des JWT est généralement locale
- 54. Mettre en cache les clés de signature avec prudence
- 55. Rejeter les algorithmes de signature inattendus
- 56. Ne jamais accepter de JWT non signés
- 57. Stocker les secrets hors du contrôle de code source
- 58. Effectuer la rotation des identifiants
- 59. Prévoir une rotation avec chevauchement lorsque c’est possible
- 60. Éviter un identifiant partagé entre de nombreux clients
- 61. Limiter le débit selon une identité stable
- 62. Les données d’authentification ne doivent pas servir d’entrée métier arbitraire
- 63. Traiter les claims du jeton comme des entrées de sécurité
- 64. Éviter d’accepter par accident des jetons de plusieurs émetteurs
- 65. Utiliser HTTPS partout pour les requêtes porteuses d’identifiants
- 66. Faire attention aux redirections et aux en-têtes Authorization
- 67. Ne pas placer de jetons dans le code source frontend
- 68. Modèle backend-for-frontend
- 69. Les sessions d’API basées sur des cookies nécessitent une protection CSRF
- 70. Les cookies nécessitent des attributs de sécurité
- 71. Authentification et CORS sont différents
- 72. Authentification et chiffrement sont différents
- 73. Authentification et signature de requêtes sont différentes
- 74. Les échecs d’authentification doivent refuser par défaut (fail closed)
- 75. Éviter les identifiants de secours maison
- 76. Utiliser les contrôles d’intégrité avec prudence
- 77. Documenter le contrat d’authentification de l’API
- 78. Construire une matrice de diagnostic
- Interpréter le résultat
- Points à vérifier
- 401 Unauthorized
- 403 Forbidden
- Fonctionne jusqu’à l’expiration approximative du jeton
- Fonctionne en local mais échoue dans le service déployé
- Un JWT valide est rejeté
- Un jeton valide accède aux données d’un autre tenant
- Notes de production
- Les secrets d’authentification sont des identifiants de production
- Préférer les identifiants de courte durée
- Les bibliothèques d’authentification sont des dépendances de sécurité
- L’autorisation doit se faire au plus près de la ressource protégée
- Les API multi-tenant nécessitent des contrôles de tenant explicites
- La rotation des identifiants doit être testée avant un incident
- Erreurs fréquentes
- 1. Considérer le décodage d’un JWT comme une validation
- 2. Envoyer un ID token à une API
- 3. Journaliser des jetons bruts
- 4. Partager une même clé d’API entre de nombreux clients
- 5. Placer des secrets dans les chaînes de requête
- 6. Utiliser des jetons Bearer à longue durée de vie parce que l’actualisation est contraignante
- 7. Valider l’authentification mais pas l’accès au tenant/à la ressource
- 8. Accepter n’importe quel JWT signé par un fournisseur connu
- 9. Stocker des secrets client dans le code frontend
- 10. Construire une authentification maison au lieu d’utiliser des standards établis
- Étape suivante
- Pour aller plus loin
Problème
Une API doit savoir qui ou quoi l’appelle avant d’autoriser l’accès.
La difficulté ne consiste pas à ajouter un en-tête Authorization. Les vraies questions d’ingénierie sont les suivantes :
- L’appelant est-il un utilisateur, un service, un script, un appareil ou un partenaire ?
- L’API a-t-elle besoin uniquement d’authentification, ou aussi d’une autorisation déléguée ?
- Quelle doit être la durée de vie des identifiants ?
- Comment les identifiants sont-ils renouvelés (rotation) ou révoqués ?
- Où les secrets sont-ils stockés ?
- L’appelant se trouve-t-il dans une plateforme de confiance, ou franchit-il des frontières entre organisations ?
- L’API a-t-elle besoin d’une identité client forte, comme le mTLS ?
- Les jetons sont-ils validés localement ou par l’intermédiaire d’un serveur d’autorisation ?
L’objectif est de choisir le modèle d’authentification le plus simple qui corresponde au modèle de confiance, sans créer de secrets à longue durée de vie ni de sécurité maison fragile.
Réponse rapide
Utilisez ce modèle de décision :
Intégration simple de serveur à serveur, peu complexe
→ clé d’API, si la plateforme la prend en charge de façon sécurisée
Authentification HTTP héritée/simple
→ Basic auth, uniquement sur TLS
Jeton d’utilisateur ou de service présenté à une API
→ jeton d’accès Bearer
Un utilisateur délègue l’accès à une application
→ flux d’autorisation OAuth 2.0
Service à service sans utilisateur
→ OAuth 2.0 client credentials ou identité de charge de travail gérée par la plateforme
Besoin d’une identité client cryptographiquement forte au niveau de la couche TLS
→ mTLS
JWT
→ format de jeton, pas un protocole d’authentification en soi
Requête typique avec un jeton Bearer :
curl \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.example.com/v1/reports"
N’inventez pas votre propre format de jeton et n’envoyez pas de secrets à longue durée de vie dans les chaînes de requête (query strings).
Code / commandes
1. Clé d’API dans un en-tête de requête
curl \
--header "X-API-Key: $API_KEY" \
"https://api.example.com/v1/data"
À utiliser lorsque l’API prend volontairement en charge l’authentification par clé d’API.
Cas adaptés :
- intégrations de services internes
- intégrations simples avec des partenaires
- accès machine peu complexe
Limites :
- représente généralement l’application, pas un utilisateur final
- souvent à longue durée de vie
- la révocation et la rotation doivent être gérées explicitement
- granularité grossière, sauf si elle est combinée à une stratégie côté serveur
2. Préférer les en-têtes aux clés d’API dans la chaîne de requête
À éviter :
curl \
"https://api.example.com/v1/data?api_key=$API_KEY"
Les secrets placés dans la chaîne de requête peuvent fuiter dans :
- les journaux d’accès
- l’historique du navigateur
- les outils de supervision
- les proxys inverses
- les données de référent (referrer)
Utilisez un en-tête d’authentification chaque fois que l’API le permet.
3. Authentification Basic
curl \
--user "$API_USER:$API_PASSWORD" \
"https://api.example.com/v1/admin"
Cette commande envoie les identifiants au moyen de l’authentification HTTP Basic.
À utiliser uniquement sur HTTPS.
L’authentification Basic ne chiffre pas les identifiants par elle-même ; c’est TLS qui assure la protection du transport.
4. Ne pas intégrer d’identifiants Basic dans les URL
À éviter :
https://user:password@api.example.com
Les identifiants peuvent fuiter par les journaux, l’historique, les outils ou les diagnostics.
Utilisez plutôt le mécanisme d’autorisation HTTP.
5. Jeton d’accès Bearer
curl \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.example.com/v1/reports"
Un jeton Bearer signifie :
quiconque possède le jeton peut l’utiliser
Protégez-le comme un mot de passe.
6. Ne pas journaliser les jetons Bearer
Mauvais :
print(headers)
si headers contient :
Authorization: Bearer ...
Journalisez plutôt des métadonnées sans risque :
jeton présent : oui
émetteur du jeton : émetteur attendu
audience du jeton : API attendue
expiration du jeton : 2026-10-04T22:00:00Z
Ne journalisez pas le jeton lui-même.
7. OAuth 2.0 client credentials
À utiliser pour les appels de machine à machine sans utilisateur.
Modèle de demande de jeton :
curl \
--request POST \
--url "https://auth.example.com/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET" \
--data-urlencode "scope=reports.read"
Réponse typique :
{
"access_token": "...",
"token_type": "Bearer",
"expires_in": 3600
}
Appelez ensuite l’API avec le jeton d’accès renvoyé.
8. Préférer l’identité de charge de travail aux secrets client stockés lorsqu’elle est disponible
Dans les environnements cloud, une identité managée ou de charge de travail (workload identity) peut souvent obtenir des jetons sans stocker de secret client statique.
Conceptuellement :
identité de charge de travail
→ serveur d’autorisation / plateforme d’identité cloud
→ jeton d’accès de courte durée
→ API
Préférez cette approche à la distribution de secrets à longue durée de vie entre les applications.
9. Flux OAuth authorization code
À utiliser lorsqu’une application a besoin d’un accès pour le compte d’un utilisateur.
Conceptuellement :
Utilisateur
→ connexion/consentement auprès du serveur d’autorisation
→ code d’autorisation
→ l’application échange le code
→ jeton d’accès
→ API
Les clients publics modernes doivent utiliser PKCE.
N’exposez pas le secret utilisé pour l’échange du code d’autorisation au code navigateur/mobile lorsque le client ne peut pas protéger un secret.
10. PKCE protège les flux authorization code pour les clients publics
PKCE utilise :
code_verifier
code_challenge
pour lier la demande d’autorisation au client qui échange ensuite le code.
Utilisez le SDK ou la bibliothèque pris en charge par le serveur d’autorisation au lieu d’implémenter PKCE manuellement, sauf nécessité.
11. Modèle du jeton d’actualisation
Cycle de vie typique :
jeton d’accès
→ courte durée de vie
jeton d’actualisation (refresh token)
→ identifiant à plus longue durée de vie servant à obtenir de nouveaux jetons d’accès
Les jetons d’actualisation doivent normalement rester dans l’application ou le backend de confiance qui détient la session.
Ne les exposez pas largement aux services en aval.
12. Effectuer la rotation des jetons d’actualisation lorsque le fournisseur le permet
La rotation des jetons d’actualisation peut réduire le risque de rejeu.
Un jeton soumis à rotation est remplacé par un nouveau lors de l’actualisation.
Si un ancien jeton est réutilisé, le fournisseur peut être en mesure de détecter un rejeu suspect.
Le comportement exact dépend du fournisseur.
13. Exemple de jeton Bearer JWT
Un JWT ressemble souvent à :
xxxxx.yyyyy.zzzzz
avec trois sections encodées en Base64URL :
header.payload.signature
Les claims courants incluent :
iss
sub
aud
exp
nbf
iat
scope
roles
Un JWT est un format de jeton.
Il n’est pas automatiquement digne de confiance du seul fait qu’on peut le décoder.
14. Décoder les métadonnées d’un JWT sans le considérer comme validé
Vous pouvez décoder le payload d’un JWT pour un diagnostic, mais :
décoder
!=
valider
La validation doit vérifier la signature et les claims requis.
N’autorisez pas des requêtes sur la seule base du contenu décodé d’un jeton.
15. Valider la signature du JWT
La validation côté serveur doit s’appuyer sur des clés de confiance fournies par le fournisseur d’identité.
Vérifications de validation typiques :
signature
émetteur
audience
expiration
not-before (pas avant)
algorithme de signature autorisé
scopes/rôles requis
Utilisez une bibliothèque de sécurité maintenue.
N’implémentez pas manuellement la cryptographie des JWT.
16. Valider l’émetteur
Conceptuellement :
iss == serveur d’autorisation attendu
Rejetez les jetons provenant d’émetteurs inattendus.
N’acceptez pas n’importe quel jeton correctement signé s’il ne provient pas d’un émetteur de confiance.
17. Valider l’audience
Conceptuellement :
aud contient cette API
Un jeton destiné à une autre API ne doit pas être accepté.
La validation de l’audience empêche la réutilisation de jetons entre des services sans rapport.
18. Valider l’expiration du jeton
Vérifiez :
exp
et rejetez les jetons expirés.
Une petite tolérance pour le décalage d’horloge peut être appropriée, mais elle doit être délibérée et limitée.
19. Valider nbf
Si le jeton contient :
nbf
ne l’acceptez pas avant cette date.
Cela protège contre l’utilisation anticipée de jetons dont la validité commence plus tard.
20. Valider l’autorisation après l’authentification
L’authentification répond à :
Qui appelle ?
L’autorisation répond à :
Qu’est-ce que cet appelant a le droit de faire ?
Exemple :
utilisateur authentifié
+
scope: reports.read
→ GET /reports autorisé
même utilisateur
sans reports.write
→ POST /reports refusé
Ne vous arrêtez pas à la validation du jeton.
21. Autorisation basée sur les scopes
Exemple de scope de jeton :
reports.read reports.write
Logique serveur :
GET /reports
→ exige reports.read
POST /reports
→ exige reports.write
Alignez les scopes sur les capacités de l’API, pas sur des écrans d’interface arbitraires.
22. Autorisation basée sur les rôles
Exemple :
role = ReportAdmin
Les rôles peuvent être utiles pour des autorisations applicatives à granularité grossière.
Évitez de créer un rôle pour chaque endpoint.
23. Autorisation au niveau de la ressource
Même avec un jeton valide et le bon scope, vérifiez que l’appelant peut accéder à la ressource demandée.
Exemple :
tenant_id du jeton = tenant-a
le rapport demandé appartient à tenant-b
→ refuser
C’est essentiel dans les API multi-tenant.
24. L’isolation des tenants relève de la logique d’autorisation
Ne faites pas confiance à :
tenantId
provenant à lui seul d’une chaîne de requête ou d’un corps de requête.
Déduisez ou validez l’identité du tenant à partir d’un contexte d’authentification de confiance.
25. Exemple de jeton de service à service
Demander un jeton :
TOKEN="$(
curl \
--silent \
--request POST \
--url "https://auth.example.com/oauth2/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET" \
--data-urlencode "scope=reports.read" \
| jq -r '.access_token'
)"
Utiliser le jeton :
curl \
--header "Authorization: Bearer $TOKEN" \
"https://api.example.com/v1/reports"
Dans le code de production, utilisez si possible la bibliothèque OAuth prise en charge par la plateforme plutôt qu’un traitement en shell.
26. Ne pas demander de scopes plus larges que nécessaire
Mauvais :
scope=*
Mieux :
scope=reports.read
Le moindre privilège réduit le rayon d’impact si un jeton est compromis.
27. Préférer des jetons d’accès de courte durée
Une durée de vie courte réduit l’exposition en cas de fuite d’un jeton.
Ne compensez pas une contrainte opérationnelle en émettant des jetons Bearer à durée de vie extrêmement longue, sauf si le modèle de sécurité l’exige explicitement.
Utilisez plutôt des mécanismes d’actualisation ou d’identité de charge de travail.
28. Mettre en cache les jetons d’accès de façon responsable
Un service n’a pas besoin de demander un nouveau jeton pour chaque appel d’API.
Modèle typique :
obtenir un jeton
→ le mettre en cache jusqu’à l’approche de l’expiration
→ actualiser/obtenir un nouveau jeton
Évitez à la fois de :
- demander un jeton à chaque requête
- réutiliser indéfiniment un jeton expiré
29. Actualiser avant l’expiration avec une marge de sécurité
Conceptuellement :
if token.expires_at <= now + refresh_margin:
token = acquire_new_token()
Utilisez une marge opérationnelle modeste.
N’inventez pas de grandes marges arbitraires qui raccourcissent inutilement la durée de vie effective du jeton.
30. Éviter les rafales d’actualisation de jetons
Dans les services à forte concurrence, de nombreux workers peuvent constater l’expiration en même temps.
Utilisez :
- un cache de jetons partagé
- une synchronisation/un verrou
- une logique d’actualisation à vol unique (single-flight)
pour éviter une rafale de demandes de jetons.
31. Authentification client mTLS
Exemple :
curl \
--cert client-cert.pem \
--key client-key.pem \
"https://api.example.com/v1/data"
Le serveur authentifie le certificat client pendant la négociation TLS.
À utiliser lorsque le modèle de confiance exige une identité machine forte.
32. Le mTLS peut coexister avec des jetons au niveau applicatif
Exemple :
mTLS
→ authentifie la machine appelante / le certificat client
Jeton Bearer
→ transmet l’identité et les autorisations de l’application/de l’utilisateur
Ce modèle en couches est courant dans les intégrations à niveau de confiance élevé.
33. Protéger les clés privées
Les clés privées ne doivent pas être :
- commitées dans le contrôle de code source
- intégrées dans des images de conteneur
- stockées dans une configuration en texte clair
- copiées dans des tickets ou des messages de chat
Utilisez un magasin de secrets sécurisé ou un système de gestion des certificats et des clés.
34. Signature de requêtes HMAC
Certaines API authentifient les requêtes en signant des éléments de la requête avec un secret partagé.
Conceptuellement :
requête canonique
→ HMAC(secret, requête canonique)
→ en-tête de signature
Cela peut protéger l’intégrité de la requête et prouver la possession du secret.
Les règles exactes de canonicalisation sont propres à chaque API.
N’inventez pas votre propre protocole HMAC pour une API publique lorsque des mécanismes d’authentification standard sont disponibles.
35. Protection contre le rejeu des requêtes signées
Les protocoles de signature incluent souvent :
horodatage
nonce
hachage du corps de la requête
Le serveur doit rejeter les requêtes périmées ou rejouées conformément au protocole.
Ne vous fiez pas aux seules signatures si la même requête signée peut être rejouée indéfiniment.
36. Authentification au niveau de la passerelle d’API
Une passerelle peut valider :
- des clés d’API
- des JWT
- des jetons OAuth
- des certificats mTLS
avant que le trafic n’atteigne le backend.
Concevez tout de même soigneusement l’autorisation côté backend.
Ne supposez pas que le seul emplacement réseau rend chaque requête backend digne de confiance.
37. Le backend doit savoir à quelle identité se fier
Si une passerelle transmet des en-têtes d’identité comme :
X-User-ID
X-Tenant-ID
le backend doit garantir que les clients ne peuvent pas contourner la passerelle et falsifier ces en-têtes.
Contrôles typiques :
- réseau backend privé
- accès réservé à la passerelle
- suppression/réécriture des en-têtes
- validation des jetons dans le backend
38. Ne pas faire confiance aux en-têtes d’identité envoyés par des clients arbitraires
Mauvais :
X-User-ID: admin
en provenance de l’internet public.
Les en-têtes d’identité ne sont dignes de confiance que s’ils sont insérés par un intermédiaire de confiance et protégés contre l’usurpation.
39. Utiliser correctement 401 et 403
Signification habituelle :
401 Unauthorized
→ l’authentification est absente ou invalide
403 Forbidden
→ l’appelant est authentifié mais n’est pas autorisé
Certains systèmes modifient volontairement ce comportement pour des raisons de sécurité ou de confidentialité, mais c’est la distinction normale.
40. Renvoyer WWW-Authenticate lorsque c’est approprié
Pour les API à jetons Bearer, une réponse 401 peut inclure des métadonnées de challenge d’authentification.
Le comportement exact dépend de l’API et du framework de sécurité.
Utilisez le comportement standard du framework plutôt que d’inventer une sémantique d’erreur propriétaire.
41. Ne pas renvoyer de détails d’authentification sensibles
Évitez les réponses comme :
Jeton correctement signé, mais le compte utilisateur 12345 est désactivé dans le tenant X
Fournissez suffisamment de détails pour que le client puisse agir, sans exposer l’état de sécurité interne.
42. Garder les erreurs d’authentification observables côté serveur
Journalisez des champs sans risque comme :
request_id
ID du client/de l’application
émetteur
audience
résultat de la vérification des scopes
résultat de la vérification de l’expiration du jeton
issue de l’authentification
Ne journalisez pas :
jeton d’accès brut
secret client
mot de passe
clé privée
jeton d’actualisation
43. Utiliser des identifiants de corrélation
Exemple de requête :
curl \
--header "X-Correlation-ID: auth-test-123" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.example.com/v1/reports"
Cela aide à corréler :
requête du client
journaux de la passerelle
journaux d’authentification
journaux de l’API
44. Tester volontairement un jeton expiré hors production
Les tests d’authentification utiles incluent :
jeton absent
jeton mal formé
jeton expiré
audience incorrecte
émetteur incorrect
jeton valide, scope manquant
jeton valide, mauvais tenant
Cela permet de vérifier que l’API échoue de manière sûre.
45. Tester des jetons avec une audience incorrecte
Un jeton valide pour :
API A
ne doit pas fonctionner automatiquement avec :
API B
La validation de l’audience est essentielle dans les systèmes distribués.
46. Tester l’accès à un mauvais tenant
Pour les API multi-tenant :
tenant du jeton = A
tenant de la ressource = B
l’accès doit être refusé même si le jeton est valide par ailleurs.
Il s’agit d’un test d’autorisation, pas simplement d’un test d’authentification.
47. Ne pas utiliser l’authentification comme substitut à l’autorisation
Hypothèse erronée :
le jeton est valide
→ autoriser tous les endpoints
Modèle correct :
valider l’identité
→ valider l’autorisation
→ valider la propriété de la ressource / le tenant
48. Préférer les standards à l’authentification maison
Bons choix :
- OAuth 2.0
- OpenID Connect lorsqu’une connexion avec identité est nécessaire
- jetons Bearer standard
- mTLS
- identité cloud managée/de charge de travail
À éviter :
en-tête de nom d’utilisateur chiffré maison
signature de JWT faite maison
échange de mots de passe propriétaire
sauf exigence forte et revue.
49. OpenID Connect sert à l’identité au-dessus d’OAuth 2.0
OAuth 2.0 est avant tout un framework d’autorisation.
OpenID Connect ajoute des concepts d’identité utilisateur comme :
ID token
authentification de l’utilisateur
claims d’identité standard
N’envoyez pas un ID token à une API simplement parce que c’est un JWT.
Les API attendent généralement un jeton d’accès.
50. Jeton d’accès ou ID token
Utilisez :
jeton d’accès
→ appeler une API
ID token
→ informer une application cliente de l’utilisateur authentifié
Ne les intervertissez pas, sauf si le fournisseur d’identité documente explicitement ce comportement.
51. Ne pas utiliser un jeton d’actualisation comme jeton d’API
Les jetons d’actualisation sont destinés au serveur d’autorisation.
L’API doit normalement recevoir un jeton d’accès.
52. Introspection de jetons
Les systèmes à jetons opaques peuvent permettre à l’API ou à la passerelle d’appeler un serveur d’autorisation pour vérifier l’état d’un jeton.
Conceptuellement :
jeton
→ endpoint d’introspection
→ actif / inactif + métadonnées
Utile lorsque la révocation immédiate compte et que les jetons ne sont pas autonomes.
Compromis :
- ajoute une dépendance réseau, sauf mise en cache
53. La validation des JWT est généralement locale
Les jetons d’accès JWT autonomes peuvent souvent être validés localement à l’aide de clés publiques de confiance.
Avantage :
- pas d’appel au serveur d’autorisation à chaque requête d’API
Compromis :
- la révocation est moins immédiate, sauf mécanismes supplémentaires
54. Mettre en cache les clés de signature avec prudence
Les validateurs de JWT mettent souvent en cache les clés publiques/JWKS du fournisseur d’identité.
Gérez correctement la rotation des clés.
Ne codez pas en dur un unique certificat de signature pour toujours.
Utilisez le mécanisme standard de découverte des clés du framework de sécurité ou du fournisseur.
55. Rejeter les algorithmes de signature inattendus
N’acceptez pas des algorithmes arbitraires déclarés par le jeton.
Configurez la bibliothèque de validation avec les algorithmes auxquels l’API fait réellement confiance.
56. Ne jamais accepter de JWT non signés
Rejetez les jetons qui utilisent :
alg = none
pour les API protégées.
Utilisez des bibliothèques JWT matures avec des valeurs par défaut sécurisées.
57. Stocker les secrets hors du contrôle de code source
Privilégiez :
- les magasins de secrets managés
- l’identité de charge de travail
- les variables secrètes CI/CD protégées
- une configuration d’exécution sécurisée
Ne commitez pas :
clés d’API
secrets client
clés privées
jetons d’actualisation
mots de passe
58. Effectuer la rotation des identifiants
Un cycle de vie d’identifiants en production doit répondre à :
Qui en est propriétaire ?
Où est-il stocké ?
Quand expire-t-il ?
Comment est-il renouvelé ?
Comment est-il révoqué ?
Qu’est-ce qui casse lorsqu’il change ?
Si ces réponses sont inconnues, la conception de l’authentification est incomplète.
59. Prévoir une rotation avec chevauchement lorsque c’est possible
Rotation plus sûre :
ancien identifiant valide
+
nouvel identifiant déployé
→ les clients migrent
→ l’ancien identifiant est révoqué
Cela réduit le risque d’interruption par rapport à la modification de toutes les dépendances exactement au même moment.
60. Éviter un identifiant partagé entre de nombreux clients
Si 50 services partagent la même clé d’API :
vous ne pouvez pas facilement identifier
quel service a effectué quelle requête
Préférez une identité par client lorsque c’est opérationnellement possible.
Cela améliore :
- l’auditabilité
- la révocation
- la limitation de débit
- la réponse aux incidents
61. Limiter le débit selon une identité stable
Dimensions utiles :
client_id
identité de la clé d’API
tenant
utilisateur
principal de service
Ne vous fiez pas uniquement à l’IP source lorsque des appelants peuvent partager un NAT ou des proxys.
62. Les données d’authentification ne doivent pas servir d’entrée métier arbitraire
Exemple :
sub = sujet authentifié
est un claim d’identité.
Ne réutilisez pas des champs non validés de la requête du client pour remplacer cette identité de confiance.
63. Traiter les claims du jeton comme des entrées de sécurité
Même les claims signés nécessitent :
- une validation de l’émetteur
- une validation de l’audience
- un schéma attendu
- une stratégie d’autorisation
Ne faites pas confiance à un claim simplement parce qu’il existe.
64. Éviter d’accepter par accident des jetons de plusieurs émetteurs
Si plusieurs émetteurs sont pris en charge, configurez-les explicitement.
N’étendez pas la confiance à « n’importe quel jeton signé par un endpoint de clés accessible ».
65. Utiliser HTTPS partout pour les requêtes porteuses d’identifiants
Les clés d’API, les identifiants Basic et les jetons Bearer ne doivent pas transiter en HTTP en clair.
Rediriger de HTTP vers HTTPS n’équivaut pas à ne jamais envoyer l’identifiant en HTTP.
Appelez directement l’endpoint HTTPS.
66. Faire attention aux redirections et aux en-têtes Authorization
Si une URL authentifiée redirige vers un autre hôte, sachez si les identifiants seront transmis.
Ne forcez pas manuellement des en-têtes d’autorisation vers des cibles de redirection sans rapport.
67. Ne pas placer de jetons dans le code source frontend
Un secret intégré dans :
bundle JavaScript
binaire mobile
application de bureau
doit être considéré comme découvrable par le client/l’utilisateur.
Les clients publics ne peuvent pas conserver en toute sécurité des secrets client confidentiels à longue durée de vie.
68. Modèle backend-for-frontend
Pour les applications navigateur, un backend-for-frontend (BFF) peut tenir les jetons sensibles et les identifiants serveur à l’écart du JavaScript du navigateur.
Conceptuellement :
navigateur
→ session BFF
→ backend
→ jetons des API en aval
À utiliser lorsque l’architecture et la plateforme d’identité le permettent.
69. Les sessions d’API basées sur des cookies nécessitent une protection CSRF
Si l’authentification est jointe automatiquement par le navigateur au moyen de cookies, les requêtes qui modifient l’état peuvent nécessiter des défenses CSRF.
Les jetons Bearer placés explicitement dans des en-têtes Authorization présentent un modèle de menace différent côté navigateur.
Ne supposez pas qu’« authentifié » signifie « protégé contre le CSRF ».
70. Les cookies nécessitent des attributs de sécurité
Pour les cookies de session, envisagez :
Secure
HttpOnly
SameSite
en fonction des besoins inter-sites de l’application.
Ne placez pas de jetons de session dans des cookies lisibles par JavaScript, sauf si la conception l’exige explicitement et que le risque est compris.
71. Authentification et CORS sont différents
CORS contrôle l’accès cross-origin depuis le navigateur.
Il n’authentifie pas l’appelant.
Une requête cURL peut appeler une API indépendamment de la stratégie CORS du navigateur.
72. Authentification et chiffrement sont différents
L’authentification répond à :
qui êtes-vous ?
TLS assure :
la confidentialité/l’intégrité du transport
Utilisez les deux.
73. Authentification et signature de requêtes sont différentes
Jeton Bearer :
prouve la possession du jeton
Requête signée :
peut lier l’authentification à des éléments de la requête
Choisissez selon le modèle de menace et les standards du fournisseur.
74. Les échecs d’authentification doivent refuser par défaut (fail closed)
Si le validateur de jetons, la recherche de clés ou une dépendance d’identité échoue de manière inattendue, n’autorisez pas silencieusement la requête.
Les défaillances sensibles pour la sécurité doivent refuser l’accès, sauf si une conception explicitement revue du système prévoit autre chose.
75. Éviter les identifiants de secours maison
Mauvais modèle :
le jeton OAuth échoue
→ essayer une clé d’API d’administration partagée et cachée
Les chemins d’authentification de secours sont faciles à oublier et difficiles à auditer.
Gardez les chemins d’authentification explicites.
76. Utiliser les contrôles d’intégrité avec prudence
Un endpoint de contrôle d’intégrité public peut ne pas exiger d’authentification.
Un endpoint de contrôle d’intégrité de diagnostic/d’administration peut contenir des détails sensibles et doit être protégé.
Décidez délibérément quelles informations sont exposées de façon anonyme.
77. Documenter le contrat d’authentification de l’API
Chaque API doit indiquer clairement :
méthode d’authentification
émetteur du jeton
audience
scopes/rôles requis
durée de vie des identifiants
mécanisme d’actualisation
règles relatives aux tenants
comportement en cas d’erreur
Cela réduit les erreurs d’intégration.
78. Construire une matrice de diagnostic
Pour une requête authentifiée en échec :
Pas d’en-tête Authorization
→ problème côté client/configuration
401 + jeton expiré
→ actualiser/obtenir un nouveau jeton d’accès
401 + émetteur/audience incorrects
→ mauvais jeton / mauvaise configuration de l’API
403 + jeton valide
→ problème d’autorisation/de scope/de tenant
fonctionne en local, échoue dans le service déployé
→ configuration du secret/de l’identité de charge de travail/de l’environnement
échecs intermittents à l’approche de l’expiration
→ course critique dans le cache/l’actualisation des jetons
Interpréter le résultat
| Modèle | Cas d’usage idéal | Préoccupation principale |
|---|---|---|
| Clé d’API | Accès machine simple | Rotation, identité grossière |
| Basic auth | Intégrations héritées/simples | Secret à longue durée de vie assimilable à un mot de passe |
| Jeton Bearer | Jeton d’accès à une API | Vol/rejeu du jeton |
| OAuth client credentials | Service à service | Identité du client et secret/identité de charge de travail |
| OAuth authorization code + PKCE | Accès délégué par l’utilisateur | Gestion des redirections/de la session/des jetons |
| JWT | Format de jeton autonome | Validation correcte de la signature et des claims |
| Jeton opaque | Jeton vérifié de manière centralisée | Disponibilité/latence de l’introspection |
| mTLS | Identité machine/client forte | Cycle de vie des certificats |
| Requête signée HMAC | Protocoles partenaires/API signés | Canonicalisation et protection contre le rejeu |
| Identité de charge de travail | Charges de travail cloud/serveur | Configuration de la plateforme/de l’IAM |
Le principe de conception clé est :
authentifier l’identité
→ autoriser la capacité
→ autoriser la ressource
Points à vérifier
401 Unauthorized
Vérifiez :
- l’absence d’en-tête Authorization
- un jeton mal formé
- un jeton expiré
- un émetteur incorrect
- une audience incorrecte
- une signature invalide
- un échec lié au certificat ou à la clé d’API
403 Forbidden
L’authentification a peut-être réussi.
Vérifiez :
- le scope
- le rôle
- la propriété de la ressource
- le tenant
- la stratégie
- les restrictions IP/réseau
Fonctionne jusqu’à l’expiration approximative du jeton
Vérifiez la logique de mise en cache et d’actualisation des jetons.
Le client réutilise peut-être un jeton expiré, ou plusieurs workers entrent peut-être en concurrence pendant l’actualisation.
Fonctionne en local mais échoue dans le service déployé
Vérifiez :
- les identifiants propres à l’environnement
- l’identité managée/de charge de travail
- la disponibilité des secrets
- l’accès réseau sortant
- l’audience/le scope attendus
Un JWT valide est rejeté
Une « syntaxe de JWT valide » ne suffit pas.
Vérifiez :
- l’émetteur
- l’audience
- la clé de signature
- l’algorithme
expnbf- le scope/rôle requis
Un jeton valide accède aux données d’un autre tenant
Il s’agit d’un défaut d’autorisation/d’isolation.
L’authentification a réussi, mais l’autorisation au niveau de la ressource est absente ou incorrecte.
Notes de production
Les secrets d’authentification sont des identifiants de production
Traitez-les avec le même soin que des mots de passe.
Ne les exposez pas dans :
- les journaux
- les captures d’écran
- les tickets
- le contrôle de code source
- l’historique du shell
- les bundles côté client
Préférer les identifiants de courte durée
Les jetons d’accès de courte durée et l’identité de charge de travail réduisent l’impact d’un vol d’identifiants.
Les secrets statiques à longue durée de vie alourdissent la rotation et la réponse aux incidents.
Les bibliothèques d’authentification sont des dépendances de sécurité
Utilisez des bibliothèques de plateforme/de framework maintenues.
Appliquez-leur les correctifs et évitez la cryptographie ou l’analyse de jetons écrites à la main.
L’autorisation doit se faire au plus près de la ressource protégée
La validation au niveau de la passerelle est utile, mais le service doit tout de même appliquer les autorisations qui comptent pour ses données et ses règles métier.
Les API multi-tenant nécessitent des contrôles de tenant explicites
Ne supposez jamais qu’un jeton valide est autorisé à accéder à chaque tenant représenté par les paramètres de la requête.
La rotation des identifiants doit être testée avant un incident
Si une clé ne peut pas être renouvelée sans interruption de service, la conception de l’authentification est fragile sur le plan opérationnel.
Erreurs fréquentes
1. Considérer le décodage d’un JWT comme une validation
N’importe qui peut décoder le payload d’un JWT.
La confiance exige la validation de la signature et des claims.
2. Envoyer un ID token à une API
Utilisez le jeton d’accès destiné à cette API.
3. Journaliser des jetons bruts
Les journaux ont souvent une rétention et un accès étendus.
4. Partager une même clé d’API entre de nombreux clients
Cela nuit à l’auditabilité et à la révocation.
5. Placer des secrets dans les chaînes de requête
Ils fuitent facilement.
6. Utiliser des jetons Bearer à longue durée de vie parce que l’actualisation est contraignante
Cela aggrave l’impact d’une compromission.
7. Valider l’authentification mais pas l’accès au tenant/à la ressource
Cela provoque des défauts de sécurité, notamment entre tenants.
8. Accepter n’importe quel JWT signé par un fournisseur connu
L’émetteur et l’audience doivent tout de même correspondre à la stratégie de confiance de l’API.
9. Stocker des secrets client dans le code frontend
Les clients publics ne peuvent pas garder des secrets confidentiels.
10. Construire une authentification maison au lieu d’utiliser des standards établis
Les cas limites de sécurité s’accumulent rapidement.
Ce contenu vous a-t-il été utile ?
Que pourrions-nous améliorer ?
Merci — cela m’aide à améliorer Javi Builds.
Restez au courant
Recevez uniquement les nouvelles de Javi Builds qui vous intéressent.
Consultez votre boîte de réception
Je vous ai envoyé un lien de confirmation. Votre abonnement sera actif après confirmation.