Décoder un token JWT : lire les claims en navigateur

Si vous avez déjà fixé une longue chaîne comme eyJhbGciOi... dans une réponse d'API en vous demandant ce qu'elle raconte vraiment, vous n'êtes pas seul. Savoir décoder un token JWT est une compétence de débogage précieuse, qui s'apprend en une trentaine de secondes. Un JSON Web Token (JWT) ressemble à du charabia aléatoire, mais ce n'est en réalité que trois morceaux lisibles collés ensemble avec des points. Dans ce guide, vous apprendrez ce que contient chaque morceau, comment décoder un token en toute sécurité dans votre navigateur sans rien installer, et l'erreur de sécurité à ne jamais commettre en inspectant des tokens.

Ce que contient vraiment un JWT

Un JWT transporte des informations de façon compacte et compatible avec les URL entre deux parties — le plus souvent entre un serveur et un navigateur ou une application mobile après la connexion. Quand l'authentification réussit, le serveur crée un token rempli de claims : de petites affirmations comme « c'est l'utilisateur 42 », « ce token a été émis à 15 h » ou « il expire dans une heure ». Le client renvoie ensuite ce token avec chaque requête, généralement dans l'en-tête Authorization, pour que le serveur sache qui demande quoi.

Ce qui surprend la plupart des débutants : un JWT standard est signé, mais pas chiffré. Quiconque possède la chaîne du token peut lire le payload — aucune clé secrète requise. La signature prouve seulement que le token vient de quelqu'un qui détient le secret (ou la clé privée) et qu'il n'a pas été modifié. Lire et faire confiance sont deux opérations distinctes, et cette confusion cause la plupart des failles de sécurité liées aux JWT.

Le token transportant les données utilisateur, les serveurs vérifient les requêtes sans interroger la base à chaque fois — mais cela en fait aussi un identifiant de porteur, comme un mot de passe temporaire. Quiconque le détient peut agir au nom de l'utilisateur jusqu'à son expiration : manipulez donc les vrais tokens avec précaution.

Header, payload, signature : les trois parties

Tous les guides sur la façon de décoder un token JWT commencent par la même anatomie, car la structure ne change jamais : header.payload.signature — trois segments encodés en Base64URL séparés par des points, chacun étant du JSON brut en dessous.

1. Le header. Un petit objet JSON décrivant le token, presque toujours avec deux champs : typ ("JWT") et alg, l'algorithme de signature, par exemple HS256 (HMAC avec SHA-256) ou RS256 (RSA avec SHA-256). Un header décodé typique :

{"alg": "HS256", "typ": "JWT"}

2. Le payload. Le payload contient les claims — les vraies données. Les claims sont enregistrés (les standards iss, sub, aud, exp, nbf, iat, jti), publics (noms personnalisés enregistrés pour éviter les collisions) ou privés (définis d'un commun accord entre émetteur et consommateur, comme un rôle utilisateur). L'exemple classique :

{"sub": "1234567890", "name": "Jane Doe", "iat": 1516239022}

3. La signature. La signature est créée en signant ensemble le header encodé, un point et le payload encodé — avec HMAC, c'est HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret) ; avec RSA, l'émetteur signe avec sa clé privée. Tout est encodé en Base64URL — une variante du Base64 compatible avec les URL qui remplace + par - et / par _ — pour que les tokens survivent sans dommage dans les URL et les en-têtes.

Comment décoder un token en toute sécurité dans votre navigateur

Passons à la pratique : décoder un token JWT sans installer de logiciel. Trois bonnes options s'offrent à vous, et les plus sûres n'envoient jamais votre token à un serveur.

Option 1 : un décodeur côté client. Le plus simple : un décodeur JWT gratuit qui fonctionne entièrement dans votre navigateur — collez le token, le header et le payload s'affichent instantanément en JSON lisible. Le décodage se fait localement en JavaScript, donc le token ne quitte jamais votre machine : aucun envoi, aucun journal serveur, rien à fuiter.

Option 2 : la console de votre navigateur. Au clavier : ouvrez les DevTools et exécutez cette ligne — elle reconvertit d'abord le Base64URL en Base64 standard :

JSON.parse(atob(token.split('.')[1].replace(/-/g,'+').replace(/_/g,'/')))

Elle isole le segment du milieu, reconvertit les caractères URL, le décode avec atob() puis analyse le JSON. Elle ne lit que le payload, sans vérifier la signature : parfait pour inspecter, mais ne considérez pas le contenu comme fiable.

Option 3 : une page de débogage. Des pages comme jwt.io décodent aussi les tokens dans le navigateur et permettent de tester la vérification de signature avec un secret. Elles fonctionnent, mais pour une lecture rapide, préférez un outil minimal de confiance — collez le token dans le décodeur JWT de Toolinga pour des réponses immédiates.

Rappelez-vous : décoder n'est pas vérifier. Décoder lit le payload ; vérifier contrôle la signature, ce qui exige le secret (HMAC) ou la clé publique (RSA). Un décodeur affiche sans broncher un payload à signature invalide : ne faites jamais confiance à un token parce qu'il s'est décodé proprement.

Les claims courants expliqués (exp, iat, sub)

Une fois le décodage maîtrisé, comprenez les claims standard. Ces trois-là figurent dans presque tous les tokens rencontrés :

• exp — date d'expiration. Le moment après lequel le token ne doit plus être accepté. C'est une NumericDate : le nombre de secondes écoulées depuis l'époque Unix (1970-01-01T00:00:00Z). Si exp vaut 1760500000, le token meurt à cette seconde précise. Face à des erreurs « token expiré », lire exp après décodage est le diagnostic le plus rapide — convertissez ce nombre avec un convertisseur d'époque ou new Date(1760500000 * 1000) dans la console.
• iat — date d'émission. Le moment où le token a été créé, dans le même format NumericDate. Comparer iat et exp révèle d'un coup d'œil la durée de vie du token, pratique pour repérer une expiration mal configurée (des tokens qui vivent un an parce qu'on a tapé des jours au lieu de secondes, par exemple).
• sub — sujet. La personne concernée par le token — généralement un identifiant utilisateur comme "sub": "user_8f42". Si les requêtes semblent appartenir au mauvais compte, vérifier sub révèle aussitôt si le token est en cause ou si le problème vient d'ailleurs.

Vous croiserez aussi iss (émetteur), aud (audience), nbf (pas valide avant cette heure) et jti (identifiant unique, pratique pour la révocation). Les serveurs tolèrent quelques secondes de décalage d'horloge sur exp : inutile de traquer une seconde d'écart.

Pourquoi ne jamais coller de tokens sur des sites inconnus

Voici la leçon de sécurité essentielle : le payload n'étant qu'encodé, la chaîne du token est elle-même le secret — quiconque la copie peut la rejouer contre l'API et usurper l'utilisateur jusqu'à exp. Coller un token de production dans un décodeur qui l'envoie à un serveur, le journalise ou l'affiche dans une capture partagée, c'est remettre votre session à celui qui contrôle ce serveur.

Suivez donc trois règles. Premièrement, décodez avec des tokens de test : utilisez un token factice ou expiré, ou un token émis pour un utilisateur de test jetable, avant d'essayer un nouvel outil. Deuxièmement, préférez les outils qui décodent localement : hors ligne, votre token ne quitte jamais votre machine. Troisièmement, considérez toute exposition comme une compromission : si un vrai token a pu fuiter, révoquez-le immédiatement. Les tokens d'accès à courte durée de vie existent précisément pour limiter les dégâts.

Le débogage de tokens se fait rarement seul — en traquant un échec d'authentification, vous avez souvent aussi les journaux de requêtes sous les yeux ; les passer d'abord dans un formateur SQL rend la session bien moins pénible. Gardez la boucle courte : décodez, lisez les claims, vérifiez les requêtes.

Décoder un JWT, est-ce la même chose que le vérifier ?

Non. Décoder décode le payload en Base64URL pour pouvoir le lire — aucun secret nécessaire. Vérifier contrôle la signature cryptographique, ce qui exige le secret HMAC ou la clé publique RSA. Un token peut se décoder parfaitement tout en ayant une signature invalide.

Puis-je décoder un JWT sans la clé secrète ?

Oui. Le payload d'un JWT standard est seulement encodé, pas chiffré, donc aucun secret n'est nécessaire pour le lire. Le secret ne sert qu'à vérifier la signature ou à émettre de nouveaux tokens. Les tokens vraiment chiffrés (JWE) sont un format différent et ne peuvent pas être lus sans la clé.

Pourquoi mon token affiche-t-il « signature invalide » dans un décodeur ?

Presque toujours parce que le décodeur ignore votre secret de signature — collez-le dans le champ de vérification. Autres causes : token modifié après signature, mauvais algorithme sélectionné, ou espaces parasites copiés. Le payload se décode correctement de toute façon.

Comment savoir exactement quand mon token expire ?

Décodez le token, lisez le claim exp et convertissez l'horodatage Unix — new Date(exp * 1000) dans la console donne le moment exact d'expiration. Comparez avec l'heure actuelle pour connaître la durée de vie restante du token.

Lire les tokens est un réflexe de débogage quotidien, pas un art obscur. Maintenant que vous savez décoder un token JWT — ses trois parties, le sens de exp, iat et sub, et pourquoi les tokens actifs méritent le respect — la prochaine chaîne eyJ... mystérieuse ne vous résistera que quelques secondes. Quand elle apparaîtra, décodez-la gratuitement dans votre navigateur avec le décodeur JWT de Toolinga : collez, lisez, déboguez, terminé.