JWT expliqué : structure, claims et comment en décoder un

Si vous avez travaillé avec une API web moderne, vous avez croisé les JWT — ces longues chaînes de charabia à deux points qui apparaissent dans les réponses de connexion et les en-têtes Authorization. Ils semblent opaques, mais sont étonnamment lisibles une fois qu'on connaît la structure. Ce guide explique ce qu'est un JSON Web Token, ce qu'il contient, comment fonctionne la signature, et les erreurs de sécurité à éviter.

À quoi sert un JWT

Un JSON Web Token (JWT) est une façon compacte et autonome de transporter un ensemble de claims — des affirmations comme « c'est l'utilisateur 42 et il s'est connecté à 10h05 ». Son usage principal est l'authentification : après connexion, un serveur émet un JWT, votre appli le renvoie à chaque requête, et le serveur lui fait confiance au lieu de vous rechercher dans un magasin de sessions à chaque fois. Comme le jeton porte l'information lui-même, il est dit sans état (stateless).

Les trois parties

Tout JWT est composé de trois sections encodées en Base64URL reliées par des points : header.payload.signature.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.3x9kQ...
└──── header ────┘ └── payload ──┘ └ signature ┘

1. En-tête (Header)

Des métadonnées sur le jeton — l'algorithme de signature (alg, p. ex. HS256) et le type (typ: JWT). Décodé, ce n'est qu'un petit JSON :

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

2. Charge utile (Payload)

Les claims — les données réelles. Certains noms sont normalisés (appelés claims enregistrés) :

• sub — sujet (subject), généralement l'ID utilisateur.
• iss — émetteur (issuer), qui a créé le jeton.
• aud — audience, à qui il est destiné.
• exp — heure d'expiration (un timestamp Unix).
• iat — heure d'émission (un timestamp Unix).

Ces valeurs exp et iat sont des secondes depuis 1970 — si vous devez les lire comme de vraies dates, un convertisseur d'horodatage les transforme en heures lisibles.

3. Signature

La signature est ce qui rend le jeton digne de confiance. L'émetteur prend l'en-tête et la charge utile et, à l'aide d'une clé secrète, produit une signature cryptographique. Quiconque a la clé peut vérifier que l'en-tête et la charge utile n'ont pas été altérés — changez un seul caractère de la charge utile et la signature ne correspond plus.

La chose la plus importante à comprendre

Un JWT est signé, pas chiffré. L'en-tête et la charge utile ne sont qu'encodés en Base64URL, ce qui signifie que n'importe qui peut les décoder et les lire — sans clé. La signature empêche la falsification, pas la lecture.

La conséquence pratique : ne mettez jamais de secrets dans une charge utile JWT. Aucun mot de passe, aucun numéro de carte, aucune donnée privée — considérez la charge utile comme publique. Vous pouvez le confirmer vous-même en collant n'importe quel jeton dans notre décodeur JWT, qui lit l'en-tête et les claims instantanément, entièrement dans votre navigateur (le jeton ne quitte jamais votre appareil). En dessous, ce n'est que du décodage Base64 — le décodeur vous épargne simplement les étapes.

Vérifier vs. décoder

Ce sont deux actions différentes, et les confondre est un vrai bug de sécurité. Décoder lit la charge utile — n'importe qui peut le faire et cela ne prouve rien. Vérifier contrôle la signature avec la clé et confirme que le jeton est authentique et inaltéré. Un serveur doit vérifier chaque jeton avant de lui faire confiance ; décoder seul n'est pas de l'authentification.

Pièges courants

• Faire confiance à un jeton non vérifié — contrôlez toujours la signature côté serveur avant d'agir sur les claims.
• Ignorer l'expiration — respectez exp ; un jeton expiré doit être rejeté.
• Stocker des données sensibles dans la charge utile — elle est lisible par tout le monde.
• Le piège `alg: none` — certaines bibliothèques acceptaient autrefois des jetons prétendant « aucune signature ». Rejetez-les et fixez l'algorithme attendu.

Comprenez cela et les JWT passent de chaînes intimidantes à un format simple et transparent : des claims lisibles, protégés par une signature que vous devez vérifier avant de faire confiance.