Quand on cherche comment les JWT s’intègrent à une authentification par e-mail et mot de passe, on retrouve toujours les mêmes questions : peut-on mettre des identifiants dans un token sans risque, faut-il encore utiliser HTTPS, qui est censé lire ce token et que se passe-t-il lorsqu’il expire ? Les réponses sont brèves ; bien les appliquer constitue l’essentiel du travail.
Ce tutoriel présente tout le cycle de vie d’un JSON Web Token dans une application avec e-mail et mot de passe, de la première inscription à la déconnexion, à l’aide de l’API REST AuthFlow™. Le format du token est défini dans RFC 7519 ; vous n’avez pas besoin de lire cette spécification pour suivre le guide.
Ce qu’est un JWT, et ce qu’il n’est pas
Un JWT est le résultat de l’authentification, pas son substitut. L’utilisateur prouve une fois son identité avec une adresse e-mail et un mot de passe. Le serveur renvoie alors un token signé indiquant : « cette personne s’est déjà authentifiée ». Chaque requête suivante transporte le token au lieu du mot de passe. C’est ce qui rend les JWT utiles dans les systèmes sans état et distribués : tout service disposant de la bonne clé peut vérifier le token sans nouvel aller-retour vers la base de données.
Un JWT comprend trois parties : un en-tête (type de token et algorithme de signature), un payload contenant des claims sur l’utilisateur et une signature. La signature prouve que le token n’a pas été modifié. Elle ne masque rien. Le payload est simplement encodé en base64, donc toute personne qui obtient le token peut le lire. Considérez un JWT comme détectable en cas de falsification, et non comme secret.
Ne mettez jamais le mot de passe dans le token
Une question fréquente chez les débutants est de savoir si les identifiants d’un utilisateur peuvent être stockés dans le JWT. En général, ce n’est pas nécessaire : le token est lui-même un identifiant à courte durée de vie produit lors de la connexion. Pour identifier l’utilisateur, placez un identifiant dans le claim sub, ainsi qu’un rôle ou un niveau d’accès si votre backend en a besoin. N’incluez ni mots de passe, ni secrets, ni aucune information que vous ne voudriez pas voir exposée dans un navigateur.
HTTPS est une question distincte et doit être utilisé partout. Il protège le trafic entre le client et le serveur, tandis que la signature du JWT protège l’intégrité du token. L’un ne remplace pas l’autre.
Étape 1 : gardez la clé API sur votre serveur
Chaque appel à AuthFlow est effectué pour le compte de votre organisation, à l’aide de la clé API du tableau de bord propriétaire. Cette clé doit rester sur une infrastructure que vous contrôlez, par exemple dans une variable d’environnement côté serveur comme AUTHFLOW_API_KEY. Ne l’intégrez jamais au JavaScript du navigateur. La solution sûre la plus simple est un petit backend (ou le proxy ExpressJS que nous publions) auquel votre frontend s’adresse et qui appelle /auth pour son compte.
Étape 2 : inscrivez-vous et connectez-vous
Avant une inscription ou une connexion, votre backend demande un token anti-abus à courte durée de vie via /auth/fooBar, pour l’adresse e-mail de l’utilisateur. Il expire au bout de 45 secondes : récupérez-le juste avant l’appel suivant et ne le réutilisez jamais. Appelez ensuite /auth/signUp avec la valeur foobar, votre api_key, l’email, un password conforme à la règle de complexité (8 à 32 caractères, avec une majuscule, une minuscule, un chiffre et un caractère spécial), le fullname et disclaimed défini à true. En cas de succès, l’inscription renvoie immédiatement un token de session ; une adresse e-mail et un rôle déjà associés renvoient le code 409.
La connexion fonctionne de la même façon avec /auth/login. En cas de succès, vous recevez le token de session : un JWT signé avec RS512. RS512 utilise une paire de clés. Les tokens sont signés avec une clé privée que vous ne voyez jamais et peuvent être vérifiés sans partager de secret.
Étape 3 : stockez le token avec précaution
Une fois le token reçu par votre backend, choisissez où le conserver. Les cookies HTTP-only sont recommandés, car les scripts de page ne peuvent pas les lire, ce qui limite les dégâts d’une faille de cross-site scripting. Quel que soit votre choix, conservez le token de session, pas un token temporaire, et veillez à ne jamais l’écrire dans les journaux.
Étape 4 : validez chaque route protégée
Avant de traiter une requête protégée, votre backend doit vérifier le token. Appelez /auth/validate avec sessionToken et l’email de l’utilisateur : un token valide est accepté, tandis qu’un token invalide ou expiré renvoie 401. Utilisez /auth/me pour obtenir le profil de l’utilisateur actuel. Cette vérification côté serveur doit être faite pour chaque requête protégée : un token signé que vous ne vérifiez jamais ne protège rien.
L’expiration fait partie du fonctionnement prévu. Quand un token expire, l’utilisateur se reconnecte au lieu que votre application tente de le prolonger discrètement. Veillez à gérer correctement la réponse 401 et à renvoyer l’utilisateur vers la page de connexion.
Étape 5 : gérez l’authentification à deux facteurs
Si un utilisateur a activé la 2FA, /auth/login ne renvoie pas de token de session. Il renvoie requires2FA et un tempToken. Votre application demande alors un second facteur et échange le tempToken via l’un des points de terminaison de vérification /auth/2fa (un code TOTP, un code de secours ou un OTP envoyé par e-mail). Seul cet échange produit le véritable token de session : veillez donc à stocker celui-ci, et jamais le tempToken.
Déboguez les tokens avec jwt.io
En cas de problème, le moyen le plus rapide de voir ce que contient réellement un token est jwt.io. Collez un token dans son débogueur ; il décode l’en-tête et le payload, ce qui vous permet de vérifier l’algorithme, le claim sub et l’heure d’expiration. Cela suffit généralement à repérer un token expiré, le mauvais utilisateur ou un tempToken stocké par erreur.
Tout ce qui précède implique une mise en garde : un token est un identifiant d’accès. Traitez tout token de production actif comme une information sensible, privilégiez les comptes de test pour le débogage et évitez de coller de vrais tokens dans un outil auquel vous ne faites pas confiance. Décoder un token ne revient pas à le vérifier. La vérification a toujours lieu sur votre serveur via /auth/validate.
Étape 6 : déconnectez-vous
Pour mettre fin à une session, appelez /auth/logout avec sessionToken et email, puis supprimez le token de l’endroit où vous l’avez stocké. Le changement de mot de passe fonctionne de façon similaire via /auth/changePassword. Consigner les événements d’authentification au fil du parcours vous fournit un historique utile en cas de problème.
Liste de contrôle pour l’intégration JWT
- La clé API reste uniquement dans la configuration côté serveur, jamais dans le code du navigateur.
- Chaque inscription et connexion est précédée d’un nouvel appel à
/auth/fooBar. - Aucun mot de passe ni secret ne figure dans le payload du token ; identifiez les utilisateurs avec
subet un rôle. - Le token de session est conservé dans un cookie HTTP-only ou un autre stockage contrôlé par le serveur.
- Chaque route protégée valide le token via
/auth/validateavant toute opération. - Les tokens expirés ou invalides (401) renvoient l’utilisateur vers la connexion.
- Le parcours 2FA stocke le token de session final, et non le
tempToken. - Tout le trafic utilise HTTPS et les tokens ne sont jamais écrits dans les journaux.
Voilà tout le processus : authentifiez-vous une fois, transportez un token signé, vérifiez-le sur le serveur et laissez-le expirer. Consultez le guide de démarrage pour la référence complète des points de terminaison, ou comparez l’approche des autres plateformes. Si un token semble incorrect, jwt.io vous montrera son contenu.