Débogage de jetons JWT : problèmes courants

Pourquoi les JWT cassent et où chercher

L'authentification par JWT échoue d'un petit nombre de façons récurrentes : jetons expirés, dérive d'horloge, émetteur ou audience incompatibles, confusion d'algorithme et erreurs de vérification de signature.

Presque toutes laissent une trace lisible. Un JWT n'est pas opaque – son en-tête et son payload sont du JSON encodé en Base64URL que n'importe qui peut décoder. Les claims vous disent ce que le jeton prétend sur lui-même ; l'erreur de votre serveur vous dit ce qu'il a rejeté.

Ce guide parcourt le flux de débogage, du jeton lui-même à la configuration de la bibliothèque, et montre comment le faire sans fuiter le jeton vers un site quelconque.

Anatomie d'un JWT : trois segments, une signature

Un JWT est composé de trois segments séparés par des points : en-tête.payload.signature.

L'en-tête déclare l'algorithme (alg) et le type de jeton (typ). Le payload contient les claims – des déclarations sur le sujet et le jeton lui-même. Les deux sont du JSON brut, encodé en Base64URL, lisible par n'importe qui.

La signature est produite avec l'algorithme de l'en-tête et une clé détenue par l'émetteur. Elle permet au vérificateur de confirmer que le jeton n'a pas été modifié et qu'il a été signé par la partie attendue.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
# header      = {"alg":"HS256","typ":"JWT"}
# payload     = {"sub":"1234567890","name":"John Doe","iat":1516239022}
# signature   = HMAC-SHA256(header.payload, secret)

Les claims standard et leur signification

Un flux de débogage sûr

1. Copiez le JWT complet depuis le journal, l'en-tête ou la requête en échec – points inclus.
2. Décodez-le localement avec le décodeur JWT – ne collez jamais les jetons de production dans un service en ligne non vérifié.
3. Lisez les claims du payload : exp, iat, nbf, iss, aud, sub.
4. Convertissez exp en heure lisible et comparez-la à l'heure actuelle du serveur, pas à celle de votre ordinateur portable.
5. Vérifiez iss et aud par rapport à ce que votre API est configurée pour accepter.
6. Si les claims semblent corrects, l'échec vient de la vérification : algorithme, clé ou gestion de l'horloge dans la bibliothèque.
7. Masquez le jeton avant de partager des journaux avec qui que ce soit, même en interne.

Motifs d'échec courants et correctifs

Décoder n'est pas vérifier

Décoder lit les claims – n'importe quel outil peut le faire, sans clé. Vérifier prouve l'authenticité du jeton : signature, exp, nbf, iss, aud et algorithme, contrôlés par le serveur avec la bonne clé.

Le débogage commence généralement par le décodage pour comprendre le jeton, puis passe à la vérification pour comprendre pourquoi le serveur l'a rejeté.

Méfiez-vous des services de décodage qui prétendent vérifier les signatures : une vraie vérification exige la clé secrète ou publique, qu'un service distant ne devrait jamais vous demander de fournir. Un outil côté client est la valeur sûre.

Outils de débogage au-delà du décodeur

• Un décodeur JWT côté client pour lire les claims sans envoyer le jeton
• Le convertisseur d'horodatage pour transformer les secondes Unix de exp/iat en dates lisibles
• Un décodeur Base64/Base64URL pour inspecter les segments individuellement
• La bibliothèque JWT de votre langage avec vérification de signature activée et algorithme épinglé
• Des journaux de requêtes structurés qui masquent les en-têtes Authorization par défaut

FAQ

Références

• RFC 7519 – JSON Web Token (JWT) : https://www.rfc-editor.org/rfc/rfc7519
• RFC 7515 – JSON Web Signature (JWS) : https://www.rfc-editor.org/rfc/rfc7515
• RFC 7517 – JSON Web Key (JWK) : https://www.rfc-editor.org/rfc/rfc7517
• Aide-mémoire OWASP JWT : https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html