Pular para o conteúdo
XOOPS 2.7 Docs

ADR-006: Implementação de Autenticação de Dois Fatores

Status

Seção intitulada “Status”

Proposto

Contexto

Seção intitulada “Contexto”

XOOPS precisa de segurança aprimorada para autenticação de usuário. Autenticação de dois fatores (2FA) fornece uma camada adicional de segurança além de senhas, protegendo contas mesmo se senhas forem comprometidas.

Considerações principais:

  • Compatibilidade com autenticação existente
  • Suportar múltiplos métodos 2FA
  • Experiência de usuário durante configuração e login
  • Mecanismos de recuperação para dispositivos perdidos
  • Integração com sistema de permissão existente

Decisão

Seção intitulada “Decisão”

Implementaremos TOTP (Senha Única Baseada em Tempo) como método 2FA primário com suporte a códigos de backup.

Abordagem de Implementação

Seção intitulada “Abordagem de Implementação”
sequenceDiagram
    participant U as Usuário
    participant X as XOOPS
    participant T as Biblioteca TOTP
    participant D as Banco de Dados


    U->>X: Login com senha
    X->>D: Validar senha
    D-->>X: Senha válida
    X->>D: Verificar 2FA habilitado
    D-->>X: 2FA necessário
    X->>U: Requisitar código 2FA
    U->>X: Enviar código TOTP
    X->>T: Validar código
    T-->>X: Código válido
    X->>U: Login bem sucedido

Esquema de Banco de Dados

Seção intitulada “Esquema de Banco de Dados”
CREATE TABLE `{PREFIX}_users_2fa` (
    `user_id` INT(11) NOT NULL,
    `secret` VARCHAR(32) NOT NULL,
    `enabled` TINYINT(1) DEFAULT 0,
    `backup_codes` TEXT,
    `last_used` INT(11),
    `created` INT(11) NOT NULL,
    PRIMARY KEY (`user_id`),
    FOREIGN KEY (`user_id`) REFERENCES `{PREFIX}_users`(`uid`)
);

Interface de Serviço

Seção intitulada “Interface de Serviço”
interface TwoFactorAuthInterface
{
    public function enable(int $userId): TwoFactorSetup;
    public function disable(int $userId): void;
    public function verify(int $userId, string $code): bool;
    public function generateBackupCodes(int $userId): array;
    public function isEnabled(int $userId): bool;
}

Integração de Middleware

Seção intitulada “Integração de Middleware”
class TwoFactorMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        $session = $request->getAttribute('session');


        if ($session->has('pending_2fa_user_id')) {
            // Usuário precisa completar 2FA
            if ($this->isVerificationRequest($request)) {
                return $handler->handle($request);
            }
            return new RedirectResponse('/2fa/verify');
        }


        return $handler->handle($request);
    }
}

Consequências

Seção intitulada “Consequências”

Positivo

Seção intitulada “Positivo”
  • Segurança de conta significativamente melhorada
  • Compatibilidade TOTP padrão da indústria (Google Authenticator, Authy, etc.)
  • Códigos de backup previnem bloqueio de conta
  • Opcional por usuário - não força adoção
  • Middleware PSR-15 permite integração limpa

Negativo

Seção intitulada “Negativo”
  • Etapa de login adicional impacta experiência de usuário
  • Usuários devem gerenciar apps autenticador
  • Dispositivos perdidos requerem processo de recuperação
  • Armazenamento e queries de banco de dados adicionais
  • Requer dependência de biblioteca criptográfica

Caminho de Migração

Seção intitulada “Caminho de Migração”
  1. Adicionar tabela de banco de dados para dados 2FA
  2. Implementar serviço TOTP com dependência de biblioteca
  3. Adicionar middleware à cadeia de autenticação
  4. Criar UI de configuração e verificação
  5. Opção de admin para exigir 2FA para grupos específicos

Alternativas Consideradas

Seção intitulada “Alternativas Consideradas”

OTP Baseado em SMS

Seção intitulada “OTP Baseado em SMS”

Rejeitado devido a:

  • Vulnerabilidades de SIM swapping
  • Custo de gateway SMS
  • Complexidade de verificação de número de telefone
  • Preocupações de privacidade

Chaves de Segurança de Hardware (WebAuthn)

Seção intitulada “Chaves de Segurança de Hardware (WebAuthn)”

Adiado para ADR futuro:

  • Implementação mais complexa
  • Suporte de navegador historicamente limitado
  • Custo de usuário mais alto
  • Pode ser adicionado junto com TOTP depois

OTP Baseado em Email

Seção intitulada “OTP Baseado em Email”

Rejeitado devido a:

  • Compromisso de conta de email derrota propósito
  • Atrasos de entrega impactam UX
  • Problemas de filtro de spam

Referências

Seção intitulada “Referências”