email-and-password-best-practices

Démarrage rapide

1. Activer email/mot de passe : emailAndPassword: { enabled: true }
2. Configurer emailVerification.sendVerificationEmail
3. Ajouter sendResetPassword pour les flux de réinitialisation de mot de passe
4. Exécuter npx @better-auth/cli@latest migrate
5. Vérifier : effectuer une inscription et confirmer que l'email de vérification est déclenché

Configuration de la vérification d'email

Configurez emailVerification.sendVerificationEmail pour vérifier les adresses email des utilisateurs.

import { betterAuth } from "better-auth";
import { sendEmail } from "./email"; // your email sending function

export const auth = betterAuth({
  emailVerification: {
    sendVerificationEmail: async ({ user, url, token }, request) => {
      await sendEmail({
        to: user.email,
        subject: "Verify your email address",
        text: `Click the link to verify your email: ${url}`,
      });
    },
  },
});

Note : Le paramètre url contient le lien de vérification complet. Le token est disponible si vous avez besoin de construire une URL de vérification personnalisée.

Exiger la vérification d'email

Pour une sécurité renforcée, activez emailAndPassword.requireEmailVerification pour bloquer la connexion jusqu'à ce que l'utilisateur vérifie son email. Quand cette option est activée, les utilisateurs non vérifiés recevront un nouvel email de vérification à chaque tentative de connexion.

export const auth = betterAuth({
  emailAndPassword: {
    requireEmailVerification: true,
  },
});

Note : Cela nécessite que sendVerificationEmail soit configuré et s'applique uniquement aux connexions par email/mot de passe.

Validation côté client

Implémentez une validation côté client pour un retour immédiat à l'utilisateur et une réduction de la charge serveur.

URLs de callback

Utilisez toujours des URLs absolues (incluant l'origine) pour les URLs de callback dans les requêtes d'inscription et de connexion. Cela empêche Better Auth d'avoir à déduire l'origine, ce qui peut causer des problèmes quand votre backend et frontend sont sur des domaines différents.

const { data, error } = await authClient.signUp.email({
  callbackURL: "https://example.com/callback", // absolute URL with origin
});

Flux de réinitialisation de mot de passe

Fournissez sendResetPassword dans la configuration email et mot de passe pour activer les réinitialisations de mot de passe.

import { betterAuth } from "better-auth";
import { sendEmail } from "./email"; // your email sending function

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    // Custom email sending function to send reset-password email
    sendResetPassword: async ({ user, url, token }, request) => {
      void sendEmail({
        to: user.email,
        subject: "Reset your password",
        text: `Click the link to reset your password: ${url}`,
      });
    },
    // Optional event hook
    onPasswordReset: async ({ user }, request) => {
      // your logic here
      console.log(`Password for user ${user.email} has been reset.`);
    },
  },
});

Considérations de sécurité

Protections intégrées : envoi d'email en arrière-plan (prévention des timing attacks), opérations factices sur les requêtes invalides, messages de réponse constants indépendamment de l'existence de l'utilisateur.

Sur les plateformes serverless, configurez un gestionnaire de tâches en arrière-plan :

export const auth = betterAuth({
  advanced: {
    backgroundTasks: {
      handler: (promise) => {
        // Use platform-specific methods like waitUntil
        waitUntil(promise);
      },
    },
  },
});

Sécurité des tokens

Les tokens expirent après 1 heure par défaut. Configurez avec resetPasswordTokenExpiresIn (en secondes) :

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    resetPasswordTokenExpiresIn: 60 * 30, // 30 minutes
  },
});

Les tokens sont à usage unique — supprimés immédiatement après une réinitialisation réussie.

Révocation de session

Activez revokeSessionsOnPasswordReset pour invalider toutes les sessions existantes lors d'une réinitialisation de mot de passe :

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    revokeSessionsOnPasswordReset: true,
  },
});

Exigences de mot de passe

Limites de longueur de mot de passe (configurables) :

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    minPasswordLength: 12,
    maxPasswordLength: 256,
  },
});

Envoyer la réinitialisation de mot de passe

Appelez requestPasswordReset pour envoyer le lien de réinitialisation. Déclenche la fonction sendResetPassword depuis votre configuration.

const data = await auth.api.requestPasswordReset({
  body: {
    email: "john.doe@example.com", // required
    redirectTo: "https://example.com/reset-password",
  },
});

Ou avec authClient :

const { data, error } = await authClient.requestPasswordReset({
  email: "john.doe@example.com", // required
  redirectTo: "https://example.com/reset-password",
});

Note : Bien que l'email soit obligatoire, nous recommandons aussi de configurer redirectTo pour une meilleure expérience utilisateur.

Hachage de mot de passe

Par défaut : scrypt (natif Node.js, aucune dépendance externe).

Algorithme de hachage personnalisé

Pour utiliser Argon2id ou un autre algorithme, fournissez des fonctions hash et verify personnalisées :

import { betterAuth } from "better-auth";
import { hash, verify, type Options } from "@node-rs/argon2";

const argon2Options: Options = {
  memoryCost: 65536, // 64 MiB
  timeCost: 3, // 3 iterations
  parallelism: 4, // 4 parallel lanes
  outputLen: 32, // 32 byte output
  algorithm: 2, // Argon2id variant
};

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    password: {
      hash: (password) => hash(password, argon2Options),
      verify: ({ password, hash: storedHash }) =>
        verify(storedHash, password, argon2Options),
    },
  },
});

Note : Si vous changez d'algorithme de hachage sur un système existant, les utilisateurs dont les mots de passe ont été hachés avec l'ancien algorithme ne pourront pas se connecter. Planifiez une stratégie de migration si nécessaire.