Structure JWT

Trois segments, deux points

La sérialisation compacte est header.payload.signature — chaque segment encodé indépendamment en Base64url, les points servant de séparateurs littéraux. L’encodage omet délibérément le padding, si bien qu’un token ne contient que des lettres, des chiffres, des tirets et des underscores : sans danger dans les URL, les en-têtes et les cookies, sans échappement. Décoder les deux premiers segments n’est pas un piratage — c’est la manière prévue d’inspecter un token ; le troisième segment est celui où intervient la vérification.

Un vrai token, avec une signature calculée sur lui, se décode exactement comme ceci :

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzg0OTIiLCJhdWQiOiJhcGkuZXhhbXBsZS5jb20iLCJpYXQiOjE3NjcyMjU2MDAsImV4cCI6MTc2NzMxMjAwMCwianRpIjoiYjBmNmMyZDQtNGU3YS00YzFmLTlhMmItM2Q1ZTdmOWExYzNlIn0.iDPqw4BRxZtM064Y3EH83XLB0cgEjbj5snSXeM846VY

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

{"iss":"https://auth.example.com","sub":"user_8492",
 "aud":"api.example.com","iat":1767225600,
 "exp":1767312000,
 "jti":"b0f6c2d4-4e7a-4c1f-9a2b-3d5e7f9a1c3e"}

L’en-tête : la table des matières du token

L’en-tête est un petit objet JSON — formellement le JWS Protected Header. Deux champs font presque tout le travail : alg nomme l’algorithme de signature, et typ enregistre le type de média, JWT par convention. Un troisième, kid (identifiant de clé), oriente le vérificateur vers la bonne clé quand un émetteur en publie plusieurs. L’en-tête est signé mais jamais chiffré, et il n’est fiable qu’une fois la signature vérifiée — jusque-là, alg est une revendication, pas un fait.

Le payload : les revendications enregistrées et ce que chacune promet

Le payload est un objet JSON de revendications. Sept d’entre elles sont enregistrées par la RFC 7519 avec des significations précises et interopérables ; tout le reste est privé, propre à l’émetteur et à l’audience. Les heures sont des valeurs NumericDate — des secondes depuis l’epoch Unix, pas des millisecondes — et les revendications temporelles n’ont qu’une valeur indicative pour le vérificateur : c’est à lui de les contrôler, ce n’est pas le format qui l’impose.

La signature : HS256, RS256 et le fonctionnement de la vérification

La signature est calculée sur l’entrée à signer — l’en-tête encodé, un point, le payload encodé — avec l’algorithme que nomme l’en-tête. HS256 est du HMAC-SHA256 avec un secret partagé : rapide et symétrique, approprié uniquement quand le signataire et chaque vérificateur forment un même domaine de confiance, car quiconque détient le secret peut fabriquer des tokens. RS256 est du RSA : l’émetteur signe avec une clé privée et n’importe qui — y compris un navigateur — peut vérifier avec la clé publique publiée, ce qui en fait le choix par défaut des protocoles fédérés comme OAuth 2.0 et OpenID Connect.

La vérification recalcule la signature et compare. C’est tout le mécanisme — et c’est pourquoi l’en-tête alg, à lui seul, décide comment le contrôle s’effectue. Les bibliothèques se sont durcies après les attaques de confusion d’algorithme du début des années 2010 : un token déclarant alg none, ou un token RS256 rejoué comme HS256 en utilisant la clé publique comme secret HMAC, ne passe la vérification qu’auprès des vérificateurs qui omettent d’épingler leur algorithme attendu.

HS256: HMAC-SHA256(secret, header + '.' + payload)
       le signataire et le vérificateur partagent le secret

RS256: RSA-SHA256(private key, header + '.' + payload)
       l’émetteur signe ; n’importe qui vérifie avec la clé publique

Fixez l’algorithme attendu pour chaque émetteur.
Ne le déduisez jamais du seul en-tête du jeton.
N’acceptez jamais alg: none.

Signé, pas scellé : ce que la signature ne fait pas

La signature prouve que le token a été émis par celui qui détient la clé et qu’il n’a pas été altéré depuis — intégrité et authenticité. Elle n’offre aucune confidentialité : Base64url est un encodage, et le payload est lisible par quiconque voit passer le token, y compris les extensions de navigateur, les proxys quand les tokens circulent dans des URL, et les collecteurs de logs. Les règles permanentes en découlent : ne jamais placer de secrets dans un payload JWT, ne jamais envoyer de tokens dans des URL, et traiter chaque revendication décodée comme une donnée plutôt que comme une décision.

Ce dernier point est le piège côté client. Un navigateur peut décoder un token et lire exp ou sub — mais il ne peut pas vérifier le token de manière significative, parce qu’il ne détient pas la clé de l’émetteur : avec HS256, le secret ne doit jamais atteindre un navigateur du tout, et avec RS256, un contrôle côté client ne prouve rien sur ce à quoi le détenteur a accès. Les clients peuvent inspecter des tokens pour l’affichage — montrer un nom, avertir d’une expiration prochaine — mais c’est au serveur de vérifier la signature et chaque revendication à chaque requête. Inspecter n’est pas vérifier, et lisible ne veut pas dire autorisé.

Inspecter des tokens en toute sécurité — la boucle pratique

Une boucle d’inspection disciplinée prend quelques secondes : décoder l’en-tête et le payload, vérifier exp et nbf par rapport à l’horloge, confirmer que iss et aud sont bien ceux attendus, et seulement alors — sur le serveur — vérifier la signature avec un algorithme épinglé et la bonne clé. Tout, sauf la vérification finale, n’est que traitement de texte, et c’est pourquoi un décodeur qui s’exécute entièrement dans votre navigateur est le bon outil : les vrais tokens sont des secrets de type bearer, et un secret a sa place dans les onglets que vous contrôlez, pas sur des sites qui pourraient les faire suivre.

Gardez en mémoire ce que la structure ne peut pas vous donner : la révocation — les listes de blocage fondées sur jti doivent être construites et consultées côté serveur ; la confidentialité — utilisez JWE si vous avez besoin de tokens chiffrés ; et la confiance — un token structurellement parfait, émanant d’un émetteur que vous n’avez jamais configuré, ne vaut rien. La structure vous dit ce qui a été promis ; seule la vérification vous dit que la promesse est intacte.