Comment résoudre les erreurs "JWT Expired" et "Invalid Signature"

Les erreurs JWT telles que TokenExpiredError et signature invalide sont fréquentes en développement web. Ce guide explique chaque erreur majeure, sa sa cause spécifique et comment la résoudre sans jamais exposer vos jetons à des outils tiers vers des serveurs distants.

Table des matières

1. Les 5 erreurs JWT les plus courantes
2. Comment débugger un JWT sans l'exposer
3. Expiration JWT — Fonctionnement de la durée de vie
4. Comment prévenir les erreurs JWT en production
5. FAQ

Les 5 erreurs JWT les plus courantes

Comprendre la cause profonde des messages d'erreur automatisés est la première étape vers une résolution sécurisée. Voici les cinq problèmes les plus fréquents rencontrés par les développeurs.

1. TokenExpiredError : jwt expired

• Cause : La revendication exp (expiration) dans la charge utile du jeton contient un horodatage passé. Le serveur rejette correctement le jeton car il n'est plus valide.
• Solution :
  • Synchroniser les horloges serveurs : Assurez-vous que vos serveurs d'application et d'authentification utilisent des horloges NTP synchronisées.
  • Augmenter la durée de vie : Ajustez le paramètre expiresIn lors de la signature (par exemple, de 15m à 30m).
  • Jetons de rafraîchissement : Implémentez un pattern de refresh token pour renouveler les accès sans reconnexion.

2. JsonWebTokenError : invalid signature

• Cause : La signature cryptographique à la fin du JWT ne correspond pas au contenu lorsqu'elle est vérifiée avec la clé secrète ou publique fournie.
• Solution :
  • Vérifier les clés : Assurez-vous que la clé utilisée pour la vérification correspond exactement à celle de la signature.
  • Confusion d'algorithme : Une vulnérabilité critique. Consultez notre article sur la Confusion d'algorithme JWT.

3. JsonWebTokenError : jwt malformed

• Cause : La chaîne du jeton ne respecte pas le format standard header.payload.signature. Il peut manquer un point ou contenir des caractères invalides.
• Solution :
  • Vérifiez les espaces ou les sauts de ligne accidentels.
  • Assurez-vous que le préfixe "Bearer " est correctement supprimé avant la vérification.

4. JsonWebTokenError : jwt not active (NotBeforeError)

• Cause : La revendication nbf (not before) est dans le futur. Le jeton n'est pas encore autorisé à être utilisé.
• Solution :
  • Vérifiez la synchronisation de l'horloge du serveur.

5. Error : invalid algorithm

• Cause : L'algorithme spécifié dans l'en-tête JWT n'est pas dans la liste des algorithmes acceptés par le serveur.
• Solution :
  • Définissez explicitement les algorithmes autorisés dans votre code (ex: jwt.verify(token, key, { algorithms: ['RS256'] })).

Comment débugger un JWT sans l'exposer

L'une des erreurs les plus courantes consiste à copier un JWT de production dans un décodeur en ligne public pour comprendre pourquoi il échoue.

Le risque : La plupart des décodeurs en ligne envoient votre jeton à leur serveur. Si le jeton est encore valide, le fournisseur de l'outil (ou toute personne ayant accès à ses logs) peut compromettre vos sessions utilisateurs.

La solution : Décodage local dans le navigateur

FmtDev propose une solution 100% côté client. Nos outils s'exécutent entièrement dans la mémoire de votre navigateur ; votre jeton ne quitte jamais votre machine.

1. Copiez votre JWT problématique.
2. Allez sur notre Décodeur JWT Local.
3. Collez le jeton pour voir instantanément l'en-tête et la charge utile décodés.
4. Vérifiez spécifiquement les revendications exp, iat et nbf.

Expiration JWT — Fonctionnement de la durée de vie

Les JWT sont "sans état" (stateless), ce qui signifie que le serveur n'a pas besoin de consulter une base de données pour valider une session.

• exp (Expiration Time) : L'horodatage Unix de fin de validité.
• iat (Issued At) : Date de génération du jeton.
• nbf (Not Before) : Date de début de validité.

Calculer la durée de vie

Vous pouvez calculer le temps restant en soustrayant l'horodatage Unix actuel de la valeur exp.

// Exemple Node.js avec jsonwebtoken
const jwt = require('jsonwebtoken');

try {
  const decoded = jwt.verify(token, 'votre-secret');
} catch (err) {
  if (err.name === 'TokenExpiredError') {
    console.error(`Jeton expiré à : ${err.expiredAt}`);
  }
}

Comment prévenir les erreurs JWT en production

Voici les standards de l'industrie pour minimiser les problèmes JWT :

1. Vérification explicite : Ne faites jamais confiance à l'en-tête du jeton pour choisir l'algorithme.
2. Clés asymétriques : Utilisez RS256 (clé privée/publique) pour les systèmes distribués.
3. Rotation des Refresh Tokens : Renouvelez le refresh token à chaque utilisation pour détecter le vol.
4. Tolérance d'horloge : Gérez le "Clock Skew" (dérive d'horloge) avec une marge de tolérance (ex: 30 secondes).

Pour plus de détails, lisez notre article sur le Décodage sécurisé de JWT.

FAQ

Pourquoi mon JWT indique-t-il "invalid signature" ?

La cause la plus fréquente est l'utilisation d'une mauvaise clé secrète. Vérifiez que la clé de signature et de vérification sont identiques pour HS256, ou que vous utilisez la bonne clé publique pour RS256.

Quelle doit être la durée de vie d'un jeton d'accès ?

Pour des API, 15 à 30 minutes est le standard. Utilisez des jetons de rafraîchissement pour obtenir de nouveaux jetons sans forcer l'utilisateur à se reconnecter.

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

Oui. L'en-tête et la charge utile sont simplement encodés en Base64, pas cryptés. N'importe qui peut les lire. La clé secrète n'est nécessaire que pour vérifier l'intégrité de la signature.

Est-il sûr d'utiliser un décodeur en ligne ?

Non. Les décodeurs en ligne envoient vos données à leurs serveurs. Utilisez un outil local comme le Décodeur JWT de FmtDev qui garantit une confidentialité totale.

Conclusion

Maîtriser les erreurs "JWT Expired" et "Invalid Signature" est essentiel pour tout développeur moderne. En utilisant des outils de débuggage locaux et des pratiques de signature sécurisées, vous garantissez un flux d'authentification robuste.

👉 Débuggez vos jetons JWT localement et en toute sécurité avec FmtDev