better-auth/bonnes-pratiques-authentification-deux-facteurs

Que fait bonnes-pratiques-authentification-deux-facteurs ?

Configurez les applications d'authentification TOTP, envoyez des codes OTP par e-mail/SMS, gérez les codes de secours, gérez les appareils de confiance et implémentez des flux de connexion 2FA avec le plugin twoFactor de Better Auth. À utiliser lorsque les utilisateurs ont besoin d'MFA, d'authentification multifacteur, de configuration d'authentificateur ou de sécurité de connexion avec Better Auth.

Aperçu

Better Auth simplifie l'ajout de l'authentification à deux facteurs (2FA) à vos applications. Le plugin twoFactor gère les méthodes basées sur le temps (TOTP) et les codes à usage unique (OTP) via e-mail ou SMS. Cette compétence décrit les meilleures pratiques pour configurer, personnaliser et sécuriser votre implémentation 2FA avec Better Auth.

Fonctionnalités clés

• TOTP (Time-based One-Time Password) : Demandez aux utilisateurs de scanner un code QR avec n'importe quelle application d'authentification (Google Authenticator, Authy, etc.).
• OTP par e-mail : Envoyez un code à usage unique à l'adresse e-mail vérifiée de l'utilisateur.
• OTP par SMS : Envoyez un code à usage unique au numéro de téléphone vérifié de l'utilisateur (nécessite un service SMS externe).
• Codes de secours : Générez et validez des codes de secours à usage unique pour l'accès en cas d'urgence.
• Appareils de confiance : Permettez aux utilisateurs de marquer un appareil comme "de confiance" pour ignorer la 2FA lors des connexions futures.
• Connexion 2FA : Interceptez les connexions réussies et forcez l'utilisateur à fournir un code 2FA avant de terminer la session.

Plugins Better Auth associés

Plugin	Rôle
multi-session	Gère plusieurs sessions simultanées par utilisateur
admin	Accord des rôles admin et fonctionnalités de gestion
organization	Prise en charge de la gestion multi-tenant et des rôles au sein de l'organisation
phone-number	Vérifie les numéros de téléphone via OTP SMS

Configuration de base

Installez le plugin twoFactor dans votre configuration Better Auth :

import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    twoFactor(),
  ],
});

Personnalisation

Activation de l'authentification par application (TOTP)

Utilisez l'API côté serveur totp pour activer TOTP :

const { data } = await auth.api.totp({
  headers: {
    Authorization: `Bearer $token}`,
  },
});

Le client reçoit un qrCodeURI pour l'affichage du code QR et un secret pour l'encodage manuel.

Envoi d'OTP par e-mail

Configurez un adaptateur de messagerie Better Auth (ou un transport) puis appelez sendVerificationOtp :

await auth.api.sendVerificationOtp({
  headers: {
    Authorization: `Bearer $token}`,
  },
  body: {
    email: "[email protected]",
    type: "two-factor",
  },
});

Envoi d'OTP par SMS

Configurez le plugin phone-number, puis utilisez sendVerificationOtp avec un type "two-factor" et un numéro de téléphone vérifié.

Gestion des codes de secours

Générez des codes de secours via l'API serveur :

const { data } = await auth.api.totp({
  headers: {
    Authorization: `Bearer $token}`,
  },
  body: {
    generateBackupCodes: true,
  },
});

Conservez-les de manière sécurisée (par exemple, dans un gestionnaire de mots de passe). Validez-les comme n'importe quel autre code 2FA.

Gestion des appareils de confiance

Better Auth prend en charge les jetons d'appareil de confiance. Vous pouvez marquer un appareil comme "de confiance" dans le flux de vérification 2FA :

const { data } = await auth.api.twoFactor({
  headers: {
    Authorization: `Bearer $token}`,
  },
  body: {
    code: "123456",
    trustDevice: true,
  },
});

Les futurs flux de connexion depuis cet appareil ignoreront la 2FA.

Flux complet de connexion 2FA

1. L'utilisateur se connecte avec son e-mail et mot de passe.
2. Better Auth retourne un jeton de session partiel ou une erreur indiquant que la 2FA est requise.
3. Le frontend détecte l'indicateur twoFactorRequired et affiche la vue 2FA.
4. L'utilisateur saisit le code de son application d'authentification, le code OTP reçu par e-mail/SMS, ou un code de secours.
5. Le frontend envoie le code au point de terminaison twoFactor.
6. En cas de succès, l'utilisateur est authentifié et redirigé.

Meilleures pratiques

• Validez les codes côté serveur : Ne faites jamais confiance aux codes 2FA provenant du client seul. Utilisez toujours les API de validation de Better Auth.
• Offrez toujours des codes de secours : Les utilisateurs perdent souvent leur application d'authentification. Proposez un téléchargement unique ou un affichage à l'écran après l'activation de la 2FA.
• Ajoutez une option "Se souvenir de cet appareil" : Améliorez l'expérience utilisateur en permettant aux appareils de confiance de sauter la 2FA.
• Limitez les tentatives : Implémentez des limites de taux (rate limiting) sur les points de terminaison 2FA pour prévenir les attaques par force brute.
• Tests : Testez les flux avec des applications d'authentification réelles, des e-mails et des SMS. Vérifiez la validation des codes de secours.
• Sécurité : Stockez les codes de secours de manière sécurisée (par exemple, hachés avec un sel). N'envoyez jamais les codes 2FA dans les réponses d'API.

Dépannage

• Le code QR ne s'affiche pas : Assurez-vous que le composant QR code du frontend peut décoder qrCodeURI. Utilisez une bibliothèque comme qrcode.
• Erreur TwoFactorRequired après la configuration : Vérifiez que le plugin twoFactor est correctement installé et que le middleware de session le reconnaît.
• Les codes OTP SMS ne sont pas envoyés : Vérifiez que le plugin phone-number est configuré et que le fournisseur SMS est fonctionnel.
• Le jeton de session est invalide : Vérifiez que le jeton Bearer utilisé est bien un jeton de session valide (non un jeton de rafraîchissement).

Références

• Documentation Better Auth twoFactor
• Plugin Better Auth phone-number