JWT et Passport - Sécuriser une API Node.js sans session

Dans une API Node.js, l’authentification par jeton fonctionne bien quand on veut rester stateless, vérifier l’identité rapidement et garder le backend simple à faire évoluer. Avec Passport et sa stratégie JWT, je peux protéger des routes Express sans session serveur, tout en gardant un point central pour valider l’émetteur, l’audience, l’expiration et l’utilisateur concerné. Ici, je vais aller au concret: comment ça marche, comment le configurer proprement et quels pièges j’évite en production.

Ce qu’il faut comprendre avant d’utiliser JWT avec Passport

Je vois souvent deux confusions: on mélange le transport du jeton et sa validation, puis on imagine que Passport “fait tout”. En réalité, Passport est un middleware d’authentification pour Node.js, et sa responsabilité reste très ciblée: il examine la requête, vérifie le jeton avec la stratégie choisie, puis expose l’utilisateur authentifié via req.user si tout est cohérent.

La stratégie JWT, elle, est adaptée aux APIs REST, aux services backend découplés et aux architectures où l’on ne veut pas maintenir une session serveur pour chaque client. C’est précisément ce que la documentation de Passport met en avant: un mécanisme léger pour authentifier des requêtes, sans imposer de logique de session. À l’inverse, si ton application repose sur un navigateur avec des interactions très longues et un besoin fort de déconnexion immédiate, je ne partirais pas sur du tout-JWT sans réfléchir à la révocation et au renouvellement.

Le bon réflexe consiste à voir le JWT comme une preuve temporaire, pas comme une vérité absolue. Le jeton transporte des claims, c’est-à-dire des assertions sur le sujet, l’émetteur, l’audience ou la date d’expiration. Ce n’est qu’après vérification que ces informations deviennent exploitables côté backend. Cette nuance change tout dans la manière de concevoir l’API.

Une fois ce cadre posé, le vrai sujet devient le trajet exact d’une requête et le point où la stratégie intervient.

Comment la vérification se déroule réellement sur une requête

Dans un flux classique, je conseille de penser l’authentification comme une chaîne très simple, mais très stricte. Passport ne “devine” rien: il reçoit une requête, extrait le jeton, vérifie sa signature et ses paramètres, puis appelle la fonction de vérification avec le contenu décodé.

1. Le client envoie la requête avec le jeton, le plus souvent dans l’en-tête Authorization.
2. La stratégie récupère le jeton via jwtFromRequest.
3. Passport vérifie la signature avec la clé ou le secret configuré.
4. Les contrôles de base passent ensuite sur l’émetteur, l’audience, l’expiration et les autres options choisies.
5. La fonction verify récupère le payload et décide si un utilisateur correspond réellement à ce jeton.
6. Si tout est bon, Passport attache l’utilisateur à req.user.

Le point important ici, c’est l’extracteur. Passport-jwt ne te force pas à utiliser un emplacement unique: il peut lire l’en-tête, le body, l’URL, ou un extrait personnalisé. En pratique, je préfère que l’extraction soit simple et visible. Plus elle est “magique”, plus les bugs de production sont difficiles à diagnostiquer.

Ce fonctionnement explique aussi pourquoi je sépare toujours le problème de transport du problème de validation. Le prochain bloc montre la configuration minimale que j’utilise le plus souvent avec Express.

Configurer une stratégie propre dans Express

Voici la structure que je préfère quand je pars sur une API propre et lisible. L’idée est de rester explicite sur le transport du jeton, l’algorithme autorisé et la logique de recherche utilisateur.

const express = require('express');
const passport = require('passport');
const { Strategy: JwtStrategy, ExtractJwt } = require('passport-jwt');

const opts = {
  jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
  secretOrKey: process.env.JWT_PUBLIC_KEY,
  issuer: 'https://api.example.fr',
  audience: 'web-app',
  algorithms: ['RS256']
};

passport.use(new JwtStrategy(opts, async (payload, done) => {
  try {
    const user = await Users.findById(payload.sub);

    if (!user) {
      return done(null, false);
    }

    return done(null, user);
  } catch (err) {
    return done(err, false);
  }
}));

const app = express();

app.use(passport.initialize());

app.get('/me',
  passport.authenticate('jwt', { session: false }),
  (req, res) => {
    res.json({
      id: req.user.id,
      email: req.user.email
    });
  }
);

app.listen(3000);

Je recommande cette base pour trois raisons. D’abord, elle rend visible le fait que l’API est sans session: { session: false } évite de laisser Passport basculer vers un mécanisme inutile ici. Ensuite, elle force la validation sur des paramètres concrets comme issuer, audience et algorithms. Enfin, elle sépare bien la vérification cryptographique de la récupération métier de l’utilisateur.

Si tu gères plusieurs environnements, plusieurs applications ou une rotation de clés plus sérieuse, secretOrKeyProvider devient vite plus propre qu’un secret figé. Je l’utilise dès que le contexte n’est plus mono-tenant ou quand la clé dépend de l’émetteur. Pour une API simple, un secret unique peut suffire; pour une architecture plus riche, la gestion de clés mérite d’être pensée dès le départ.

Dans la plupart des backends sérieux, je préfère RS256. Ce n’est pas “magiquement plus sûr” à lui seul, mais il simplifie la séparation des responsabilités: un service signe, les autres vérifient. Cette séparation devient très utile dès qu’on multiplie les applications ou qu’on veut éviter de distribuer un secret sensible partout.

Une fois la stratégie en place, le vrai choix opérationnel reste encore celui du transport du jeton. C’est là que beaucoup de projets perdent en clarté.

Choisir le bon emplacement pour le jeton

Le transport du token n’est pas un détail esthétique. Il influence la sécurité, les contraintes front-end et la manière dont tu gères le renouvellement. Je préfère comparer les options avant de trancher, parce que le mauvais choix crée souvent des correctifs pénibles plus tard.

Pour une API pure, l’en-tête Authorization: Bearer reste mon premier choix. Il est lisible, il s’intègre bien avec les clients HTTP et il colle à l’idée même d’une API sans état. Pour une application web servie dans le navigateur, le cookie HttpOnly peut être pertinent, mais seulement si tu assumes le travail de protection CSRF derrière. Sinon, tu gagnes une chose et tu en perds deux.

Passport-jwt permet aussi d’écrire un extracteur personnalisé. C’est utile si tu dois lire un cookie de session, migrer un ancien système ou gérer plusieurs emplacements de jeton pendant une transition. Je l’emploie rarement comme solution finale, mais souvent comme pont technique. Voici un exemple simple si tu veux lire un cookie nommé jwt:

const cookieExtractor = (req) => {
  if (!req || !req.cookies) {
    return null;
  }

  return req.cookies.jwt || null;
};

opts.jwtFromRequest = cookieExtractor;

Ce genre d’extracteur est pratique, mais il faut garder la discipline de ne pas multiplier les sources sans raison. Plus il y a de chemins d’entrée, plus il devient difficile de savoir d’où vient vraiment l’authentification. C’est justement pour cela que la validation doit rester stricte et prévisible.

Renforcer la validation au lieu de faire confiance au payload

Le RFC 7519 définit le format JWT, mais le RFC 8725 rappelle surtout comment l’utiliser sans se tirer une balle dans le pied. En pratique, je retiens une règle simple: ne jamais considérer un payload comme fiable avant la vérification complète. Le contenu décodé n’est qu’un objet JSON signé ou chiffré; il n’a de valeur qu’après passage du contrôle serveur.

Le contrôle d’exp est non négociable. Un jeton expiré ne devrait pas être accepté, et le RFC précise même qu’un léger décalage d’horloge peut exister, généralement de quelques minutes. Je m’autorise cette petite tolérance seulement si le contexte l’impose, par exemple entre plusieurs systèmes dont les horloges ne sont pas parfaitement alignées.

Je valide aussi systématiquement l’audience et l’issuer dès qu’un même fournisseur peut émettre des jetons pour plusieurs applications. C’est là que se jouent beaucoup d’attaques de substitution. Un token valable pour un service ne doit pas pouvoir être recyclé ailleurs sans rejet. Le RFC 8725 insiste précisément sur ce point: il faut des règles de validation distinctes selon le type de jeton et son contexte.

Enfin, je limite les algorithmes autorisés. Ne laisse jamais le serveur “choisir” librement un algorithme parce qu’il figure dans l’en-tête du jeton. Tu dois savoir à l’avance ce que tu acceptes. Si ton système émet en RS256, alors je n’accepte que RS256. C’est banal, mais c’est une barrière qui évite des erreurs lourdes.

Avec cette validation serrée, on réduit déjà beaucoup le risque. Il reste pourtant les faux pas classiques qui, eux, reviennent dans presque tous les audits.

Les erreurs qui reviennent en production

Je rencontre toujours les mêmes erreurs quand une équipe met JWT et Passport en place trop vite. La bonne nouvelle, c’est qu’elles sont simples à corriger si on les identifie tôt.

Pour les statuts HTTP, ma règle est simple: 401 quand le jeton manque, est invalide ou expiré; 403 quand l’utilisateur est bien authentifié mais n’a pas le droit d’accéder à la ressource. Cette distinction aide autant le front-end que le support technique, parce qu’elle rend le comportement de l’API lisible.

J’ajoute aussi un point souvent oublié: la journalisation. Je ne logue jamais un JWT brut, surtout pas dans des traces partagées. Un jeton contient des informations sensibles, parfois des identifiants ou des indices d’architecture. En cas de débogage, je préfère tracer un identifiant corrélé ou le résultat de la vérification, pas le jeton lui-même.

À ce stade, la structure est saine. Reste à assembler une version que je garderais vraiment en production, sans sur-ingénierie mais sans angle mort non plus.

La configuration que je garderais en production

• Je transporte le jeton dans l’en-tête Authorization: Bearer pour les APIs REST et les clients mobiles.
• Je limite la durée de vie de l’access token, en général sur une fenêtre courte, puis je renouvelle via un mécanisme dédié.
• Je valide toujours issuer, audience, algorithms et exp.
• Je sépare clairement la vérification du jeton et la récupération de l’utilisateur en base.
• Je passe à secretOrKeyProvider dès que la rotation de clés ou le multi-tenant devient réel.
• Je teste explicitement les cas d’erreur: expiré, mauvais émetteur, mauvaise audience, signature invalide et absence de jeton.

Dans une application web orientée navigateur, je peux accepter une logique de cookie HttpOnly, mais seulement si la protection CSRF est traitée avec sérieux. Dans une API pure, je reste plus sobre: un Bearer token, une vérification courte, des réponses HTTP nettes et un renouvellement séparé. C’est moins glamour qu’un montage “tout-en-un”, mais c’est la version qui m’épargne le plus d’incidents.

Au fond, Passport ne fait pas la partie la plus difficile: il fournit une couche propre pour brancher l’authentification sur tes routes. Le reste dépend de la qualité de la stratégie que tu poses autour. Si tu veux un backend maintenable, pense d’abord au flux, au transport et aux règles de validation; le code vient ensuite, et il devient immédiatement plus lisible.