Parcourir les aide-mémoire · API

Technologie: APICatégorie: SécuritéNiveau: IntermédiaireMis à jour

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
  1. Problème
  2. Réponse rapide
  3. Code / commandes
  4. 1. Clé d’API dans un en-tête de requête
  5. 2. Préférer les en-têtes aux clés d’API dans la chaîne de requête
  6. 3. Authentification Basic
  7. 4. Ne pas intégrer d’identifiants Basic dans les URL
  8. 5. Jeton d’accès Bearer
  9. 6. Ne pas journaliser les jetons Bearer
  10. 7. OAuth 2.0 client credentials
  11. 8. Préférer l’identité de charge de travail aux secrets client stockés lorsqu’elle est disponible
  12. 9. Flux OAuth authorization code
  13. 10. PKCE protège les flux authorization code pour les clients publics
  14. 11. Modèle du jeton d’actualisation
  15. 12. Effectuer la rotation des jetons d’actualisation lorsque le fournisseur le permet
  16. 13. Exemple de jeton Bearer JWT
  17. 14. Décoder les métadonnées d’un JWT sans le considérer comme validé
  18. 15. Valider la signature du JWT
  19. 16. Valider l’émetteur
  20. 17. Valider l’audience
  21. 18. Valider l’expiration du jeton
  22. 19. Valider nbf
  23. 20. Valider l’autorisation après l’authentification
  24. 21. Autorisation basée sur les scopes
  25. 22. Autorisation basée sur les rôles
  26. 23. Autorisation au niveau de la ressource
  27. 24. L’isolation des tenants relève de la logique d’autorisation
  28. 25. Exemple de jeton de service à service
  29. 26. Ne pas demander de scopes plus larges que nécessaire
  30. 27. Préférer des jetons d’accès de courte durée
  31. 28. Mettre en cache les jetons d’accès de façon responsable
  32. 29. Actualiser avant l’expiration avec une marge de sécurité
  33. 30. Éviter les rafales d’actualisation de jetons
  34. 31. Authentification client mTLS
  35. 32. Le mTLS peut coexister avec des jetons au niveau applicatif
  36. 33. Protéger les clés privées
  37. 34. Signature de requêtes HMAC
  38. 35. Protection contre le rejeu des requêtes signées
  39. 36. Authentification au niveau de la passerelle d’API
  40. 37. Le backend doit savoir à quelle identité se fier
  41. 38. Ne pas faire confiance aux en-têtes d’identité envoyés par des clients arbitraires
  42. 39. Utiliser correctement 401 et 403
  43. 40. Renvoyer WWW-Authenticate lorsque c’est approprié
  44. 41. Ne pas renvoyer de détails d’authentification sensibles
  45. 42. Garder les erreurs d’authentification observables côté serveur
  46. 43. Utiliser des identifiants de corrélation
  47. 44. Tester volontairement un jeton expiré hors production
  48. 45. Tester des jetons avec une audience incorrecte
  49. 46. Tester l’accès à un mauvais tenant
  50. 47. Ne pas utiliser l’authentification comme substitut à l’autorisation
  51. 48. Préférer les standards à l’authentification maison
  52. 49. OpenID Connect sert à l’identité au-dessus d’OAuth 2.0
  53. 50. Jeton d’accès ou ID token
  54. 51. Ne pas utiliser un jeton d’actualisation comme jeton d’API
  55. 52. Introspection de jetons
  56. 53. La validation des JWT est généralement locale
  57. 54. Mettre en cache les clés de signature avec prudence
  58. 55. Rejeter les algorithmes de signature inattendus
  59. 56. Ne jamais accepter de JWT non signés
  60. 57. Stocker les secrets hors du contrôle de code source
  61. 58. Effectuer la rotation des identifiants
  62. 59. Prévoir une rotation avec chevauchement lorsque c’est possible
  63. 60. Éviter un identifiant partagé entre de nombreux clients
  64. 61. Limiter le débit selon une identité stable
  65. 62. Les données d’authentification ne doivent pas servir d’entrée métier arbitraire
  66. 63. Traiter les claims du jeton comme des entrées de sécurité
  67. 64. Éviter d’accepter par accident des jetons de plusieurs émetteurs
  68. 65. Utiliser HTTPS partout pour les requêtes porteuses d’identifiants
  69. 66. Faire attention aux redirections et aux en-têtes Authorization
  70. 67. Ne pas placer de jetons dans le code source frontend
  71. 68. Modèle backend-for-frontend
  72. 69. Les sessions d’API basées sur des cookies nécessitent une protection CSRF
  73. 70. Les cookies nécessitent des attributs de sécurité
  74. 71. Authentification et CORS sont différents
  75. 72. Authentification et chiffrement sont différents
  76. 73. Authentification et signature de requêtes sont différentes
  77. 74. Les échecs d’authentification doivent refuser par défaut (fail closed)
  78. 75. Éviter les identifiants de secours maison
  79. 76. Utiliser les contrôles d’intégrité avec prudence
  80. 77. Documenter le contrat d’authentification de l’API
  81. 78. Construire une matrice de diagnostic
  82. Interpréter le résultat
  83. Points à vérifier
  84. 401 Unauthorized
  85. 403 Forbidden
  86. Fonctionne jusqu’à l’expiration approximative du jeton
  87. Fonctionne en local mais échoue dans le service déployé
  88. Un JWT valide est rejeté
  89. Un jeton valide accède aux données d’un autre tenant
  90. Notes de production
  91. Les secrets d’authentification sont des identifiants de production
  92. Préférer les identifiants de courte durée
  93. Les bibliothèques d’authentification sont des dépendances de sécurité
  94. L’autorisation doit se faire au plus près de la ressource protégée
  95. Les API multi-tenant nécessitent des contrôles de tenant explicites
  96. La rotation des identifiants doit être testée avant un incident
  97. Erreurs fréquentes
  98. 1. Considérer le décodage d’un JWT comme une validation
  99. 2. Envoyer un ID token à une API
  100. 3. Journaliser des jetons bruts
  101. 4. Partager une même clé d’API entre de nombreux clients
  102. 5. Placer des secrets dans les chaînes de requête
  103. 6. Utiliser des jetons Bearer à longue durée de vie parce que l’actualisation est contraignante
  104. 7. Valider l’authentification mais pas l’accès au tenant/à la ressource
  105. 8. Accepter n’importe quel JWT signé par un fournisseur connu
  106. 9. Stocker des secrets client dans le code frontend
  107. 10. Construire une authentification maison au lieu d’utiliser des standards établis
  108. Étape suivante
  109. 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
  • exp
  • nbf
  • 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.

Étape suivante

Utilisez le type d’appelant et le mode de défaillance pour choisir l’action suivante.

  • Intégration machine simple → n’envisagez une clé d’API que si la rotation et la granularité de l’identité sont acceptables.
  • Service à service dans une plateforme d’identité moderne → préférez OAuth client credentials ou l’identité de charge de travail.
  • Accès à une API délégué par l’utilisateur → utilisez le flux authorization code avec PKCE lorsque c’est approprié.
  • L’API reçoit des JWT → validez la signature, l’émetteur, l’audience et les claims temporels, puis les scopes/rôles.
  • Un jeton valide reçoit un 403 → examinez la stratégie d’autorisation, le scope, le tenant et la propriété de la ressource.
  • Les jetons expirent de façon intermittente → examinez le comportement du cache/de l’actualisation et la concurrence.
  • Besoin d’une identité machine forte → évaluez le mTLS.
  • Les secrets sont difficiles à renouveler → repensez le cycle de vie des identifiants avant de faire monter l’intégration en charge.
  • Besoin de reproduire manuellement le comportement d’authentification → utilisez cURL : référence rapide.
  • L’authentification réussit mais l’API échoue toujours → passez à Diagnostiquer les requêtes d’API.

← Tous les aide-mémoire