Two-Factor Authentication

Autor da integração: RCTI - Roda de Cuia
Categoria: Sistema · Identificador: twofactorauth · Versão: 1.0.0

O módulo adiciona autenticação de dois fatores por aplicativo autenticador às contas da equipe e dos clientes. Após a senha correta, uma conta com 2FA ativo precisa informar um código do aplicativo ou um código de recuperação.

Instalação e ativação

1. Mantenha os arquivos em modules/Sistema/Twofactorauth/, com manifest.json na raiz do módulo.
2. No painel administrativo, abra Extensões → Sistema.
3. Localize Two-Factor Authentication e clique em Ativar. A ativação cria a tabela twofactorauth e registra os eventos do módulo.
4. Abra Sistema → Two-Factor Authentication ou as configurações da extensão.
5. Configure primeiro sua própria conta e guarde os códigos de recuperação.

A pasta, o namespace RctiERP\Mod\Twofactorauth, as rotas e os métodos de API usam o mesmo identificador twofactorauth. O módulo utiliza os serviços de banco de dados e criptografia do RCTI ERP; não precisa de novas dependências Composer nem de serviços externos para gerar o QR Code.

Configurações

Configuração	Padrão	Comportamento
Exigir 2FA para a equipe	Ativada	A interface administrativa redireciona contas sem 2FA para a configuração. Contas da equipe não podem desativar o próprio 2FA enquanto esta opção estiver ativa.
Permitir 2FA para clientes	Ativada	Clientes podem configurar o autenticador e usar códigos no login. Se desativada, os códigos deixam de ser exigidos para clientes que já haviam ativado 2FA.
Nome no aplicativo autenticador	Nome da empresa	Identificação da conta exibida no aplicativo.

A política de cadastro obrigatório usa um aviso e redirecionamento na interface administrativa; ela não substitui as permissões de acesso às APIs para contas que ainda não cadastraram o autenticador.

Configurar o autenticador

Equipe

Acesse Sistema → Two-Factor Authentication. Qualquer membro autenticado pode configurar sua própria conta.

Clientes

No painel do cliente, use o aviso Ativar 2FA ou acesse /twofactorauth.

Etapas

1. Clique em Ativar autenticação de dois fatores.
2. Leia o QR Code com um aplicativo compatível com TOTP ou digite a chave manualmente.
3. Informe o código de seis dígitos exibido no aplicativo e confirme.
4. Guarde os 10 códigos de recuperação. Eles são exibidos apenas nessa etapa e cada código pode ser utilizado uma vez.

O autenticador usa SHA-1, seis dígitos e intervalos de 30 segundos, com tolerância de um intervalo para mais ou para menos. Mantenha os relógios do servidor e do dispositivo sincronizados.

Login e recuperação

No login, informe e-mail e senha. Quando solicitado, preencha o código de seis dígitos ou um código de recuperação. Um código TOTP já utilizado não pode ser repetido, mesmo dentro do mesmo intervalo.

Após cinco códigos incorretos, a verificação de 2FA fica bloqueada por 15 minutos. Esse limite também se aplica à confirmação inicial do autenticador.

Na página do módulo é possível gerar um novo conjunto de códigos de recuperação, confirmando com um código do aplicativo. O conjunto anterior deixa de funcionar. Também é possível desativar o 2FA da própria conta mediante um código válido, desde que a política da equipe permita.

Se o dispositivo e os códigos de recuperação forem perdidos, um administrador com permissão de gerenciamento pode redefinir o 2FA dessa conta. A conta deverá configurar um autenticador novamente. A redefinição de outra conta exige verificação de identidade pelo responsável pelo atendimento.

Permissões

Permissão	Finalidade
Acesso à própria conta	Consultar status, configurar o autenticador e gerenciar os próprios códigos. Disponível a todos os membros autenticados da equipe.
manage	Consultar contas protegidas e redefinir 2FA de outros membros ou clientes.
manage_settings	Alterar a política de 2FA e o nome exibido no autenticador.

API

O login continua no endpoint existente e recebe o campo adicional twofactorauth_code:

POST /api/guest/client/login
Content-Type: application/json

{
  "email": "cliente@example.com",
  "password": "senha-da-conta",
  "twofactorauth_code": "123456"
}

Para a equipe, use /api/guest/staff/login com os mesmos campos. Os erros de verificação usam os códigos 2001 (código necessário), 2002 (código inválido) e 2003 (bloqueio temporário).

Endpoint após /api/admin/ ou /api/client/	Finalidade
twofactorauth/status	Consultar o próprio status.
twofactorauth/setup_start	Iniciar a configuração e obter chave e URI do autenticador.
twofactorauth/setup_confirm	Confirmar a configuração com code e receber os códigos de recuperação.
twofactorauth/disable	Desativar o próprio 2FA com code.
twofactorauth/backup_codes_regenerate	Substituir os códigos de recuperação com code do aplicativo.

A API administrativa também disponibiliza settings, staff_overview, client_list, staff_reset, client_reset e client_status. As consultas e redefinições de outras contas exigem manage; as redefinições recebem o parâmetro id.

Credenciais de máquina por chave de API usam o mecanismo existente do sistema, sem código interativo do autenticador.

Integração com temas

Os formulários precisam manter os slots admin.staff.login.form.after e client.page.login.form.after, responsáveis pelo campo de código. O aviso da equipe usa admin.theme.content.before; o aviso do cliente usa client.index.dashboard.client.before.

Formulários personalizados podem enviar diretamente um campo chamado twofactorauth_code. Os assets são locais em modules/Sistema/Twofactorauth/assets/.

Desativação e desinstalação

Desativar a extensão interrompe sua proteção no login. Desinstalá-la remove a tabela twofactorauth, incluindo as configurações de autenticadores e os hashes dos códigos de recuperação.

Autoria e licença

Integração e manutenção para RCTI ERP por RCTI - Roda de Cuia: rodadecuia.br.

Adaptação do módulo original de TAJHOST, sob Apache License 2.0. Os avisos de copyright originais foram preservados. O gerador local de QR Code é de Kazuhiko Arase, sob licença MIT; seus créditos permanecem no arquivo distribuído.