{"id":156,"date":"2026-06-14T20:33:57","date_gmt":"2026-06-14T20:33:57","guid":{"rendered":"https:\/\/shattered.io\/fr\/2026\/06\/14\/authentification-totp-nodejs\/"},"modified":"2026-06-14T20:35:30","modified_gmt":"2026-06-14T20:35:30","slug":"authentification-totp-nodejs","status":"publish","type":"post","link":"https:\/\/shattered.io\/fr\/2026\/06\/14\/authentification-totp-nodejs\/","title":{"rendered":"Authentification TOTP en Node.js : 2FA en 12 \u00e9tapes [2026]"},"content":{"rendered":"\n

L’authentification TOTP<\/strong> (Time-based One-Time Password) est devenue le second facteur de r\u00e9f\u00e9rence pour prot\u00e9ger les comptes en ligne. Contrairement au SMS, vuln\u00e9rable au SIM swapping, un code TOTP est calcul\u00e9 hors ligne sur l’appareil de l’utilisateur \u00e0 partir d’un secret partag\u00e9 et de l’heure courante. Dans ce tutoriel publi\u00e9 le 14 juin 2026, vous allez construire, en 12 \u00e9tapes et environ 40 minutes, un syst\u00e8me de double authentification (2FA) complet en Node.js : g\u00e9n\u00e9ration du secret, QR code de provisionnement, v\u00e9rification avec tol\u00e9rance d’horloge, chiffrement du secret au repos, codes de r\u00e9cup\u00e9ration, limitation des tentatives et protection contre le rejeu.<\/p>\n\n\n\n

Le code est compatible avec Google Authenticator, Microsoft Authenticator, Authy, Ente Auth, 2FAS et tout client conforme \u00e0 la RFC 6238<\/a>. Vous repartirez avec un projet fonctionnel structur\u00e9 autour d’une API Express, pr\u00eat \u00e0 int\u00e9grer dans une application r\u00e9elle.<\/p>\n\n\n\n

Qu’est-ce que le TOTP et pourquoi l’adopter en 2026<\/h2>\n\n\n\n

Le TOTP<\/strong> est une extension de l’algorithme HOTP d\u00e9crit par la RFC 4226<\/a> (2005). HOTP g\u00e9n\u00e8re un mot de passe \u00e0 usage unique \u00e0 partir d’un secret et d’un compteur incr\u00e9mental. La RFC 6238, publi\u00e9e en 2011, remplace ce compteur par une valeur d\u00e9riv\u00e9e du temps : le syst\u00e8me prend l’heure Unix courante, la divise par un pas de temps (30 secondes par d\u00e9faut) et utilise le r\u00e9sultat comme compteur. Toutes les 30 secondes, un nouveau code \u00e0 6 chiffres appara\u00eet, identique sur le serveur et sur l’application mobile tant que leurs horloges sont synchronis\u00e9es.<\/p>\n\n\n\n

Cette approche \u00e9limine la d\u00e9pendance au r\u00e9seau. Aucun SMS n’est envoy\u00e9, aucun appel d’API n’est n\u00e9cessaire au moment de la validation. Le secret n’est \u00e9chang\u00e9 qu’une seule fois, lors de l’enr\u00f4lement, via un QR code. Ensuite, le t\u00e9l\u00e9phone et le serveur calculent le m\u00eame code chacun de leur c\u00f4t\u00e9. En 2026, l’ANSSI et l’ENISA recommandent toujours la 2FA bas\u00e9e sur une application plut\u00f4t que par SMS, jug\u00e9e beaucoup plus r\u00e9sistante \u00e0 l’interception.<\/p>\n\n\n\n

Le TOTP pr\u00e9sente trois avantages d\u00e9cisifs pour un d\u00e9veloppeur. Premi\u00e8rement, il est gratuit : aucun co\u00fbt par message, contrairement aux passerelles SMS. Deuxi\u00e8mement, il fonctionne hors ligne, m\u00eame dans un avion ou une zone blanche. Troisi\u00e8mement, il s’appuie sur des primitives cryptographiques standardis\u00e9es (HMAC-SHA1, et optionnellement SHA-256 ou SHA-512) impl\u00e9ment\u00e9es dans la biblioth\u00e8que standard crypto<\/code> de Node.js. Le seul pr\u00e9requis c\u00f4t\u00e9 utilisateur est une application d’authentification, d\u00e9sormais install\u00e9e par d\u00e9faut sur la plupart des smartphones.<\/p>\n\n\n\n

Pour replacer le TOTP dans le paysage de l’authentification forte, comparez-le aux autres m\u00e9thodes courantes. Les passkeys (cl\u00e9s d’acc\u00e8s FIDO2) offrent une s\u00e9curit\u00e9 sup\u00e9rieure contre le hame\u00e7onnage, mais leur d\u00e9ploiement reste partiel et la 2FA TOTP demeure le filet de s\u00e9curit\u00e9 le plus universel.<\/p>\n\n\n\n

M\u00e9thode 2FA<\/th>R\u00e9sistance au hame\u00e7onnage<\/th>Hors ligne<\/th>Co\u00fbt<\/th>Adoption<\/th><\/tr><\/thead>
SMS<\/td>Faible (SIM swap)<\/td>Non<\/td>Payant par message<\/td>Tr\u00e8s large<\/td><\/tr>
TOTP (application)<\/td>Moyenne<\/td>Oui<\/td>Gratuit<\/td>Large<\/td><\/tr>
Notification push<\/td>Moyenne (fatigue MFA)<\/td>Non<\/td>Variable<\/td>Croissante<\/td><\/tr>
Cl\u00e9 mat\u00e9rielle FIDO2<\/td>\u00c9lev\u00e9e<\/td>Oui<\/td>Co\u00fbt mat\u00e9riel<\/td>En hausse<\/td><\/tr>
Passkey<\/td>\u00c9lev\u00e9e<\/td>Oui<\/td>Gratuit<\/td>\u00c9mergente<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Pr\u00e9requis et versions logicielles<\/h2>\n\n\n\n

Avant de commencer, installez les versions suivantes. Ce tutoriel a \u00e9t\u00e9 test\u00e9 avec Node.js 24 (ligne LTS \u00ab Krypton \u00bb) et la derni\u00e8re version stable de chaque d\u00e9pendance disponible en juin 2026. V\u00e9rifiez votre version de Node avec node --version<\/code>. Si vous utilisez une version ant\u00e9rieure \u00e0 Node 20, mettez-la \u00e0 jour : l’API node:crypto<\/code> et la prise en charge native d’ESM y sont plus stables.<\/p>\n\n\n\n

Outil \/ paquet<\/th>Version utilis\u00e9e<\/th>R\u00f4le dans le projet<\/th><\/tr><\/thead>
Node.js<\/td>24.x LTS (Krypton)<\/td>Environnement d’ex\u00e9cution<\/td><\/tr>
otplib<\/td>13.4.1<\/td>G\u00e9n\u00e9ration et v\u00e9rification TOTP<\/td><\/tr>
qrcode<\/td>1.5.4<\/td>Cr\u00e9ation du QR code de provisionnement<\/td><\/tr>
express<\/td>5.2.1<\/td>Serveur d’API HTTP<\/td><\/tr>
express-rate-limit<\/td>8.5.2<\/td>Limitation des tentatives de v\u00e9rification<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Un mot sur le choix des biblioth\u00e8ques. La biblioth\u00e8que otplib<\/strong> (version 13.4.1, publi\u00e9e fin mai 2026) est activement maintenue et constitue aujourd’hui la r\u00e9f\u00e9rence pour le TOTP en Node.js. Vous croiserez souvent speakeasy<\/code> dans d’anciens tutoriels, mais son dernier paquet publi\u00e9 remonte \u00e0 2016 (version 2.0.0). Nous l’\u00e9vitons ici au profit d’otplib, plus \u00e0 jour et mieux typ\u00e9. C\u00f4t\u00e9 QR code, qrcode<\/code> 1.5.4 g\u00e9n\u00e8re un data URI directement int\u00e9grable dans une balise image c\u00f4t\u00e9 client.<\/p>\n\n\n\n

Vous aurez aussi besoin de notions de base en JavaScript asynchrone (async\/await<\/code>), d’un terminal et d’un \u00e9diteur de code. Aucune base de donn\u00e9es n’est requise pour suivre le tutoriel : nous simulons le stockage avec un objet en m\u00e9moire, puis nous expliquons comment passer en production. Si l’authentification par jetons vous est inconnue, lisez d’abord notre guide sur l’authentification JWT en Node.js<\/a>, car nous prot\u00e9gerons la route d’activation 2FA avec une session authentifi\u00e9e.<\/p>\n\n\n\n

Comment fonctionne l’algorithme TOTP en d\u00e9tail<\/h2>\n\n\n\n

Comprendre l’algorithme avant de l’impl\u00e9menter \u00e9vite la majorit\u00e9 des bugs. Le calcul d’un code TOTP se d\u00e9roule en quatre temps. D’abord, le serveur et le client partagent un secret al\u00e9atoire d’au moins 128 bits (160 bits recommand\u00e9s par la RFC 4226), encod\u00e9 en Base32 selon la RFC 4648 pour \u00eatre lisible par les applications d’authentification. Ensuite, on calcule le compteur temporel : T \u00e9gale l’heure Unix actuelle moins T0, divis\u00e9 par le pas de temps, T0 valant 0 et le pas valant 30 secondes.<\/p>\n\n\n\n

Troisi\u00e8me \u00e9tape, on applique HMAC-SHA1 au compteur en utilisant le secret comme cl\u00e9. Le r\u00e9sultat est un condens\u00e9 de 20 octets. Quatri\u00e8me \u00e9tape, la \u00ab troncature dynamique \u00bb extrait 4 octets du condens\u00e9 \u00e0 une position d\u00e9termin\u00e9e par son dernier quartet, convertit ces octets en entier, puis prend le modulo 10 puissance 6 pour obtenir un code \u00e0 6 chiffres. Cet encha\u00eenement est enti\u00e8rement d\u00e9terministe : deux horloges synchronis\u00e9es produisent le m\u00eame code.<\/p>\n\n\n\n

Le param\u00e8tre crucial pour la fiabilit\u00e9 est la fen\u00eatre de tol\u00e9rance<\/strong>. Les horloges d\u00e9rivent. Si le t\u00e9l\u00e9phone de l’utilisateur avance de 40 secondes, son code correspond au pas de temps suivant. Pour absorber ce d\u00e9calage, le serveur v\u00e9rifie non seulement le pas de temps courant, mais aussi un ou deux pas avant et apr\u00e8s. Une fen\u00eatre de plus ou moins 1 pas (90 secondes de tol\u00e9rance totale) est un bon compromis entre confort et s\u00e9curit\u00e9. Une fen\u00eatre trop large augmente la surface d’attaque par force brute.<\/p>\n\n\n\n

Voici les param\u00e8tres par d\u00e9faut interop\u00e9rables, ceux que comprennent toutes les applications d’authentification grand public. Conservez ces valeurs sauf raison pr\u00e9cise, car certaines applications (notamment d’anciennes versions de Google Authenticator) ignorent les param\u00e8tres non standard et retombent silencieusement sur SHA-1, 6 chiffres et 30 secondes.<\/p>\n\n\n\n

Param\u00e8tre<\/th>Valeur par d\u00e9faut<\/th>Recommandation<\/th><\/tr><\/thead>
Algorithme de hachage<\/td>SHA-1<\/td>SHA-1 pour la compatibilit\u00e9 maximale<\/td><\/tr>
Nombre de chiffres<\/td>6<\/td>6 (8 possible mais moins compatible)<\/td><\/tr>
Pas de temps (period)<\/td>30 secondes<\/td>30 secondes<\/td><\/tr>
Longueur du secret<\/td>Variable<\/td>160 bits (20 octets)<\/td><\/tr>
Fen\u00eatre de tol\u00e9rance<\/td>0<\/td>\u00b11 pas (window=1)<\/td><\/tr>
Encodage du secret<\/td>Base32 (RFC 4648)<\/td>Base32<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Note importante sur SHA-1 : son usage dans HMAC reste s\u00fbr pour le TOTP. Les attaques par collision qui ont condamn\u00e9 SHA-1 pour les signatures, comme l’a montr\u00e9 l’attaque SHAttered<\/a>, ne s’appliquent pas \u00e0 HMAC, qui repose sur la r\u00e9sistance \u00e0 la pr\u00e9image et sur un secret. Vous pouvez donc garder SHA-1 sans crainte pour la 2FA, ce qui maximise la compatibilit\u00e9.<\/p>\n\n\n\n

\u00c9tape 1 et 2 : initialiser le projet et installer les d\u00e9pendances<\/h2>\n\n\n\n

Cr\u00e9ez un dossier de projet, initialisez un package.json<\/code> et activez les modules ES. Nous utilisons la syntaxe d’import moderne, prise en charge nativement par Node 24. Le champ \"type\": \"module\"<\/code> indique \u00e0 Node de traiter les fichiers .js<\/code> comme des modules ES.<\/p>\n\n\n\n

mkdir totp-2fa-nodejs && cd totp-2fa-nodejs\nnpm init -y\nnpm pkg set type=\"module\"\nnpm install otplib@13.4.1 qrcode@1.5.4 express@5.2.1 express-rate-limit@8.5.2 dotenv<\/code><\/pre>\n\n\n\n
Apr\u00e8s l’installation, v\u00e9rifiez que les paquets sont bien pr\u00e9sents. La commande ci-dessous liste les d\u00e9pendances de premier niveau avec leur version exacte. Conservez cette sortie : en cas de bug, comparer les versions install\u00e9es aux versions attendues est le premier r\u00e9flexe de d\u00e9pannage.<\/p>\n\n\n\n
npm ls --depth=0\n\n# Sortie attendue :\n# totp-2fa-nodejs@1.0.0\n# \u251c\u2500\u2500 dotenv@latest\n# \u251c\u2500\u2500 express@5.2.1\n# \u251c\u2500\u2500 express-rate-limit@8.5.2\n# \u251c\u2500\u2500 otplib@13.4.1\n# \u2514\u2500\u2500 qrcode@1.5.4<\/code><\/pre>\n\n\n\n
Cr\u00e9ez ensuite la structure de fichiers du projet. Nous s\u00e9parons la logique TOTP (le c\u0153ur cryptographique) de la couche HTTP (les routes Express) et du stockage. Cette s\u00e9paration facilite les tests et le remplacement ult\u00e9rieur du stockage en m\u00e9moire par une vraie base de donn\u00e9es.<\/p>\n\n\n\n
totp-2fa-nodejs\/\n\u251c\u2500\u2500 package.json\n\u251c\u2500\u2500 src\/\n\u2502   \u251c\u2500\u2500 totp.js        # g\u00e9n\u00e9ration et v\u00e9rification TOTP\n\u2502   \u251c\u2500\u2500 crypto.js      # chiffrement du secret au repos\n\u2502   \u251c\u2500\u2500 recovery.js    # codes de r\u00e9cup\u00e9ration\n\u2502   \u251c\u2500\u2500 limites.js     # limitation et verrouillage\n\u2502   \u251c\u2500\u2500 store.js       # stockage (en m\u00e9moire pour la d\u00e9mo)\n\u2502   \u2514\u2500\u2500 server.js      # API Express\n\u2514\u2500\u2500 .env               # cl\u00e9 de chiffrement (jamais commit\u00e9e)<\/code><\/pre>\n\n\n\n
\u00c9tape 3 : g\u00e9n\u00e9rer un secret TOTP robuste<\/h2>\n\n\n\n
Le secret est la pierre angulaire de la s\u00e9curit\u00e9. Il doit \u00eatre g\u00e9n\u00e9r\u00e9 avec un g\u00e9n\u00e9rateur cryptographiquement s\u00fbr, jamais avec Math.random()<\/code>. otplib expose authenticator.generateSecret()<\/code> qui produit un secret Base32 de longueur appropri\u00e9e. Par d\u00e9faut, otplib g\u00e9n\u00e8re un secret suffisant ; vous pouvez augmenter sa longueur pour atteindre les 160 bits recommand\u00e9s.<\/p>\n\n\n\n
Cr\u00e9ez le fichier src\/totp.js<\/code>. Nous configurons explicitement otplib avec les param\u00e8tres standard et une fen\u00eatre de tol\u00e9rance de 1 pas, ce qui autorise un d\u00e9calage d’horloge de plus ou moins 30 secondes.<\/p>\n\n\n\n
\/\/ src\/totp.js\nimport { authenticator } from 'otplib';\nimport QRCode from 'qrcode';\n\n\/\/ Configuration conforme aux param\u00e8tres interop\u00e9rables.\nauthenticator.options = {\n  digits: 6,        \/\/ code \u00e0 6 chiffres\n  step: 30,         \/\/ pas de temps de 30 secondes\n  window: 1,        \/\/ tol\u00e9rance de +\/- 1 pas (90 s au total)\n  algorithm: 'sha1' \/\/ compatibilit\u00e9 maximale\n};\n\nconst EMETTEUR = 'MonApp';\n\n\/\/ G\u00e9n\u00e8re un nouveau secret Base32 pour un utilisateur.\nexport function genererSecret() {\n  return authenticator.generateSecret(20); \/\/ 20 octets = 160 bits\n}<\/code><\/pre>\n\n\n\n
Testez la g\u00e9n\u00e9ration depuis un fichier temporaire ou le REPL Node. Chaque appel produit un secret diff\u00e9rent, une cha\u00eene Base32 d’environ 32 caract\u00e8res compos\u00e9e de lettres majuscules et de chiffres de 2 \u00e0 7. Ce secret ne doit jamais transiter en clair en dehors du QR code initial et ne doit jamais \u00eatre journalis\u00e9.<\/p>\n\n\n\n
node --input-type=module -e \"import('.\/src\/totp.js').then(m => console.log(m.genererSecret()))\"\n\n# Sortie (exemple) :\n# KRSXG5CTMVRXEZLUKNSWG4TFOQ2GS4ZA<\/code><\/pre>\n\n\n\n
\u00c9tape 4 : cr\u00e9er l’URI otpauth:\/\/ et le QR code<\/h2>\n\n\n\n
Pour enr\u00f4ler un utilisateur, l’application d’authentification doit importer le secret. La m\u00e9thode standard est l’URI de provisionnement otpauth:\/\/<\/code>, encod\u00e9e dans un QR code que l’utilisateur scanne. Cette URI suit un format pr\u00e9cis d\u00e9fini par la documentation Key URI de Google, repris par tous les clients. Le tableau suivant d\u00e9taille chaque champ.<\/p>\n\n\n\n
Champ<\/th>Exemple<\/th>Description<\/th><\/tr><\/thead>
type<\/td>totp<\/td>Type d’OTP (totp ou hotp)<\/td><\/tr>
label<\/td>MonApp:alice@exemple.fr<\/td>\u00c9metteur et identifiant du compte<\/td><\/tr>
secret<\/td>KRSXG5CT…<\/td>Le secret Base32<\/td><\/tr>
issuer<\/td>MonApp<\/td>Nom du service affich\u00e9 dans l’application<\/td><\/tr>
algorithm<\/td>SHA1<\/td>Algorithme de hachage<\/td><\/tr>
digits<\/td>6<\/td>Longueur du code<\/td><\/tr>
period<\/td>30<\/td>Pas de temps en secondes<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
otplib construit cette URI avec authenticator.keyuri(compte, emetteur, secret)<\/code>. Le paquet qrcode<\/code> la transforme ensuite en image. Ajoutez ces fonctions \u00e0 src\/totp.js<\/code>. La fonction genererQrCode<\/code> retourne un data URI PNG en base64, directement utilisable dans l’attribut src<\/code> d’une balise image c\u00f4t\u00e9 navigateur.<\/p>\n\n\n\n
\/\/ src\/totp.js (suite)\n\n\/\/ Construit l'URI otpauth:\/\/ standard.\nexport function genererUri(compte, secret) {\n  return authenticator.keyuri(compte, EMETTEUR, secret);\n}\n\n\/\/ Transforme l'URI en data URI PNG pour affichage.\nexport async function genererQrCode(compte, secret) {\n  const uri = genererUri(compte, secret);\n  return QRCode.toDataURL(uri, { width: 240, margin: 2 });\n}<\/code><\/pre>\n\n\n\n
L’URI g\u00e9n\u00e9r\u00e9e ressemble \u00e0 otpauth:\/\/totp\/MonApp:alice@exemple.fr?secret=KRSXG5CT...&issuer=MonApp&algorithm=SHA1&digits=6&period=30<\/code>. Proposez toujours une saisie manuelle du secret en compl\u00e9ment du QR code : certains utilisateurs scannent depuis le m\u00eame appareil que celui qui affiche le code et ne peuvent pas utiliser l’appareil photo.<\/p>\n\n\n\n
\u00c9tape 5 : v\u00e9rifier un code TOTP avec tol\u00e9rance d’horloge<\/h2>\n\n\n\n
La v\u00e9rification est le moment critique. otplib fournit authenticator.verify({ token, secret })<\/code> qui renvoie un bool\u00e9en. Gr\u00e2ce \u00e0 l’option window: 1<\/code> d\u00e9finie plus haut, la fonction accepte le code du pas courant, du pas pr\u00e9c\u00e9dent et du pas suivant. Important : otplib effectue une comparaison \u00e0 temps constant en interne pour \u00e9viter les attaques temporelles, vous n’avez pas \u00e0 g\u00e9rer cela vous-m\u00eame.<\/p>\n\n\n\n
\/\/ src\/totp.js (suite)\n\n\/\/ V\u00e9rifie un code saisi par l'utilisateur.\n\/\/ Retourne le d\u00e9calage (delta) du pas valid\u00e9, ou null si invalide.\nexport function verifierCode(token, secret) {\n  \/\/ Nettoyage : retirer les espaces que certaines applications ajoutent.\n  const propre = String(token).replace(\/\\s+\/g, '');\n  if (!\/^\\d{6}$\/.test(propre)) return null;\n\n  const valide = authenticator.verify({ token: propre, secret });\n  if (!valide) return null;\n\n  \/\/ checkDelta renvoie le d\u00e9calage (-1, 0, +1) du pas accept\u00e9.\n  return authenticator.checkDelta({ token: propre, secret });\n}<\/code><\/pre>\n\n\n\n
Pourquoi retourner le delta plut\u00f4t qu’un simple bool\u00e9en ? Parce qu’il sert \u00e0 la protection contre le rejeu (\u00e9tape 9). En m\u00e9morisant le dernier pas de temps accept\u00e9, on peut refuser un code d\u00e9j\u00e0 utilis\u00e9 m\u00eame s’il est encore valide dans la fen\u00eatre. Voici un test rapide qui g\u00e9n\u00e8re un code \u00e0 la vol\u00e9e et le v\u00e9rifie imm\u00e9diatement.<\/p>\n\n\n\n
\/\/ test-verif.js\nimport { authenticator } from 'otplib';\nimport { genererSecret, verifierCode } from '.\/src\/totp.js';\n\nconst secret = genererSecret();\nconst code = authenticator.generate(secret); \/\/ simule l'application mobile\nconsole.log('Code courant :', code);\nconsole.log('Resultat     :', verifierCode(code, secret));   \/\/ 0 = pas courant\nconsole.log('Faux code    :', verifierCode('000000', secret)); \/\/ null\n\n\/\/ Sortie (exemple) :\n\/\/ Code courant : 482913\n\/\/ Resultat     : 0\n\/\/ Faux code    : null<\/code><\/pre>\n\n\n\n
\u00c9tape 6 : chiffrer le secret au repos avec AES-256-GCM<\/h2>\n\n\n\n
Stocker le secret TOTP en clair dans votre base de donn\u00e9es est une faute grave. Un attaquant qui acc\u00e8de \u00e0 la base pourrait g\u00e9n\u00e9rer des codes valides pour tous les comptes. La RFC 6238 demande explicitement de prot\u00e9ger les cl\u00e9s contre tout acc\u00e8s non autoris\u00e9. La parade : chiffrer chaque secret avec AES-256-GCM avant le stockage, \u00e0 l’aide d’une cl\u00e9 ma\u00eetre conserv\u00e9e hors de la base (variable d’environnement, gestionnaire de secrets ou HSM).<\/p>\n\n\n\n
Cr\u00e9ez src\/crypto.js<\/code>. Nous utilisons le module natif node:crypto<\/code>, sans d\u00e9pendance externe. AES-256-GCM fournit \u00e0 la fois confidentialit\u00e9 et authenticit\u00e9 : le tag d’authentification d\u00e9tecte toute alt\u00e9ration du chiffr\u00e9. Chaque chiffrement utilise un vecteur d’initialisation (IV) al\u00e9atoire de 12 octets, jamais r\u00e9utilis\u00e9.<\/p>\n\n\n\n
\/\/ src\/crypto.js\nimport { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';\n\n\/\/ Cl\u00e9 ma\u00eetre de 32 octets (256 bits), en hexad\u00e9cimal dans l'environnement.\nconst CLE = Buffer.from(process.env.TOTP_ENC_KEY || '', 'hex');\nif (CLE.length !== 32) {\n  throw new Error('TOTP_ENC_KEY doit faire 32 octets (64 caracteres hex).');\n}\n\nexport function chiffrer(texte) {\n  const iv = randomBytes(12);\n  const cipher = createCipheriv('aes-256-gcm', CLE, iv);\n  const chiffre = Buffer.concat([cipher.update(texte, 'utf8'), cipher.final()]);\n  const tag = cipher.getAuthTag();\n  \/\/ Format stock\u00e9 : iv:tag:chiffre, le tout en base64.\n  return [iv, tag, chiffre].map(b => b.toString('base64')).join(':');\n}\n\nexport function dechiffrer(charge) {\n  const [iv, tag, chiffre] = charge.split(':').map(s => Buffer.from(s, 'base64'));\n  const decipher = createDecipheriv('aes-256-gcm', CLE, iv);\n  decipher.setAuthTag(tag);\n  return Buffer.concat([decipher.update(chiffre), decipher.final()]).toString('utf8');\n}<\/code><\/pre>\n\n\n\n
G\u00e9n\u00e9rez une cl\u00e9 ma\u00eetre robuste et placez-la dans un fichier .env<\/code> exclu du d\u00e9p\u00f4t Git. Ne r\u00e9utilisez jamais cette cl\u00e9 entre environnements de d\u00e9veloppement et de production. Pour approfondir l’usage du module crypto, consultez notre guide complet sur le HMAC-SHA256 en Node.js<\/a>, qui partage les m\u00eames primitives.<\/p>\n\n\n\n
# G\u00e9n\u00e9rer une cl\u00e9 de 256 bits et l'\u00e9crire dans .env\nnode -e \"console.log('TOTP_ENC_KEY=' + require('crypto').randomBytes(32).toString('hex'))\" > .env\n\n# V\u00e9rifier (64 caract\u00e8res hexad\u00e9cimaux apr\u00e8s le signe =)\ncat .env<\/code><\/pre>\n\n\n\n
\u00c9tape 7 : g\u00e9n\u00e9rer des codes de r\u00e9cup\u00e9ration<\/h2>\n\n\n\n
Que se passe-t-il si l’utilisateur perd son t\u00e9l\u00e9phone ? Sans plan de secours, il est d\u00e9finitivement bloqu\u00e9. La solution standard est de fournir, au moment de l’activation, une liste de codes de r\u00e9cup\u00e9ration \u00e0 usage unique. L’utilisateur les imprime ou les stocke dans son gestionnaire de mots de passe. Chaque code ne fonctionne qu’une fois et contourne le TOTP.<\/p>\n\n\n\n
Point essentiel : ne stockez jamais ces codes en clair. Traitez-les comme des mots de passe et hachez-les. Comme ils sont \u00e0 forte entropie (g\u00e9n\u00e9r\u00e9s al\u00e9atoirement), un hachage SHA-256 suffit ; inutile d’utiliser un algorithme lent comme Argon2, r\u00e9serv\u00e9 aux mots de passe humains \u00e0 faible entropie. Cr\u00e9ez src\/recovery.js<\/code>.<\/p>\n\n\n\n
\/\/ src\/recovery.js\nimport { randomBytes, createHash, timingSafeEqual } from 'node:crypto';\n\n\/\/ G\u00e9n\u00e8re 10 codes lisibles de type XXXX-XXXX.\nexport function genererCodesRecuperation(nombre = 10) {\n  const codes = [];\n  for (let i = 0; i < nombre; i++) {\n    const brut = randomBytes(4).toString('hex').toUpperCase(); \/\/ 8 caract\u00e8res\n    codes.push(brut.slice(0, 4) + '-' + brut.slice(4));\n  }\n  return codes;\n}\n\nexport function hacherCode(code) {\n  const normalise = code.replace(\/-\/g, '').toUpperCase();\n  return createHash('sha256').update(normalise).digest('hex');\n}\n\n\/\/ Compare en temps constant et renvoie le hachage trouv\u00e9 ou null.\nexport function verifierCodeRecuperation(saisie, hashesStockes) {\n  const hashSaisie = Buffer.from(hacherCode(saisie), 'hex');\n  return hashesStockes.find(h => {\n    const ref = Buffer.from(h, 'hex');\n    return ref.length === hashSaisie.length && timingSafeEqual(ref, hashSaisie);\n  }) ?? null;\n}<\/code><\/pre>\n\n\n\n
Lorsqu’un code de r\u00e9cup\u00e9ration est utilis\u00e9 avec succ\u00e8s, supprimez son hachage de la liste stock\u00e9e pour emp\u00eacher toute r\u00e9utilisation. Pr\u00e9venez l’utilisateur quand il ne lui reste plus que deux ou trois codes, afin qu’il en r\u00e9g\u00e9n\u00e8re un nouveau lot. Cette logique de secrets \u00e0 usage unique compl\u00e8te bien notre tutoriel sur le hachage de mots de passe avec bcrypt<\/a>.<\/p>\n\n\n\n
\u00c9tape 8 : limiter les tentatives de v\u00e9rification<\/h2>\n\n\n\n
Un code \u00e0 6 chiffres n’offre qu’un million de combinaisons. Avec la fen\u00eatre de tol\u00e9rance, un attaquant disposant d’un d\u00e9bit illimit\u00e9 finirait par deviner un code valide. La RFC 4226 insiste sur la n\u00e9cessit\u00e9 de limiter les tentatives. Nous appliquons une double protection : un verrouillage par compte apr\u00e8s plusieurs \u00e9checs, et une limitation globale par adresse IP avec express-rate-limit<\/code>. Cr\u00e9ez src\/limites.js<\/code>.<\/p>\n\n\n\n
\/\/ src\/limites.js\nimport rateLimit from 'express-rate-limit';\n\n\/\/ Limiteur d\u00e9di\u00e9 \u00e0 la route de v\u00e9rification 2FA.\nexport const limiteurVerif = rateLimit({\n  windowMs: 15 * 60 * 1000, \/\/ fen\u00eatre de 15 minutes\n  max: 5,                   \/\/ 5 tentatives par IP et par fen\u00eatre\n  standardHeaders: true,\n  legacyHeaders: false,\n  message: { erreur: 'Trop de tentatives. R\u00e9essayez dans 15 minutes.' }\n});\n\nconst MAX_ECHECS = 5;\n\nexport function compteVerrouille(u) {\n  return Boolean(u.verrouJusqua) && Date.now() < u.verrouJusqua;\n}\n\nexport function enregistrerEchec(u) {\n  u.echecs = (u.echecs || 0) + 1;\n  if (u.echecs >= MAX_ECHECS) {\n    u.verrouJusqua = Date.now() + 15 * 60 * 1000;\n    u.echecs = 0;\n  }\n}<\/code><\/pre>\n\n\n\n
La limitation par IP ne suffit pas seule : un attaquant peut faire tourner les adresses. Le compteur d’\u00e9checs par compte ferme cette br\u00e8che. Apr\u00e8s 5 \u00e9checs cons\u00e9cutifs, le compte est verrouill\u00e9 pendant 15 minutes ; notifiez alors l’utilisateur par email. R\u00e9initialisez le compteur \u00e0 chaque succ\u00e8s. Ce m\u00e9canisme, combin\u00e9 \u00e0 la fen\u00eatre \u00e9troite, rend la force brute en ligne irr\u00e9aliste.<\/p>\n\n\n\n
\u00c9tape 9 : prot\u00e9ger contre le rejeu de code<\/h2>\n\n\n\n
Un code TOTP reste valide pendant 30 \u00e0 90 secondes selon la fen\u00eatre. Sans protection, un attaquant qui intercepte un code (par hame\u00e7onnage en temps r\u00e9el, par exemple) peut le rejouer tant qu’il n’a pas expir\u00e9. La RFC 6238 recommande d’accepter chaque code au plus une fois. La technique : stocker le dernier pas de temps valid\u00e9 par utilisateur et refuser tout code dont le pas est inf\u00e9rieur ou \u00e9gal au dernier accept\u00e9.<\/p>\n\n\n\n
\/\/ src\/totp.js (suite) : v\u00e9rification sans rejeu\nexport function verifierSansRejeu(token, secret, utilisateur) {\n  const delta = verifierCode(token, secret);\n  if (delta === null) return false;\n\n  \/\/ Pas de temps absolu du code accept\u00e9.\n  const pasActuel = Math.floor(Date.now() \/ 1000 \/ 30) + delta;\n\n  if (utilisateur.dernierPas && pasActuel <= utilisateur.dernierPas) {\n    return false; \/\/ code d\u00e9j\u00e0 utilis\u00e9 : rejet\n  }\n  utilisateur.dernierPas = pasActuel;\n  return true;\n}<\/code><\/pre>\n\n\n\n
Cette protection est particuli\u00e8rement importante face aux kits de hame\u00e7onnage modernes, qui relaient les identifiants en temps r\u00e9el. Elle ne remplace pas une vraie r\u00e9sistance au hame\u00e7onnage (que seules les passkeys offrent), mais elle ferme une fen\u00eatre d’attaque concr\u00e8te. Pour comprendre comment ces attaques fonctionnent, lisez notre dossier sur les attaques par hame\u00e7onnage<\/a>.<\/p>\n\n\n\n
\u00c9tape 10 \u00e0 12 : assembler l’API Express compl\u00e8te<\/h2>\n\n\n\n
Nous r\u00e9unissons maintenant tous les modules dans un serveur Express. Trois routes structurent le parcours : \/2fa\/setup<\/code> g\u00e9n\u00e8re le secret et le QR code, \/2fa\/activate<\/code> confirme l’activation apr\u00e8s un premier code valide, et \/2fa\/verify<\/code> valide un code lors de la connexion. En production, ces routes seraient prot\u00e9g\u00e9es par une session authentifi\u00e9e (mot de passe d\u00e9j\u00e0 v\u00e9rifi\u00e9). Pour la d\u00e9monstration, nous simulons un seul utilisateur.<\/p>\n\n\n\n
\/\/ src\/store.js : stockage en m\u00e9moire pour la d\u00e9mo.\n\/\/ En production, remplacez par PostgreSQL, MySQL ou autre.\nconst utilisateurs = new Map();\n\nexport function getUtilisateur(id) {\n  if (!utilisateurs.has(id)) {\n    utilisateurs.set(id, {\n      id, secretChiffre: null, actif: false,\n      codesRecup: [], echecs: 0, dernierPas: 0\n    });\n  }\n  return utilisateurs.get(id);\n}<\/code><\/pre>\n\n\n\n
Voici le serveur complet. Notez l’ordre logique : on ne marque jamais la 2FA comme active tant que l’utilisateur n’a pas prouv\u00e9 qu’il peut g\u00e9n\u00e9rer un code valide. Cela \u00e9vite de verrouiller un utilisateur qui aurait mal scann\u00e9 le QR code.<\/p>\n\n\n\n
\/\/ src\/server.js\nimport 'dotenv\/config';\nimport express from 'express';\nimport { genererSecret, genererQrCode, verifierSansRejeu, verifierCode } from '.\/totp.js';\nimport { chiffrer, dechiffrer } from '.\/crypto.js';\nimport { genererCodesRecuperation, hacherCode } from '.\/recovery.js';\nimport { getUtilisateur } from '.\/store.js';\nimport { limiteurVerif, compteVerrouille, enregistrerEchec } from '.\/limites.js';\n\nconst app = express();\napp.use(express.json());\n\n\/\/ \u00c9tape 10 : initialiser l'enr\u00f4lement.\napp.post('\/2fa\/setup', async (req, res) => {\n  const u = getUtilisateur(req.body.userId || 'demo');\n  const secret = genererSecret();\n  u.secretChiffre = chiffrer(secret); \/\/ chiffr\u00e9 au repos\n  const qr = await genererQrCode(u.id + '@exemple.fr', secret);\n  res.json({ qrCode: qr, secretManuel: secret });\n});\n\n\/\/ \u00c9tape 11 : activer apr\u00e8s v\u00e9rification d'un premier code.\napp.post('\/2fa\/activate', (req, res) => {\n  const u = getUtilisateur(req.body.userId || 'demo');\n  if (!u.secretChiffre) return res.status(400).json({ erreur: 'Aucun enrolement.' });\n  const secret = dechiffrer(u.secretChiffre);\n  if (verifierCode(req.body.code, secret) === null) {\n    return res.status(400).json({ erreur: 'Code invalide.' });\n  }\n  const codes = genererCodesRecuperation();\n  u.codesRecup = codes.map(hacherCode);\n  u.actif = true;\n  res.json({ message: '2FA activ\u00e9e.', codesRecuperation: codes });\n});\n\n\/\/ \u00c9tape 12 : v\u00e9rifier lors de la connexion.\napp.post('\/2fa\/verify', limiteurVerif, (req, res) => {\n  const u = getUtilisateur(req.body.userId || 'demo');\n  if (!u.actif) return res.status(400).json({ erreur: '2FA non activ\u00e9e.' });\n  if (compteVerrouille(u)) return res.status(429).json({ erreur: 'Compte verrouill\u00e9.' });\n  const secret = dechiffrer(u.secretChiffre);\n  if (!verifierSansRejeu(req.body.code, secret, u)) {\n    enregistrerEchec(u);\n    return res.status(401).json({ erreur: 'Code incorrect.' });\n  }\n  u.echecs = 0;\n  res.json({ message: 'Authentification r\u00e9ussie.' });\n});\n\napp.listen(3000, () => console.log('Serveur 2FA sur http:\/\/localhost:3000'));<\/code><\/pre>\n\n\n\n
Lancez le serveur avec node src\/server.js<\/code>, puis testez le parcours complet avec curl. La s\u00e9quence ci-dessous enr\u00f4le l’utilisateur, affiche le secret manuel (\u00e0 entrer dans votre application d’authentification), puis active et v\u00e9rifie la 2FA. Remplacez 482913 par le code r\u00e9el affich\u00e9 dans l’application.<\/p>\n\n\n\n
# 1. Enr\u00f4lement : r\u00e9cup\u00e8re le QR code et le secret manuel\ncurl -s -X POST http:\/\/localhost:3000\/2fa\/setup \\\n  -H 'Content-Type: application\/json' -d '{\"userId\":\"demo\"}'\n\n# 2. Activation avec le code affich\u00e9 dans l'application\ncurl -s -X POST http:\/\/localhost:3000\/2fa\/activate \\\n  -H 'Content-Type: application\/json' -d '{\"userId\":\"demo\",\"code\":\"482913\"}'\n\n# Sortie attendue :\n# {\"message\":\"2FA activ\u00e9e.\",\"codesRecuperation\":[\"A1B2-C3D4\", ...]}\n\n# 3. V\u00e9rification \u00e0 la connexion\ncurl -s -X POST http:\/\/localhost:3000\/2fa\/verify \\\n  -H 'Content-Type: application\/json' -d '{\"userId\":\"demo\",\"code\":\"715092\"}'\n\n# Sortie attendue :\n# {\"message\":\"Authentification r\u00e9ussie.\"}<\/code><\/pre>\n\n\n\n
Le projet complet : r\u00e9capitulatif des fichiers<\/h2>\n\n\n\n
Vous disposez d\u00e9sormais d’un syst\u00e8me 2FA fonctionnel et modulaire. Chaque responsabilit\u00e9 vit dans son fichier : g\u00e9n\u00e9ration et v\u00e9rification dans totp.js<\/code>, chiffrement dans crypto.js<\/code>, codes de secours dans recovery.js<\/code>, politique anti-abus dans limites.js<\/code>, stockage dans store.js<\/code> et exposition HTTP dans server.js<\/code>. Cette architecture en couches rend chaque morceau testable isol\u00e9ment et facilite l’audit de s\u00e9curit\u00e9.<\/p>\n\n\n\n
Pour passer en production, trois changements suffisent. Remplacez le Map<\/code> en m\u00e9moire de store.js<\/code> par des requ\u00eates vers votre base de donn\u00e9es, en stockant la colonne secretChiffre<\/code> (jamais le secret en clair), le tableau de hachages de codes de r\u00e9cup\u00e9ration et le champ dernierPas<\/code>. Liez ensuite chaque route \u00e0 votre middleware de session existant pour exiger une authentification primaire avant toute op\u00e9ration 2FA. Enfin, d\u00e9placez la cl\u00e9 TOTP_ENC_KEY<\/code> vers un gestionnaire de secrets (Vault, AWS KMS, ou \u00e9quivalent) plut\u00f4t qu’un simple fichier .env<\/code>.<\/p>\n\n\n\n
Le flux utilisateur final se r\u00e9sume ainsi : l’utilisateur active la 2FA depuis ses param\u00e8tres (setup puis activate), re\u00e7oit ses codes de r\u00e9cup\u00e9ration une seule fois, puis, \u00e0 chaque connexion ult\u00e9rieure, saisit le code de son application apr\u00e8s son mot de passe. Le serveur d\u00e9chiffre le secret, v\u00e9rifie le code avec tol\u00e9rance, bloque le rejeu, compte les \u00e9checs et journalise l’\u00e9v\u00e8nement. C’est exactement le comportement attendu d’une 2FA de niveau professionnel.<\/p>\n\n\n\n
Cinq erreurs fr\u00e9quentes \u00e0 \u00e9viter<\/h2>\n\n\n\n
Ces pi\u00e8ges reviennent dans presque toutes les impl\u00e9mentations TOTP de d\u00e9butants. Les conna\u00eetre \u00e0 l’avance vous fera gagner des heures de d\u00e9bogage.<\/p>\n\n\n\n