> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airys.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de Configuração da MFA

## Visão Geral

A Autenticação Multifator (MFA) adiciona uma camada extra de segurança à sua instalação do AirysChat ao exigir que os usuários forneçam uma senha de uso único baseada em tempo (TOTP) além da senha regular. Este guia ajudará você a ativar a MFA para a sua instância do AirysChat auto-hospedado.

## Pré-requisitos

* AirysChat versão 4.6 ou superior
* Acesso às variáveis de ambiente do seu servidor
* Capacidade de reiniciar o seu aplicativo AirysChat

## Passos de Configuração

### Passo 1: Gerar Chaves de Criptografia

A MFA requer chaves de Criptografia do Active Record para armazenar com segurança os segredos dos usuários. Use o comando de inicialização de criptografia integrado do Rails:

```bash theme={null}
# Faça SSH no seu servidor do AirysChat
cd /path/to/airyschat

# Gere todas as chaves de criptografia necessárias de uma vez
rails db:encryption:init
```

Este comando exibirá todas as três chaves necessárias:

```yaml theme={null}
# Exemplo de saída:
active_record_encryption:
  primary_key: EGY8WhulUOXixybod7ZWwMIL68R9o5kC
  deterministic_key: aPA5XyALhf75NNnMzaspW7akTfZp0lPY
  key_derivation_salt: xEY0dt6TZcAMg52K7O84wYzkjvbA62Hz
```

**Importante**:

* Armazene estas chaves com segurança. Você precisará delas para o próximo passo e para quaisquer futuras migrações de servidor
* Use chaves diferentes para cada ambiente (desenvolvimento, staging, produção)
* Nunca compartilhe ou faça commit dessas chaves para o controle de versão

### Passo 2: Configurar Variáveis de Ambiente

Adicione as seguintes variáveis ao seu arquivo `.env` usando as chaves geradas no Passo 1:

```bash theme={null}
# Chaves de Criptografia do Active Record (necessárias para a funcionalidade MFA/2FA)
# Substitua com as chaves reais da saída de rails db:encryption:init
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=EGY8WhulUOXixybod7ZWwMIL68R9o5kC
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=aPA5XyALhf75NNnMzaspW7akTfZp0lPY
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=xEY0dt6TZcAMg52K7O84wYzkjvbA62Hz
```

## Guia de Configuração do Usuário

Assim que a MFA estiver configurada no seu servidor, os usuários poderão ativá-la para as suas contas:

### Para Usuários: Ativando a MFA

1. **Faça login** na sua conta do AirysChat
2. Navegue até **Configurações de Perfil** → **Segurança**
3. Clique em **Ativar Autenticação de Dois Fatores**
4. **Escaneie o código QR** com um aplicativo autenticador:
   * Google Authenticator
   * Microsoft Authenticator
   * Authy
   * 1Password
   * Ou qualquer aplicativo compatível com TOTP
5. **Insira o código de 6 dígitos** do seu aplicativo autenticador
6. **Salve os seus códigos de backup** em um local seguro (10 códigos alfanuméricos de 8 caracteres)
7. Clique em **Verificar e Ativar**

### Para Usuários: Fazendo login com MFA

1. Insira o seu email e senha como de costume
2. Quando solicitado, insira o código de 6 dígitos do seu aplicativo autenticador
3. Alternativamente, use um código de backup se não tiver acesso ao seu autenticador

### Para Usuários: Desativando a MFA

1. Vá para **Configurações de Perfil** → **Segurança**
2. Clique em **Desativar Autenticação de Dois Fatores**
3. Insira o seu código atual de 6 dígitos e a sua senha
4. Confirme a ação

## Solução de Problemas

### MFA Indisponível

Se os usuários não virem opções de MFA:

1. **Verifique se as chaves de criptografia estão definidas**:

```bash theme={null}
echo $ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
```

Deve exibir a sua chave, não ficar em branco.

2. **Verifique se todas as três chaves estão configuradas**:

```bash theme={null}
rails runner "
  puts 'Primary Key: ' + (ENV['ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY'].present? ? '✓' : '✗')
  puts 'Deterministic Key: ' + (ENV['ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY'].present? ? '✓' : '✗')
  puts 'Derivation Salt: ' + (ENV['ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT'].present? ? '✓' : '✗')
"
```

3. **Certifique-se de que o aplicativo foi reiniciado** após a configuração

### Perda de Acesso ao Autenticador

Se um usuário perder o acesso ao seu autenticador:

1. **Usando códigos de backup**:
   * Os usuários podem fazer login com um dos seus códigos de backup salvos (alfanumérico de 8 caracteres)
   * Cada código só pode ser usado uma vez
   * Exemplo de formato: `A1B2C3D4`

2. **Intervenção do Administrador** (se os códigos de backup também forem perdidos):

```bash theme={null}
# Redefina a MFA para um usuário específico
rake mfa:reset[user@example.com]

# Gere novos códigos de backup para um usuário
rake mfa:generate_backup_codes[user@example.com]

# Redefina a MFA para todos os usuários
rake mfa:reset_all
```

## Práticas Recomendadas de Segurança

### Gerenciamento de Chaves

* **Nunca faça commit das chaves de criptografia** para o controle de versão
* **Gere chaves separadas** para cada ambiente usando `rails db:encryption:init`
* **Use chaves diferentes** para os ambientes de desenvolvimento, staging e produção
* **Gire as chaves periodicamente** (requer reinscrição de todos os usuários)
* **Faça backup das chaves com segurança** - perdê-las significa que os usuários não poderão autenticar

### Segurança do Servidor

* **Use apenas HTTPS** - Os códigos da MFA podem ser interceptados por HTTP
* **Ative a limitação de taxa** - O AirysChat inclui limitação de taxa integrada para tentativas de login
* **Atualizações regulares** - Mantenha o AirysChat e as dependências atualizados
* **Monitore tentativas falhas** - Revise os logs em busca de atividades suspeitas

## Migração e Recuperação de Desastres

### Migrando para um Novo Servidor

1. **Exporte as variáveis de ambiente** do servidor antigo (incluindo as chaves de criptografia)
2. **Faça backup do banco de dados** com os dados da MFA
3. **Configure um novo servidor** com as mesmas chaves de criptografia (NÃO gere novas)
4. **Restaure o banco de dados**
5. **Teste o login com MFA** com uma conta de teste

**Nota**: Você deve usar exatamente as mesmas chaves de criptografia no novo servidor. Se você gerar novas chaves com `rails db:encryption:init`, os segredos da MFA existentes ficarão ilegíveis.

### Recuperação de Desastres

Se as chaves de criptografia forem perdidas:

1. Todos os usuários precisarão reativar a MFA
2. Comunique o problema aos usuários o mais rápido possível

*Este guia se aplica à versão 4.6 e superior do AirysChat*