Authelia (Autenticação e 2FA)

O Authelia atua como a camada de autenticação central do ambiente, protegendo serviços expostos externamente através de 2FA e políticas de acesso.

Ele é integrado ao Nginx Proxy Manager (NPM) via auth_request.

---

🎯 Objetivo

• proteger serviços publicados externamente
• exigir autenticação com 2FA
• permitir bypass controlado para rede interna/VPN
• centralizar política de acesso
• reduzir exposição direta dos serviços

---

📋 Resumo operacional

Topologia

Componente	Local	Endereço lógico
Authelia	RPi (192.168.1.11)	https://auth.scultetus.dev.br
Integração	NPM (VIP)	auth_request via snippets

Fonte da verdade

• configuração e execução do Authelia no RPi
• política aplicada no NPM via snippets versionados no fluxo do NPM

Dependências

• DNS interno e externo corretos para auth.scultetus.dev.br
• NPM saudável no VIP 192.168.1.20
• sessão/cookies alinhados ao domínio scultetus.dev.br

Comandos de validação

curl http://192.168.1.11:9091/api/health
curl -k -I https://auth.scultetus.dev.br
docker logs authelia

Limitações

• serviço não está em HA (apenas RPi)
• indisponibilidade do RPi impacta autenticação externa protegida

Última validação

• 20/04/2026

---

🧱 Arquitetura

Componentes

Componente	Função
Authelia	autenticação e autorização
NPM	integra via auth_request
Backend (file/DB)	armazena usuários e sessões
TOTP	segundo fator (2FA)

---

Execução

• roda em container Docker no RPi
• exposto internamente (porta 9091)
• acessado via proxy (auth.scultetus.dev.br)

---

🌐 Fluxo de autenticação

Usuário → DNS → NPM (VIP)
                   ↓
          Authelia (auth_request)
                   ↓
              login + 2FA
                   ↓
             sessão válida
                   ↓
                serviço

---

🔐 Padrão de acesso

Origem	Comportamento
LAN (192.168.1.0/24)	acesso direto (sem 2FA)
VPN (10.13.13.0/24)	acesso direto
Externo	exige Authelia + 2FA

---

⚙️ Integração com NPM

A proteção é aplicada via Custom Nginx Configuration.

Includes padrão

include /snippets/authelia-location.conf;
include /snippets/authelia-authrequest.conf;

---

Exemplo completo

include /snippets/authelia-location.conf;
include /snippets/authelia-authrequest.conf;

location / {
    proxy_pass http://SERVICO_INTERNO;
}

---

Controle por rede (bypass local)

allow 192.168.1.0/24;
allow 10.13.13.0/24;
deny all;

👉 evita autenticação desnecessária na rede interna

---

🔑 Sessão

Configuração típica:

session:
  name: authelia_session
  cookies:
    - domain: scultetus.dev.br
      authelia_url: https://auth.scultetus.dev.br
      default_redirection_url: https://git.scultetus.dev.br

---

🔐 2FA (TOTP)

• algoritmo padrão (RFC6238)
• apps compatíveis:
  • Google Authenticator
  • Microsoft Authenticator
  • Authy

Parâmetros

• período: 30s
• dígitos: 6
• issuer: domínio do ambiente

---

📌 O que foi feito no ambiente

• Authelia foi instalado no RPi e substituiu a execução anterior no NAS
• a mudança foi feita porque o RPi fica 24/7 e o NAS não
• o container oficial em uso é authelia/authelia
• 2FA via TOTP validado com Google Authenticator
• integração com NPM aplicada via snippets nginx:
  • /snippets/authelia-location.conf
  • /snippets/authelia-authrequest.conf
• sessão configurada com domínio scultetus.dev.br

---

⚠️ Pontos de atenção

• Authelia depende de:
  • DNS funcional
  • NPM correto
  • backend acessível
• falhas podem parecer problema de proxy
• cookies mal configurados quebram sessão

---

🧪 Troubleshooting

1. Verificar saúde do Authelia

curl http://192.168.1.11:9091/api/health

---

2. Testar acesso via proxy

curl -k -I https://auth.scultetus.dev.br

---

3. Validar redirecionamento

• acessar serviço protegido
• verificar se redireciona para Authelia
• confirmar retorno após login

---

4. Verificar logs

docker logs authelia

---

5. Problemas comuns

Sintoma	Causa provável
loop de login	cookie/domínio incorreto
acesso sempre pede login	regra de bypass falhando
não redireciona	snippet não aplicado
erro 500 no proxy	problema no auth_request
falha ao iniciar	problema de permissão ou DB

---

🧭 Fluxo mental de diagnóstico

DNS resolve?
  ↓ não → Pi-hole
  ↓ sim
NPM responde?
  ↓ não → proxy/VIP
  ↓ sim
Authelia responde?
  ↓ não → container/config
  ↓ sim
Login funciona?
  ↓ não → sessão/2FA

---

🔒 Boas práticas

• proteger todos os serviços expostos
• manter bypass apenas para redes confiáveis
• revisar regras após mudanças de rede
• usar HTTPS sempre
• manter secrets fora do compose (arquivo dedicado)

---

📌 Observações importantes

• Authelia não substitui firewall ou VPN
• é uma camada adicional de segurança
• deve ser usado em conjunto com boas práticas de rede

---

📌 Referências rápidas

• DNS → Pi-hole
• Proxy → NPM (VIP)
• Auth → Authelia
• HA → keepalived
• Sessão → cookies + domínio

---