better-auth/melhores-práticas-de-autenticação-de-dois-fatores

O que melhores-práticas-de-autenticação-de-dois-fatores faz?

Configure aplicativos autenticadores TOTP, envie códigos OTP por e-mail/SMS, gerencie códigos de backup, lidere dispositivos confiáveis e implemente fluxos de login com 2FA usando o plugin twoFactor do Better Auth. Use quando os usuários precisarem de MFA, autenticação multifatorial, configuração de autenticador ou segurança de login com Better Auth.

Introdução

Autenticação de dois fatores (2FA) adiciona uma camada extra de segurança além da senha. Com o plugin twoFactor do Better Auth, você pode oferecer:

• TOTP: Códigos temporários gerados por aplicativos como Google Authenticator ou Authy.
• OTP por e-mail: Códigos de uso único enviados para o e-mail do usuário.
• OTP por SMS: Códigos de uso único enviados para o telefone do usuário.
• Códigos de backup: Códigos de recuperação para acesso quando o 2FA não está disponível.
• Dispositivos confiáveis: Permite que o usuário marque um dispositivo como confiável por um período, evitando nova autenticação 2FA.

Configuração

Instalação

npm install @better-auth/two-factor

Adicionar o plugin ao Better Auth

import { betterAuth } from "better-auth";
import { twoFactor } from "@better-auth/two-factor";

export const auth = betterAuth({
  plugins: [
    twoFactor({
      // Configurações opcionais
      otpOptions: {
        // Tempo de expiração do OTP (padrão: 5 minutos)
        expiresIn: 300000, // 5 minutos em milissegundos
      },
      backupCodeOptions: {
        // Número de códigos de backup a gerar (padrão: 10)
        count: 10,
      },
      trustDeviceOptions: {
        // Tempo de confiança do dispositivo (padrão: 30 dias)
        expiresIn: 2592000000, // 30 dias em milissegundos
      },
    }),
  ],
});

Fluxos de Autenticação

Ativação do 2FA

Para ativar o 2FA para um usuário, você precisa chamar a função apropriada do lado do cliente ou servidor.

Exemplo com TOTP:

import { totp } from "@better-auth/two-factor/client";

// Solicitar ativação
const { totpUri, secret } = await totp.generate({
  userId: "id_do_usuario",
});

// O usuário escaneia o QR code ou insere a chave manualmente
// Em seguida, verifique o código gerado
await totp.verify({
  userId: "id_do_usuario",
  code: "123456", // Código do autenticador
});

Verificação de Login com 2FA

Após o login com senha, se o usuário tiver 2FA ativado, você deve solicitar o segundo fator.

Exemplo com TOTP:

import { signIn } from "better-auth/client";

// Primeiro passo: login com senha
const result = await signIn.email({
  email: "[email protected]",
  password: "senha123",
});

if (result.twoFactorRequired) {
  // Segundo passo: verificar 2FA
  const verifyResult = await totp.verify({
    userId: result.user.id,
    code: "123456",
  });
}

Códigos de Backup

Gere e gerencie códigos de backup para o usuário.

import { backupCodes } from "@better-auth/two-factor/client";

// Gerar novos códigos de backup
const codes = await backupCodes.generate({
  userId: "id_do_usuario",
});

// Verificar um código de backup
await backupCodes.use({
  userId: "id_do_usuario",
  code: "ABCD-EFGH",
});

Dispositivos Confiáveis

Marque um dispositivo como confiável para evitar solicitações frequentes de 2FA.

import { trustDevice } from "@better-auth/two-factor/client";

// Durante a verificação 2FA, confiar no dispositivo
await totp.verify({
  userId: "id_do_usuario",
  code: "123456",
  trustDevice: true, // Marca o dispositivo como confiável
});

Melhores Práticas

1. Ofereça múltiplos métodos: Permita que os usuários escolham entre TOTP, e-mail ou SMS.
2. Códigos de backup obrigatórios: Sempre gere códigos de backup ao ativar o 2FA.
3. Dispositivos confiáveis: Implemente a opção de confiar no dispositivo para melhorar a experiência do usuário.
4. Expiração de sessão: Revogue tokens de confiança quando a sessão expirar.
5. Logs de auditoria: Registre eventos de ativação/desativação de 2FA e tentativas de verificação.
6. Tratamento de erros: Lide com códigos inválidos, expirados ou tentativas excessivas.

Exemplo Completo de Fluxo de Login

async function loginWith2FA(email: string, password: string) {
  const result = await signIn.email({ email, password });

  if (result.error) {
    throw new Error(result.error.message);
  }

  if (result.twoFactorRequired) {
    // Solicitar código ao usuário
    const code = await promptUserFor2FACode();

    const verifyResult = await totp.verify({
      userId: result.user.id,
      code,
      trustDevice: true,
    });

    if (verifyResult.error) {
      throw new Error("Código 2FA inválido");
    }

    return verifyResult.session;
  }

  return result.session;
}

Suporte e Contribuição

Para mais detalhes, consulte a documentação oficial do Better Auth ou abra uma issue no repositório GitHub.