Décodez les claims localement avec le décodeur JWT.
Pourquoi les jetons expirent
Les jetons d'accès à courte durée limitent les dégâts d'un jeton fuité : un attaquant n'a que des minutes, pas des mois, pour l'utiliser. Le claim exp enregistre l'expiration comme un horodatage Unix absolu en secondes.
La plupart des bibliothèques d'authentification vérifient exp automatiquement. Quand elles rejettent un jeton que vous attendiez valide, la cause est généralement l'une de ces trois choses : un jeton réellement expiré, une erreur d'unité ou une dérive d'horloge.
Les claims qui contrôlent la durée de vie
Ces trois valeurs sont des NumericDate : des secondes depuis l'epoch Unix (1970-01-01T00:00:00Z). Converti en UTC, 1784563200 devient une date et une heure claires. Vérifiez chaque claim.
| Claim | Signification | Piège courant |
|---|---|---|
| exp | Heure d'expiration (secondes Unix) | Comparer avec des millisecondes au lieu de secondes |
| iat | Heure d'émission (secondes Unix) | Un iat très futur indique une dérive ou un jeton forgé |
| nbf | Non valide avant (secondes Unix) | Le jeton est rejeté jusqu'à cette heure ; vérifiez les valeurs futures |
| iss / aud / sub | Émetteur, audience, sujet | Une incompatibilité ressemble à un bug d'expiration mais c'est un problème de configuration |
Ce que fait réellement la dérive d'horloge
La dérive d'horloge est la différence entre l'horloge de l'émetteur du jeton et celle du vérificateur. NTP maintient la plupart des serveurs proches, mais les conteneurs, runners CI et fonctions cloud peuvent dériver ou démarrer avec une horloge figée.
Si le vérificateur est en retard sur l'émetteur, un jeton fraîchement émis peut sembler pas encore valide. Si le vérificateur est en avance, un jeton valide semble expiré. Les deux produisent des erreurs déroutantes comme « token used before issued » ou « token expired ».
Les bibliothèques de vérification ajoutent une tolérance. Avec 30 secondes, un exp jusqu'à 30 secondes dans le passé passe encore, et un nbf futur de 30 secondes est toléré. Cela absorbe la dérive NTP.
Déboguez les erreurs d'expiration localement, pas à pas
- Copiez le jeton en échec et ouvrez le décodeur JWT.
- Lisez exp, iat et nbf dans le payload.
- Convertissez-les en heures lisibles avec le convertisseur d'horodatage.
- Comparez chaque valeur avec l'heure UTC actuelle du serveur.
- Vérifiez l'horloge du serveur elle-même avec la commande date et comparez-la à une source NTP.
- Ajoutez une petite tolérance (30–60 secondes) à la vérification et re-testez.
Avertissement: Ne corrigez pas la dérive en réglant la tolérance sur des heures. Une grande tolérance étend silencieusement la durée de vie des jetons et affaiblit la sécurité que exp est censé fournir.
Liste de prévention
- Gardez les horloges serveur synchronisées avec NTP, y compris les runners CI et conteneurs
- Vérifiez avec une tolérance de 30–60 secondes, jamais plus
- Comparez toujours exp/iat/nbf en secondes Unix, jamais en millisecondes
- Créez des jetons à durée de vie plus longue dans les environnements de test au lieu d'augmenter la tolérance en production
- N'émettez pas un nouveau jeton à chaque requête ; réutilisez le jeton actuel jusqu'à exp, sauf vraie raison de rotation
FAQ
Q.Pourquoi un jeton expire-t-il avant sa durée de vie annoncée ?
A.Généralement parce que l'horloge du vérificateur est en avance sur celle de l'émetteur (dérive d'horloge) ou parce que exp a été calculé avec la mauvaise unité. Décodez le jeton et comparez le claim avec l'heure UTC actuelle. Si exp n'est que de quelques minutes dans le passé sur un jeton frais, c'est de la dérive ; un facteur 1000, des millisecondes.
Q.Quelle tolérance dois-je utiliser ?
A.30–60 secondes est la plage courante. Assez pour absorber la dérive NTP, assez peu pour garder l'expiration signifiante. Une tolérance plus grande pour le confort du CI doit être implémentée en émettant des jetons à durée de vie plus longue, pas en assouplissant la vérification. Une vérification assouplie s'applique partout, pas seulement en CI.
Q.Dois-je utiliser des secondes ou des millisecondes pour les claims temporels JWT ?
A.Des secondes. RFC 7519 définit NumericDate comme des secondes depuis l'epoch Unix. Envoyer des millisecondes dans les comparaisons exp est l'une des causes les plus courantes de bugs d'expiration fantômes. Indice : un jeton frais dont exp tombe dans les années 2030.
Q.Pourquoi ma bibliothèque signale-t-elle « token used before issued » ?
A.Cette erreur vient du claim iat ou nbf : le vérificateur pense que le jeton a été émis dans le futur. Souvent, son horloge est en retard sur celle de l'émetteur. Une petite tolérance absorbe l'écart ; des minutes signalent une horloge à synchroniser.
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
- OWASP JSON Web Token Cheat Sheet : https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html
Décodez un jeton maintenant
En-tête et payload dans votre navigateur, en lecture seule. Vérifiez exp, iat et nbf en secondes.
Lisez les claims avant de changer le code
Décodez le jeton en échec, convertissez exp, iat et nbf avec le convertisseur d'horodatage et comparez à l'horloge du serveur en UTC. La plupart des erreurs « expiré » sont de la dérive ou des erreurs d'unité.
Si les horloges sont synchronisées et que le calcul est bon, une tolérance de 30–60 secondes absorbe la dérive NTP sans vider l'expiration. Décodez les jetons avec le décodeur JWT.