JsonWebToken pour JavaScript (Node.js) : guide complet avec exemples

Qu'est-ce que c'est et pourquoi l'utiliser

La bibliothèque JsonWebToken (souvent utilisée sous les noms jsonwebtoken ou jwt) est l'une des plus populaires pour manipuler les JSON Web Tokens (JWT) dans l'environnement Node.js. Un JWT est un moyen compact et autonome de transmettre des informations entre deux parties sous la forme d'un objet JSON. Ces informations peuvent être vérifiées et dignes de confiance car elles sont signées numériquement. Les JWT peuvent être signés à l'aide d'une clé secrète (algorithme HMAC) ou d'une paire de clés publique/privée (algorithmes RSA ou ECDSA).

L'objectif principal de cette bibliothèque est d'implémenter des mécanismes d'autorisation et d'authentification dans les applications web et les API. Lorsqu'un utilisateur se connecte avec succès, le serveur crée un JWT et l'envoie au client. Le client renvoie ensuite ce jeton avec chaque requête suivante, permettant au serveur de vérifier l'identité de l'utilisateur sans avoir à stocker les données de session côté serveur. Cela fait du JWT une solution idéale pour créer des API RESTful, des architectures de microservices et des applications monopages (SPA).

La bibliothèque jsonwebtoken fournit un ensemble complet d'outils pour créer (sign), vérifier (verify) et décoder (decode) les jetons. Elle prend en charge tous les algorithmes de signature standard, notamment HS256, RS256 et ES256, et permet de configurer de manière flexible la durée de vie du jeton, d'ajouter des champs personnalisés (claims) et de travailler avec des clés publiques/privées. Grâce à sa fiabilité et sa simplicité, cette bibliothèque est utilisée dans des milliers de projets dans le monde entier et constitue la norme de facto pour travailler avec JWT dans l'écosystème Node.js.

Installation

Pour installer la bibliothèque JsonWebToken dans votre projet Node.js, exécutez la commande suivante dans votre terminal :

npm install jsonwebtoken

Si vous utilisez Yarn :

yarn add jsonwebtoken

Après l'installation, vous pouvez importer la bibliothèque dans votre code :

const jwt = require('jsonwebtoken');
// ou pour les modules ES :
// import jwt from 'jsonwebtoken';

Démarrage rapide — exemple minimal fonctionnel

Créons un exemple simple illustrant la création et la vérification d'un jeton JWT :

const jwt = require('jsonwebtoken');

// Clé secrète (dans un projet réel, stockez-la dans un fichier .env)
const secretKey = 'ma-super-cle-secrete-123';

// Données que nous souhaitons encoder dans le jeton (payload)
const payload = {
  userId: 12345,
  username: 'jean_dupont',
  role: 'user'
};

// 1. CRÉATION DU JETON
const token = jwt.sign(payload, secretKey, { expiresIn: '1h' });
console.log('Jeton créé :', token);

// 2. VÉRIFICATION DU JETON
try {
  const decoded = jwt.verify(token, secretKey);
  console.log('Données décodées :', decoded);
  // Affiche : { userId: 12345, username: 'jean_dupont', role: 'user', iat: ..., exp: ... }
} catch (err) {
  console.error('Erreur lors de la vérification du jeton :', err.message);
}

// 3. DÉCODAGE SANS VÉRIFICATION DE LA SIGNATURE (NON RECOMMANDÉ pour l'autorisation !)
const decodedWithoutVerify = jwt.decode(token);
console.log('Décodé sans vérification :', decodedWithoutVerify);

Cet exemple illustre les trois opérations principales : la création d'un jeton avec sign(), la vérification de son authenticité avec verify() et le simple décodage sans vérification de la signature avec decode().