JWT en Node.js : signer, vérifier et protéger des routes

Un JWT (JSON Web Token) est une chaîne en trois parties base64url, header.payload.signature, qu'un serveur remet à l'utilisateur à la connexion et vérifie à chaque requête suivante. La signature prouve que le serveur a émis le token et que personne ne l'a modifié, mais le payload est seulement encodé, pas chiffré, donc tout le monde peut le lire. En Node.js, vous en créez un avec new SignJWT(payload).sign(secret) du package jose et vous le vérifiez avec jwtVerify(token, secret).

import { SignJWT, jwtVerify } from 'jose';

// In a real app the secret comes from process.env.JWT_SECRET
const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');

const token = await new SignJWT({ role: 'admin' })
    .setProtectedHeader({ alg: 'HS256' })
    .setSubject('user-42')
    .setIssuedAt()
    .setExpirationTime('1h')
    .sign(secret);

console.log(token.split('.').length, 'parts');

const { payload } = await jwtVerify(token, secret);
console.log(payload.sub, payload.role);

Le programme affiche 3 parts, puis user-42 admin : jwtVerify a vérifié la signature et l'expiration, puis a renvoyé le payload. Changez d'un caractère le secret passé à jwtVerify et relancez : la vérification échoue avec signature verification failed.

Ce que contient un JWT

Le header et le payload sont du JSON encodé en base64url. Les décoder ne demande aucune clé, c'est pourquoi un JWT ne doit jamais contenir de mot de passe ni rien d'autre de secret.

import { SignJWT } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const token = await new SignJWT({ name: 'Ada', role: 'editor' })
    .setProtectedHeader({ alg: 'HS256' })
    .sign(secret);

const [header, payload, signature] = token.split('.');

console.log(Buffer.from(header, 'base64url').toString());
console.log(Buffer.from(payload, 'base64url').toString());
console.log(signature.length);

Les deux premières lignes affichent {"alg":"HS256"} et {"name":"Ada","role":"editor"}, lisibles par quiconque détient le token. La signature (43 caractères pour HS256) est ce qui empêche de le modifier : remplacez editor par admin et la signature ne correspond plus.

Expiration et vérification qui échoue

setExpirationTime('15m') écrit un claim exp, et jwtVerify rejette un token qui l'a dépassé. Chaque rejet est une erreur avec un code, ce qui permet de distinguer un token expiré d'un token falsifié.

import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const expired = await new SignJWT({ sub: 'user-42' })
    .setProtectedHeader({ alg: 'HS256' })
    .setExpirationTime(1700000000) // a moment in 2023, long past
    .sign(secret);

try {
    await jwtVerify(expired, secret);
} catch (err) {
    console.log(err.code);
}

const forged = expired.slice(0, -2) + 'xx';
try {
    await jwtVerify(forged, secret);
} catch (err) {
    console.log(err.code);
}

La première vérification échoue avec ERR_JWT_EXPIRED et la seconde, dont la signature a été modifiée, avec ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Pour votre API, les deux veulent dire la même chose (répondre 401), mais journaliser le code aide au débogage.

Protéger une route Express avec un Bearer token

Le client se connecte une fois, garde le token et l'envoie dans l'en-tête Authorization sous la forme Bearer <token>. Un middleware le vérifie et place le payload dans req.user pour la route.

// GET /me
import express from 'express';
import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const app = express();
app.use(express.json());

app.post('/login', async (req, res) => {
    const { username, password } = req.body ?? {};
    // A real app looks the user up and checks a hashed password
    if (username !== 'ada' || password !== 'lovelace') {
        return res.status(401).json({ error: 'Wrong username or password' });
    }
    const token = await new SignJWT({ name: username })
        .setProtectedHeader({ alg: 'HS256' })
        .setSubject('user-1')
        .setExpirationTime('15m')
        .sign(secret);
    res.json({ token });
});

async function requireAuth(req, res, next) {
    const header = req.get('authorization') ?? '';
    const token = header.startsWith('Bearer ') ? header.slice(7) : null;
    if (!token) return res.status(401).json({ error: 'Missing token' });
    try {
        const { payload } = await jwtVerify(token, secret);
        req.user = payload;
        next();
    } catch {
        res.status(401).json({ error: 'Invalid or expired token' });
    }
}

app.get('/me', requireAuth, (req, res) => {
    res.json({ id: req.user.sub, name: req.user.name });
});

app.listen(3000);

La première requête, GET /me sans token, reçoit 401 et Missing token. Envoyez POST /login avec le corps {"username": "ada", "password": "lovelace"}, copiez le token de la réponse, puis renvoyez GET /me avec l'en-tête Authorization: Bearer <token> : la réponse est {"id":"user-1","name":"ada"}.

Le package jsonwebtoken

jsonwebtoken (npm install jsonwebtoken) est l'autre choix courant. Ses fonctions sign et verify sont synchrones (avec des callbacks optionnels) au lieu de renvoyer des promesses :

const jwt = require('jsonwebtoken');

const token = jwt.sign({ role: 'admin' }, process.env.JWT_SECRET, {
    subject: 'user-42',
    expiresIn: '1h',
});

const payload = jwt.verify(token, process.env.JWT_SECRET); // throws if invalid

Utilisez jose pour du nouveau code : il n'a aucune dépendance et tourne aussi dans les edge runtimes et les navigateurs. Les tokens des deux bibliothèques sont des JWT standard, donc l'une peut vérifier ce que l'autre a signé.

Erreurs fréquentes

Utiliser decode au lieu de verify. jwt.decode et decodeJwt lisent le payload sans vérifier la signature, donc un token falsifié passe. Ne faites confiance qu'à ce que renvoie verify.

Un secret court ou commité. Un secret HS256 devinable permet à un attaquant de signer ses propres tokens. Utilisez au moins 32 octets aléatoires, lisez-le depuis process.env et ne le commitez jamais.

Des tokens qui n'expirent jamais. Sans exp, un token qui fuite fonctionne pour toujours. Définissez toujours une expiration.