Guia completo do Authentik self-hosted

O Authentik é uma plataforma de identidade self-hosted. Ele centraliza usuários, grupos, login, autenticação multifator e regras de acesso, permitindo usar a mesma identidade em serviços como Proxmox, Grafana, Nextcloud, Immich, Portainer, Wiki.js e dezenas de outros. Quando um programa não entende login único, o Authentik ainda pode colocá-lo atrás de uma camada de autenticação por meio do Proxy Provider.

Este guia parte de uma instalação pequena ou média em Debian ou Ubuntu com Docker Compose. Ele explica não apenas como subir os containers, mas como pensar a arquitetura, configurar domínio e HTTPS, criar usuários e grupos, habilitar recuperação e MFA, integrar serviços por OIDC, SAML, LDAP ou forward auth, fazer backup, atualizar e diagnosticar erros.

Escopo temporal: a pesquisa foi validada contra a linha estável 2026.5 do Authentik. Em 28 de julho de 2026, o Compose oficial apontava para 2026.5.6. Sempre consulte as notas de versão antes de instalar ou atualizar, pois telas, campos e requisitos podem mudar.

Resumo executivo

Para um homelab ou pequena infraestrutura, a arquitetura recomendada é:

1. auth.seudominio.com apontando para o seu proxy reverso;
2. HTTPS público válido no proxy;
3. Authentik em Docker Compose com server, worker e PostgreSQL;
4. SMTP configurado desde o início;
5. um usuário administrativo separado da conta cotidiana;
6. WebAuthn/passkey ou chave física para administradores, TOTP como alternativa e códigos estáticos guardados fora do servidor;
7. um grupo por função, como infra-admins, media-users e familia;
8. OIDC como primeira escolha para aplicativos modernos;
9. SAML somente quando o serviço exigir ou tiver implementação melhor;
10. LDAP/LDAPS para programas antigos ou que realmente consultam um diretório;
11. Proxy Provider com forward auth por aplicação para páginas sem SSO nativo;
12. backup diário do PostgreSQL e cópia de .env, compose.yml, data, certs, templates e blueprints;
13. atualização somente depois de ler as notas, salvar backup testável e respeitar a sequência de versões.

O Authentik não substitui o banco de usuários interno de todos os aplicativos. O resultado depende da integração:

Para serviços importantes, prefira OIDC nativo. Forward auth protege a porta de entrada, mas não cria automaticamente usuários dentro do aplicativo e pode não resolver clientes móveis, APIs, WebDAV ou integrações que não usam navegador.

Metodologia e critérios

A pesquisa foi construída prioritariamente com a documentação oficial do Authentik, o catálogo oficial de integrações, as notas da versão 2026.5 e os arquivos oficiais de instalação. Foram conferidos:

• arquitetura e persistência dos containers;
• requisitos mínimos publicados;
• variáveis de ambiente atuais;
• endpoints atuais de OIDC e SAML;
• funcionamento dos providers, applications, sources e outposts;
• recomendações de backup e atualização;
• requisitos de proxy reverso e WebSocket;
• procedimentos de recuperação;
• integrações práticas com Grafana, Proxmox, Immich, Nextcloud e Jellyfin;
• alertas de segurança publicados pelo projeto.

Os blocos de configuração usam domínios de exemplo. Troque seudominio.com, endereços internos, client IDs e segredos pelos valores do seu ambiente. Nunca copie segredos reais para documentação pública.

O que é o Authentik

O Authentik pode atuar como Identity Provider, ou IdP: o sistema que autentica o usuário e informa a outros serviços quem ele é. O usuário entra uma vez no Authentik e, enquanto a sessão for válida, abre vários aplicativos sem repetir a senha.

Entre as funções mais úteis estão:

• login centralizado;
• painel de aplicativos;
• usuários, grupos, funções e permissões;
• MFA com TOTP, códigos estáticos, WebAuthn/FIDO2/passkeys e métodos adicionais;
• OIDC/OAuth2, SAML, LDAP, RADIUS, proxy de autenticação e outros providers;
• login social ou federação por sources;
• fluxos personalizáveis para login, cadastro, recuperação e consentimento;
• políticas por grupo, usuário, reputação, rede, país ou expressão;
• auditoria de eventos;
• notificações locais, por e-mail ou webhook;
• API e blueprints para automação.

O que ele não é

O Authentik não é:

• gerenciador de senhas;
• substituto de firewall, VPN ou segmentação de rede;
• antivírus ou WAF;
• proxy reverso completo para todos os casos;
• garantia de que uma aplicação antiga passará a entender logout, grupos ou MFA;
• backup dos aplicativos integrados;
• forma segura de publicar indiscriminadamente painéis administrativos na internet.

SSO concentra conveniência e também risco. Se a conta central for comprometida, vários serviços ficam expostos. Por isso, MFA, recuperação, atualização e backup deixam de ser opcionais.

Arquitetura atual

Segundo a arquitetura oficial, a instalação Compose moderna tem três componentes essenciais:

O Compose oficial de 28 de julho de 2026 usa PostgreSQL 16 e imagens do Authentik 2026.5.6. O Redis, presente em muitos tutoriais antigos, foi completamente removido no Authentik 2025.10. Não adicione Redis a uma instalação nova baseada na documentação atual.

Server e outpost embutido

O container server contém o Core e um embedded outpost. Para muitos usos de Proxy Provider em um único host, o outpost embutido é suficiente. Um outpost externo passa a ser útil quando:

• o serviço protegido está em outra rede ou máquina;
• você precisa expor LDAP, RADIUS ou RAC;
• quer aproximar a autenticação dos aplicativos;
• a rede é isolada ou parcialmente sem internet;
• deseja separar falhas e carga do Core.

Worker

O worker executa tarefas assíncronas. Se o painel abre, mas e-mails não saem ou tarefas ficam presas, o problema pode estar nele. No Compose oficial, o worker recebe o socket Docker para criar e atualizar outposts automaticamente. Isso é conveniente, mas poderoso: acesso irrestrito ao socket pode equivaler a acesso root ao host.

PostgreSQL

O PostgreSQL é o componente mais crítico. Sem o banco, você perde usuários, providers, policies, flows e boa parte da configuração. O diretório /data também deve ser protegido se você envia ícones, fundos, relatórios ou outros arquivos.

Conceitos que evitam confusão

Application

Uma Application é a representação visível e lógica do serviço: Grafana, Proxmox ou Nextcloud. Ela recebe nome, slug, ícone, URL de abertura e regras de acesso.

Provider

O Provider define como o Authentik fala com a aplicação. Pode ser OIDC, SAML, LDAP, Proxy e outros. Em geral, existe um provider principal por application.

Source

Uma Source traz identidades de fora para dentro. Exemplos:

• entrar no Authentik com Google;
• usar GitHub ou Discord como login;
• sincronizar ou autenticar contra LDAP/Active Directory;
• receber identidade de outro IdP por OIDC ou SAML.

Regra mental:

• Provider: Authentik autentica o usuário para outro serviço.
• Source: outro serviço autentica o usuário para o Authentik.

Flow, stage e policy

Um flow é um processo, como autenticação, cadastro ou recuperação. Cada stage é uma etapa: identificar usuário, pedir senha, validar MFA, enviar e-mail ou concluir login. Uma policy decide se algo pode acontecer.

O poder do Authentik está aqui, mas também a maior chance de travar a própria conta. Antes de alterar os flows padrão:

1. crie um segundo superusuário;
2. mantenha uma sessão administrativa aberta em outro navegador;
3. exporte ou documente o flow atual;
4. teste em um flow duplicado;
5. conheça o comando de recovery key.

Binding

Um binding liga um usuário, grupo ou policy a uma application, source, flow ou stage. Atenção: conforme a documentação de primeiros passos, se uma aplicação não tiver bindings, todos os usuários poderão acessá-la. Para produção, crie grupos antes das aplicações e aplique bindings explícitos.

Outpost

Um outpost é um componente do Authentik implantado perto do serviço. Proxy, LDAP, RADIUS e RAC dependem de outposts. OIDC e SAML normalmente são atendidos diretamente pelo Core.

Planejamento antes de instalar

Domínio

Reserve um hostname estável, por exemplo:

auth.seudominio.com

Evite trocar o hostname depois de cadastrar passkeys, providers e redirect URIs. WebAuthn está vinculado ao domínio, e serviços OIDC/SAML armazenam endpoints exatos.

DNS

Crie um registro A e, se usado, AAAA apontando para o proxy reverso. Se o acesso for apenas interno:

• use DNS local;
• use split DNS, mantendo o mesmo hostname dentro e fora;
• ou publique apenas por Tailscale, WireGuard ou rede privada.

Um domínio no Cloudflare funciona normalmente. O Authentik não precisa da API do Cloudflare para operar. Se usar o proxy laranja ou Cloudflare Tunnel, preserve Host, X-Forwarded-Proto, X-Forwarded-For e WebSockets, e garanta que o tráfego não consiga contornar o caminho protegido.

Recursos

A documentação oficial exige pelo menos 2 núcleos e 2 GB de RAM para Docker Compose. Na prática:

A recomendação prática não é um mínimo oficial. Mais importante que CPU é ter armazenamento confiável, backup externo e relógio correto.

Relógio

OIDC, SAML e TOTP dependem fortemente do horário. Configure NTP no host. A documentação alerta para não montar /etc/timezone nem /etc/localtime nos containers do Authentik; as operações internas usam UTC, e essas montagens podem quebrar OAuth e SAML.

Topologia recomendada

Internet ou VPN
       |
       v
Proxy reverso com HTTPS
       |
       +--> auth.seudominio.com --> Authentik server:9000
       |
       +--> app.seudominio.com  --> aplicação
                    |
                    +--> OIDC/SAML direto, ou consulta ao outpost

Authentik server <--> PostgreSQL
Authentik worker <--> PostgreSQL
Authentik/outposts <--> aplicações e redes internas

Se o proxy estiver no mesmo host, publique o Authentik apenas em loopback. Se estiver em outro container, use uma rede Docker compartilhada. Se estiver em outra máquina, restrinja a porta no firewall para o IP do proxy.

Instalação no Debian ou Ubuntu com Docker Compose

1. Preparar o host

Use uma versão suportada de Debian ou Ubuntu, atualize o sistema e instale Docker Engine com o plugin Compose v2 conforme a documentação oficial do Docker.

Confirme:

docker --version
docker compose version
timedatectl status

O comando precisa ser docker compose, com espaço. docker-compose é a implementação antiga.

2. Criar o diretório

sudo install -d -m 750 /opt/authentik
sudo chown "$USER":"$USER" /opt/authentik
cd /opt/authentik

3. Baixar o Compose oficial

wget -O compose.yml https://docs.goauthentik.io/compose.yml

Use o Compose oficial como ponto de partida. A própria documentação recomenda não escrever um arquivo do zero na primeira instalação. Guarde uma cópia antes de personalizá-lo:

cp compose.yml compose.yml.original

4. Gerar segredos

umask 077
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" > .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
chmod 600 .env

Não troque AUTHENTIK_SECRET_KEY casualmente. Ela assina cookies; uma alteração invalida sessões. Não versione .env e não envie esse arquivo para suporte ou Git.

5. Limitar as portas, quando o proxy está no mesmo host

Acrescente:

COMPOSE_PORT_HTTP=127.0.0.1:9000
COMPOSE_PORT_HTTPS=127.0.0.1:9443

Se o proxy estiver em container e alcançar o Authentik por rede Docker, você pode remover o mapeamento público e usar o nome do serviço. Se precisar de acesso remoto à porta, restrinja-a com firewall. Não deixe o painel administrativo em HTTP aberto para a internet.

6. Configurar e-mail

O SMTP é tecnicamente opcional, mas operacionalmente essencial. Ele serve para recuperação, verificação e alertas. Exemplo com STARTTLS na porta 587:

AUTHENTIK_EMAIL__HOST=smtp.seudominio.com
AUTHENTIK_EMAIL__PORT=587
AUTHENTIK_EMAIL__USERNAME=auth@seudominio.com
AUTHENTIK_EMAIL__PASSWORD=COLOQUE_O_SEGREDO_REAL_SOMENTE_NO_SERVIDOR
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__USE_SSL=false
AUTHENTIK_EMAIL__TIMEOUT=10
AUTHENTIK_EMAIL__FROM=Authentik <auth@seudominio.com>

Para SMTP implícito na porta 465:

AUTHENTIK_EMAIL__PORT=465
AUTHENTIK_EMAIL__USE_TLS=false
AUTHENTIK_EMAIL__USE_SSL=true

Nunca habilite USE_TLS e USE_SSL simultaneamente. Alguns provedores de VPS bloqueiam SMTP de saída; nesse caso, use um relay autorizado.

7. Subir a pilha

docker compose pull
docker compose up -d
docker compose ps

Veja a inicialização:

docker compose logs -f --tail=100 server worker postgresql

Interrompa a visualização com Ctrl+C; os containers continuam rodando.

8. Fazer o setup inicial

Sem proxy reverso, abra:

http://IP_DO_SERVIDOR:9000/if/flow/initial-setup/

Com domínio e HTTPS já configurados:

https://auth.seudominio.com/if/flow/initial-setup/

A barra final é obrigatória. Sem ela, o Authentik pode responder Not Found. Defina uma senha forte para akadmin e um e-mail real.

9. Testar a configuração

docker compose run --rm worker ak dump_config
docker compose exec worker ak test_email voce@seudominio.com
curl -fsS http://127.0.0.1:9000/-/health/live/
curl -fsS http://127.0.0.1:9000/-/health/ready/

live confirma que o servidor está respondendo. ready também verifica a conexão com PostgreSQL.

Proxy reverso e HTTPS

O guia oficial de reverse proxy exige HTTP/1.1 ou superior e preservação de:

• Host;
• X-Forwarded-Proto;
• X-Forwarded-For;
• Upgrade;
• Connection.

WebSockets são usados na comunicação com outposts. Se a interface funciona, mas o outpost fica desconectado, verifique os headers de upgrade.

Exemplo Nginx

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name auth.seudominio.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name auth.seudominio.com;

    ssl_certificate     /etc/letsencrypt/live/auth.seudominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/auth.seudominio.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Se usar o listener HTTPS interno 9443, altere para proxy_pass https://127.0.0.1:9443.

Proxy confiável

Por padrão, o Authentik confia em loopback e redes privadas. Se o proxy chega de outro intervalo, configure somente a faixa necessária:

AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,IP_OU_REDE_DO_PROXY

Não use 0.0.0.0/0. Isso permitiria que clientes falsificassem headers de origem.

Cloudflare

Há três cenários:

1. DNS only: o Cloudflare apenas resolve o nome; o proxy local cuida de HTTPS.
2. Proxy laranja: o Cloudflare termina a conexão pública e abre outra até sua origem. Use modo Full (strict), certificado válido na origem e restrinja acesso à origem.
3. Cloudflare Tunnel: o cloudflared encaminha o hostname ao Authentik sem abrir porta de entrada.

Cuidados:

• mantenha HTTPS até a origem sempre que possível;
• preserve host e esquema originais;
• aceite IP real apenas de proxies confiáveis;
• confirme WebSockets;
• não aplique outro login intermediário que quebre callbacks OIDC/SAML;
• se usar Cloudflare Access junto, documente qual camada é responsável por cada aplicação para evitar dois logins e loops.

Configuração inicial segura

Criar contas separadas

Mantenha:

• akadmin como conta de emergência, pouco usada;
• uma conta administrativa nominal para cada administrador;
• uma conta comum sem privilégio para uso diário.

Não compartilhe um único superusuário. A auditoria só é útil quando cada pessoa tem identidade própria.

Criar grupos antes dos serviços

Exemplo:

Crie os grupos em Directory > Groups, adicione usuários e depois faça bindings dos grupos às applications. Não confunda grupos de organização visual de aplicativos com grupos de usuários.

Habilitar recuperação

Segundo o guia de usuários, a recuperação exige um recovery flow definido na Brand:

1. configure e teste SMTP;
2. importe ou crie um flow de recuperação com verificação por e-mail;
3. vá a System > Brands;
4. edite a Brand ativa;
5. defina o flow em Default recovery flow;
6. teste com uma conta sem privilégios.

O administrador também pode gerar um link temporário na página do usuário. Trate o link como senha: quem o possui assume a conta.

Configurar MFA

O Authentik oferece por padrão:

• WebAuthn/FIDO2/passkeys: melhor opção para administradores;
• TOTP: compatível com praticamente qualquer autenticador;
• static tokens: códigos de uso único para emergência.

Ordem recomendada:

1. registre duas passkeys ou chaves em locais diferentes;
2. registre TOTP como alternativa;
3. gere códigos estáticos;
4. guarde os códigos fora do servidor e fora do dispositivo principal;
5. acrescente um Authenticator Validation stage ao flow de login;
6. selecione Deny ou Configure em vez de Skip quando o MFA for obrigatório;
7. teste antes de encerrar todas as sessões.

Para administradores, exija MFA sempre. Para usuários domésticos, você pode permitir TOTP ou passkey e usar um período de confiança razoável no dispositivo.

Não destruir o flow padrão na primeira tentativa

Duplique o flow, edite a cópia e associe-o primeiro a uma aplicação de teste. Um flow mal ordenado pode criar loop ou impedir login. A sequência típica é:

Identification -> Password -> Authenticator Validation -> User Login

Passkeys sem senha exigem configuração específica de WebAuthn e HTTPS. Não conclua que uma passkey é “segundo fator” se ela substitui inteiramente a senha; o nível de garantia depende do flow.

Como escolher o protocolo para cada serviço

Use esta ordem:

1. OIDC nativo, quando disponível;
2. SAML, se o fornecedor o suporta melhor;
3. LDAP/LDAPS, quando o programa precisa consultar diretório ou senha;
4. Proxy Provider, quando não existe integração de identidade;
5. mantenha login local, VPN ou acesso restrito quando proxy auth quebraria clientes e APIs.

Integração genérica por OIDC

OIDC é a melhor escolha para a maioria dos serviços modernos. O Authentik atua como OpenID Provider, e a aplicação como client.

Informações necessárias

No aplicativo, descubra:

• callback ou redirect URI;
• post-logout URI, quando suportada;
• scopes esperados;
• claim usado como identificador;
• se o client é confidencial ou público;
• se aceita discovery URL.

Criar application e provider

1. Vá a Applications > Applications.
2. Clique em New Application.
3. Defina nome e slug, por exemplo grafana.
4. Selecione OAuth2/OpenID Connect.
5. Escolha o authorization flow padrão.
6. Cadastre a redirect URI exata como Strict / Authorization.
7. A partir do Authentik 2026.5, cadastre uma URI separada do tipo Post Logout quando o aplicativo a suporta.
8. Use Authorization Code; habilite PKCE quando o cliente suporta.
9. Selecione uma signing key.
10. Anote Client ID e Client Secret.
11. Adicione bindings de grupo.
12. Salve.

Não use regex para redirect URI por conveniência. Prefira URLs estritas. Uma redirect URI ampla pode permitir desvio de código ou token.

Endpoints

Para https://auth.seudominio.com e slug grafana:

Issuer:
https://auth.seudominio.com/application/o/grafana/

Discovery:
https://auth.seudominio.com/application/o/grafana/.well-known/openid-configuration

Authorization:
https://auth.seudominio.com/application/o/authorize/

Token:
https://auth.seudominio.com/application/o/token/

UserInfo:
https://auth.seudominio.com/application/o/userinfo/

JWKS:
https://auth.seudominio.com/application/o/grafana/jwks/

End session:
https://auth.seudominio.com/application/o/grafana/end-session/

Quando o aplicativo aceita discovery, forneça apenas a URL de discovery ou o issuer. Isso reduz erros de digitação.

Scopes

Comece com:

openid profile email

Peça offline_access somente se o serviço realmente precisa de refresh token. Não entregue claims ou grupos desnecessários.

Identificador do usuário

Escolha um identificador estável. E-mail e username podem mudar; UUID ou sub geralmente é mais seguro para novos usuários. Antes de trocar o subject mode de um serviço já usado, verifique se ele criará contas duplicadas.

Exemplo: Grafana

O tutorial oficial usa:

environment:
  GF_AUTH_GENERIC_OAUTH_ENABLED: "true"
  GF_AUTH_GENERIC_OAUTH_NAME: "authentik"
  GF_AUTH_GENERIC_OAUTH_CLIENT_ID: "CLIENT_ID"
  GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET: "CLIENT_SECRET"
  GF_AUTH_GENERIC_OAUTH_SCOPES: "openid profile email"
  GF_AUTH_GENERIC_OAUTH_AUTH_URL: "https://auth.seudominio.com/application/o/authorize/"
  GF_AUTH_GENERIC_OAUTH_TOKEN_URL: "https://auth.seudominio.com/application/o/token/"
  GF_AUTH_GENERIC_OAUTH_API_URL: "https://auth.seudominio.com/application/o/userinfo/"
  GF_AUTH_SIGNOUT_REDIRECT_URL: "https://auth.seudominio.com/application/o/grafana/end-session/"
  GF_SERVER_ROOT_URL: "https://grafana.seudominio.com"

Redirect URI no Authentik:

https://grafana.seudominio.com/login/generic_oauth

Teste primeiro com login local ainda disponível. Só habilite auto-login depois de confirmar que OIDC e permissões funcionam.

Exemplo: Proxmox VE

O guia oficial de integração com Proxmox usa um realm OpenID. Exemplo pela CLI:

pveum realm add authentik \
  --type openid \
  --issuer-url https://auth.seudominio.com/application/o/proxmox/ \
  --client-id CLIENT_ID \
  --client-key CLIENT_SECRET \
  --username-claim username \
  --autocreate 1

Depois, atribua permissões no Proxmox. Autocriar uma conta não concede automaticamente uma função segura. Mantenha o realm local PAM/PVE como acesso de emergência e teste o SSO antes de alterar o padrão.

Exemplo: Immich

No Authentik, crie uma aplicação OIDC e use o issuer:

https://auth.seudominio.com/application/o/immich/

No Immich, habilite OAuth e informe issuer, Client ID e Client Secret. O guia oficial do Immich traz as redirect URIs da versão atual. Confirme-as no próprio Immich, pois clientes web e móveis podem exigir callbacks diferentes.

Exemplo: Nextcloud

O guia oficial do Nextcloud recomenda OIDC para novas instalações. A discovery URL tem o padrão:

https://auth.seudominio.com/application/o/nextcloud/.well-known/openid-configuration

Use o app user_oidc, mapeie sub, nome e e-mail e mantenha uma forma documentada de login local de emergência. Se o Nextcloud já possui usuários, planeje cuidadosamente o mapeamento para não criar duplicatas.

Integração genérica por SAML

SAML aparece em aplicações empresariais, appliances e serviços mais antigos. Aqui:

• SP é a aplicação;
• IdP é o Authentik;
• ACS URL é onde a aplicação recebe a resposta;
• Entity ID/Audience identifica o SP;
• metadata XML automatiza endpoints e certificados.

Procedimento

1. obtenha o metadata XML do SP ou anote ACS URL, Entity ID e NameID esperado;
2. em Applications > Applications, crie uma nova application;
3. selecione SAML Provider;
4. importe o metadata do SP quando possível;
5. confira ACS URL e audience;
6. selecione certificado de assinatura;
7. prefira SHA-256;
8. configure NameID e property mappings;
9. crie bindings de acesso;
10. baixe o metadata do Authentik e importe no SP;
11. teste login iniciado pelo SP e, se necessário, pelo IdP;
12. teste logout separadamente.

Para slug meu-servico, os endpoints atuais são:

SSO/SLO:
https://auth.seudominio.com/application/saml/meu-servico/

Login iniciado pelo IdP:
https://auth.seudominio.com/application/saml/meu-servico/init/

Metadata:
https://auth.seudominio.com/application/saml/meu-servico/metadata/

Na versão 2026.5, o Authentik passou a usar endpoints SAML unificados. Tutoriais antigos com caminhos separados de binding/redirect e binding/post ainda podem funcionar por compatibilidade, mas não devem ser a base de uma configuração nova.

Mapeamentos

O Authentik inclui mappings padrão de e-mail, grupos, nome, UPN, ID e username. Envie apenas o necessário. Para privilégios administrativos, não confie apenas num texto controlável pelo usuário; derive grupos de memberships administradas.

Certificados

Planeje rotação antes do vencimento:

• registre quem confia em qual certificado;
• salve metadata e datas;
• se o SP aceita duas chaves, publique a nova antes de remover a antiga;
• teste assinatura e, se usado, criptografia;
• não envie a chave privada ao SP.

Integração por LDAP/LDAPS

O LDAP Provider apresenta usuários e grupos do Authentik como um diretório. Ele exige um LDAP outpost.

Use LDAP quando:

• o serviço não suporta OIDC ou SAML;
• precisa pesquisar usuários e grupos;
• um plugin depende de Base DN e filtros LDAP;
• a aplicação autentica diretamente com usuário e senha.

Evite LDAP aberto na internet. Prefira rede interna, Tailscale, WireGuard ou VLAN, e use LDAPS.

Criar o provider

1. crie uma application;
2. escolha LDAP Provider;
3. defina Base DN, por exemplo:

DC=ldap,DC=seudominio,DC=com

1. crie bindings para os grupos autorizados;
2. crie uma service account exclusiva para a aplicação;
3. conceda apenas a permissão de busca necessária;
4. gere token ou senha longa;
5. crie ou edite um LDAP outpost;
6. associe a application ao outpost;
7. configure certificado confiável para LDAPS;
8. libere a porta somente na rede necessária.

Portas padrão do outpost:

Você pode publicar externamente como 636:6636, mas apenas em interface/rede restrita.

Parâmetros típicos na aplicação

Servidor: ldap.seudominio.com
Porta: 636
TLS: LDAPS
Base DN: DC=ldap,DC=seudominio,DC=com
Bind DN: CN=conta-servico,OU=users,DC=ldap,DC=seudominio,DC=com
Filtro geral: (objectClass=user)
Filtro por grupo: (memberOf=CN=grupo,OU=groups,DC=ldap,DC=seudominio,DC=com)
Username: uid ou cn, conforme a aplicação
E-mail: mail
Nome: displayName

Os DNs e atributos exatos devem ser confirmados com uma consulta ao outpost. Não reutilize a conta administrativa como bind account.

MFA e LDAP

LDAP não tem um fluxo nativo de MFA. O Authentik pode aceitar senha;codigo para autenticadores baseados em código, mas isso depende do provider e da aplicação. Para muitos casos, um app password limitado é mais previsível. Não prometa MFA forte a uma aplicação só porque o diretório central possui TOTP.

Exemplo: Jellyfin

O Jellyfin não tem SSO externo nativo; a integração oficial comunitária usa o plugin LDAP:

• servidor LDAPS;
• conta de serviço;
• Base DN;
• filtro por grupo, por exemplo jellyfin_users;
• criação automática de usuário;
• grupo administrativo separado.

OIDC também é possível por plugin de terceiros, mas a qualidade e manutenção do plugin devem ser avaliadas. Para mídia doméstica, LDAP costuma ser mais simples; para clientes variados, teste TVs, celulares e apps antes de remover logins locais.

Proxy Provider e forward auth

O Proxy Provider protege aplicações sem OIDC, SAML ou LDAP. Existem três modos:

Prefira single application. O modo de domínio reduz configuração, mas não permite políticas diferentes por aplicação.

Criar um forward auth por aplicação

1. vá a Applications > Applications;
2. crie application e escolha Proxy Provider;
3. selecione Forward auth (single application);
4. informe o host externo exato, como https://painel.seudominio.com;
5. adicione bindings de grupo;
6. associe ao embedded outpost ou a um outpost externo;
7. configure o proxy para consultar o endpoint do outpost;
8. roteie /outpost.goauthentik.io/ sem autenticação para o outpost;
9. teste em janela anônima;
10. confirme acesso negado para um usuário fora do grupo.

Exemplo Caddy

Adaptado do template oficial:

painel.seudominio.com {
    route {
        reverse_proxy /outpost.goauthentik.io/* http://authentik-server:9000

        forward_auth http://authentik-server:9000 {
            uri /outpost.goauthentik.io/auth/caddy
            copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Email X-Authentik-Name X-Authentik-Uid
        }

        reverse_proxy painel-interno:8080
    }
}

Exemplo Nginx Proxy Manager

O template completo muda conforme a topologia. Use a aba Nginx Proxy Manager do template oficial de Nginx e substitua:

• domínio da aplicação;
• endereço do outpost;
• endereço do upstream;
• modo single-app ou domain-level.

Não copie apenas auth_request e esqueça a rota /outpost.goauthentik.io/; isso costuma produzir loop ou página 404.

Cabeçalhos

O outpost pode enviar:

X-authentik-username
X-authentik-groups
X-authentik-entitlements
X-authentik-email
X-authentik-name
X-authentik-uid

O aplicativo só deve confiar nesses cabeçalhos quando:

• acesso direto ao upstream está bloqueado;
• o proxy remove qualquer header semelhante enviado pelo cliente;
• somente o outpost/proxy consegue alcançar a aplicação;
• o aplicativo valida a presença e o conteúdo necessário.

Limitações importantes

Forward auth pode falhar conceitualmente em:

• apps móveis;
• APIs e webhooks;
• WebDAV;
• feeds;
• clientes que não guardam cookies;
• conexões WebSocket incomuns;
• URLs públicas de compartilhamento;
• health checks;
• callbacks de outros sistemas.

Use Unauthenticated Paths apenas para caminhos realmente públicos e com regex específica. Liberar .*, /api/.* ou um prefixo amplo pode anular a proteção.

Alerta de segurança

O projeto publicou o CVE-2026-25748, um bypass de forward authentication envolvendo cookies malformados com Traefik ou Caddy. As linhas antigas foram corrigidas em 2025.10.4 e 2025.12.4; versões atuais também incluem a correção. Não use imagens antigas e não fixe uma versão vulnerável. A recomendação permanente é executar o patch mais recente da linha suportada.

Sources: entrar no Authentik com contas externas

Sources permitem usar Google, GitHub, Microsoft, LDAP, SAML, SCIM e logins sociais como origem. Para adicionar uma source ao login padrão:

1. crie a source em Directory > Federation and Social login ou menu equivalente da versão;
2. configure Client ID, secret e callback;
3. defina como usuários serão vinculados ou criados;
4. crie mappings para username, e-mail e nome;
5. abra Flows and Stages > Flows;
6. edite o default-authentication-flow;
7. edite o identification stage;
8. adicione a source em Selected sources;
9. teste com uma conta nova e outra já existente.

Cuidados:

• não vincule contas apenas por e-mail sem avaliar tomada de conta;
• controle quais domínios podem criar usuários;
• não transforme automaticamente todo usuário externo em administrador;
• mantenha ao menos um login local de emergência;
• documente como revogar acesso quando a conta externa é desativada;
• defina se a source apenas autentica ou também sincroniza atributos.

Políticas e autorização

Comece simples. Bindings diretos de grupos atendem a maior parte de um homelab:

infra-admins -> Proxmox, Grafana, Portainer
media-users  -> Jellyfin, Immich
familia      -> serviços domésticos

Use policies quando precisar:

• exigir MFA para uma aplicação sensível;
• permitir somente uma rede ou país;
• restringir por reputação;
• validar força e vazamento de senhas;
• executar uma etapa apenas para certos grupos;
• enviar notificações para eventos específicos.

Evite expressions em Python quando uma policy pronta resolve. Uma expressão errada é mais difícil de auditar e pode permitir ou bloquear além do esperado.

Any versus All

• Any: basta um binding/policy permitir.
• All: todas as condições aplicáveis precisam passar.

Nomeie as policies como frases claras:

permitir-grupo-infra-admins
exigir-mfa-administradores
permitir-rede-vpn
negar-reputacao-baixa

Teste quatro casos: usuário autorizado, usuário não autorizado, usuário sem MFA e usuário fora da rede esperada.

Outposts

Embedded outpost

Use primeiro o embedded outpost para proxy auth no mesmo ambiente. Ele reduz containers e tokens.

Outpost gerenciado

O Authentik pode criar outposts pelo Docker socket. Vantagem: atualização automática e configuração simples. Risco: o worker acessa a API Docker com poderes relevantes.

Opções:

1. aceitar o socket no homelab e proteger bem o host;
2. usar um Docker Socket Proxy;
3. remover o mount e implantar outposts manualmente;
4. colocar outposts remotos em redes específicas.

O socket proxy deve permitir apenas as operações necessárias de leitura, criação, interrupção e remoção de containers e consulta do sistema. Não exponha a API Docker em TCP sem TLS.

Outpost manual

Um outpost manual recebe:

• URL do Authentik;
• token gerado para o outpost;
• imagem da mesma versão do Core;
• acesso de rede ao Authentik e à aplicação.

Core e outposts devem ter a mesma versão. Se atualizar apenas um lado, podem ocorrer falhas silenciosas ou incompatibilidade.

Backup e restauração

O guia oficial de backup diz que PostgreSQL é a parte mais importante. Um backup completo deve incluir:

Dump do banco

cd /opt/authentik
mkdir -p backups
docker compose exec -T postgresql \
  pg_dump -U authentik -d authentik -Fc \
  > "backups/authentik-$(date +%F-%H%M).dump"

Valide:

test -s backups/authentik-AAAA-MM-DD-HHMM.dump
pg_restore --list backups/authentik-AAAA-MM-DD-HHMM.dump | head

Se pg_restore não estiver no host:

docker run --rm \
  -v "$PWD/backups:/backups:ro" \
  postgres:16-alpine \
  pg_restore --list /backups/authentik-AAAA-MM-DD-HHMM.dump

Arquivos

tar --exclude='./backups' \
  -czf "backups/authentik-files-$(date +%F-%H%M).tar.gz" \
  .env compose.yml data certs custom-templates

Esse arquivo contém segredos. Criptografe-o e copie para outro host ou armazenamento. Um backup no mesmo disco não protege contra falha, ransomware ou erro administrativo.

Política recomendada

• dump diário;
• cópia externa automática;
• retenção diária, semanal e mensal;
• criptografia antes de sair do host;
• teste de restauração trimestral;
• backup manual antes de toda atualização;
• cópia offline da secret key e do procedimento de recuperação.

Restauração

Em uma máquina de teste:

1. instale a mesma versão do Authentik;
2. restaure .env, Compose e diretórios;
3. suba somente o PostgreSQL;
4. restaure o dump com pg_restore;
5. suba server e worker;
6. confira logs e migrations;
7. teste login, MFA, e-mail, OIDC, SAML e outposts;
8. só então considere o backup válido.

Não faça o primeiro teste de restauração durante um desastre real.

Atualização segura

O procedimento oficial tem três regras críticas:

1. downgrade não é suportado;
2. faça backup do PostgreSQL antes;
3. não pule linhas principais de versão.

Se estiver em 2025.12.x, por exemplo, siga a sequência indicada nas notas até chegar à linha desejada. Atualize primeiro para o último patch de cada linha.

Procedimento

cd /opt/authentik
docker compose exec -T postgresql \
  pg_dump -U authentik -d authentik -Fc \
  > "backups/pre-upgrade-$(date +%F-%H%M).dump"

cp compose.yml "backups/compose-pre-upgrade-$(date +%F-%H%M).yml"
wget -O compose.yml https://docs.goauthentik.io/compose.yml
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 server worker postgresql

Depois:

• confira a versão em Dashboards > Overview;
• confira system tasks;
• teste /-/health/ready/;
• teste login comum e administrativo;
• teste pelo menos uma aplicação OIDC e um proxy provider;
• confira todos os outposts;
• teste SMTP.

Não use :latest: essa tag foi congelada na versão 2025.2 e não recebe atualizações. Use o Compose oficial ou uma tag explícita suportada.

Monitoramento e auditoria

Health checks

/-/health/live/   -> processo responde
/-/health/ready/  -> processo e PostgreSQL estão prontos

Para o worker:

docker compose exec worker ak healthcheck

Outposts respondem:

/outpost.goauthentik.io/ping

Métricas

Core, worker e outposts expõem métricas Prometheus na porta 9300. Elas não exigem autenticação porque, por padrão, não são expostas. Mantenha essa porta interna e permita apenas ao Prometheus.

Logs

docker compose logs --since=30m server
docker compose logs --since=30m worker
docker compose logs --since=30m postgresql
docker compose logs -f --tail=200

O nível trace pode incluir cookies e dados sensíveis. Use-o apenas temporariamente, proteja o arquivo resultante e remova-o depois.

Eventos e alertas

Em Events > Logs, acompanhe:

• falhas repetidas de login;
• mudanças administrativas;
• criação e exclusão de usuários;
• erros de provider;
• falhas de outpost;
• tokens e ações incomuns.

Crie Notification Rules para eventos importantes e entregue por e-mail ou webhook. Não encaminhe logs contendo tokens para canais públicos.

Diagnóstico de problemas

Containers não sobem

docker compose ps
docker compose logs --tail=200 postgresql server worker
docker compose config

Verifique:

• .env presente;
• PG_PASS sem quebra inesperada;
• AUTHENTIK_SECRET_KEY definida;
• porta 9000 ou 9443 livre;
• espaço em disco;
• saúde do PostgreSQL;
• permissão nos diretórios.

Not Found no setup inicial

Use a barra final:

/if/flow/initial-setup/

Reinicie os containers se a instalação ainda estiver concluindo tarefas.

Admin travado fora

Gere uma recovery key válida por dez minutos:

docker compose run --rm server create_recovery_key 10 akadmin

Quem tiver a URL assume a conta. Não a cole em chat, ticket ou histórico público.

Como último recurso para o setup inicial:

docker compose exec server ak changepassword akadmin

Loop de login

Confira:

• URL externa e esquema HTTPS;
• Host e X-Forwarded-Proto;
• cookies bloqueados;
• redirect URI exatamente igual;
• horário do host;
• flow e stages;
• policy negando após autenticação;
• aplicação atrás de duas camadas de login.

redirect_uri_mismatch

Compare caractere por caractere:

• http versus https;
• hostname;
• porta;
• caminho;
• barra final;
• letras maiúsculas;
• callback web versus móvel;
• tipo Authorization ou Post Logout nas versões atuais.

Não resolva transformando tudo em regex ampla.

Erro CSRF

Normalmente indica Host ou Origin incorreto no proxy. Preserve o host original e o esquema HTTPS. Confira também se o proxy está numa faixa confiável.

Outpost offline

Verifique:

• token;
• URL authentik_host;
• DNS;
• certificado;
• WebSocket;
• firewall;
• versão igual ao Core;
• associação entre outpost e application;
• system tasks;
• logs do outpost.

502 Bad Gateway

Teste do proxy até o Authentik:

curl -v http://ENDERECO_INTERNO:9000/-/health/ready/

Se funciona no host mas não no container do proxy, o problema é rede Docker, DNS interno ou firewall.

E-mail não chega

docker compose exec worker ak test_email usuario@seudominio.com
docker compose logs --since=15m worker

Verifique TLS versus SSL, porta, autenticação, remetente, SPF/DKIM/DMARC, bloqueio de SMTP na VPS e spam.

Usuário vê uma aplicação que não deveria

Se não existem bindings, todos os usuários têm acesso. Crie binding explícito de grupo. Confira também Any versus All e policies herdadas.

OIDC cria usuário duplicado

O subject/claim usado mudou ou não coincide com a conta existente. Antes de mudar UUID, username ou e-mail como identificador, documente como o aplicativo correlaciona usuários.

LDAP conecta, mas não encontra usuários

Confira:

• Base DN;
• Bind DN;
• permissão de busca da service account;
• filtro;
• grupo e memberOf;
• atributo de username;
• aplicação associada ao outpost;
• certificado e SNI.

Use uma ferramenta como ldapsearch na mesma rede do aplicativo para separar problema de LDAP de problema do plugin.

Checklist de segurança

• Authentik acessível somente por HTTPS ou rede privada
• portas 9000, 9443, 9300, LDAP e debug não expostas sem necessidade
• PostgreSQL não publicado na internet
• .env com permissão 600 e fora do Git
• dois administradores ou conta de emergência testada
• MFA forte nos administradores
• códigos de recuperação armazenados fora do servidor
• SMTP e recovery flow testados
• bindings explícitos em todas as aplicações sensíveis
• login local de emergência mantido nos serviços críticos
• redirect URIs estritas
• Docker socket removido, protegido ou conscientemente aceito
• outposts na mesma versão do Core
• logs e eventos monitorados
• backup externo criptografado
• restauração testada
• versão suportada no patch mais recente
• proxy bloqueia acesso direto ao upstream protegido
• NTP funcionando
• nenhum segredo em arquivos públicos, tickets ou capturas

Ordem de implantação recomendada

Fase 1: laboratório

1. instalar Authentik;
2. configurar domínio, HTTPS e SMTP;
3. criar conta comum e grupo de teste;
4. configurar MFA;
5. proteger uma aplicação descartável;
6. testar backup e recovery key.

Fase 2: OIDC

1. integrar Grafana ou Immich;
2. testar criação e correlação de usuários;
3. aplicar binding de grupo;
4. testar logout;
5. manter login local.

Fase 3: infraestrutura

1. integrar Proxmox;
2. atribuir permissões no próprio Proxmox;
3. testar em outro navegador;
4. documentar realm local de emergência;
5. configurar notificações.

Fase 4: aplicações sem SSO

1. escolher uma página puramente web;
2. criar forward auth single-app;
3. bloquear acesso direto ao upstream;
4. testar usuário permitido e negado;
5. testar API, WebSocket e links públicos antes de proteger outros serviços.

Fase 5: LDAP

1. implantar outpost em rede privada;
2. emitir certificado confiável;
3. criar service account por aplicação;
4. restringir busca e grupos;
5. testar clientes reais;
6. documentar rotação de token e certificado.

Matriz prática de serviços

O catálogo oficial possui mais de 180 guias de integração. Use o guia específico do serviço antes de adivinhar callback, scopes ou mappings.

Recomendações práticas

Para o seu tipo de ambiente com VPS, Docker, Proxmox, Cloudron e Tailscale, eu adotaria:

1. Authentik numa VPS ou VM dedicada com 4 GB de RAM;
2. auth.seudominio.com atrás do proxy reverso já usado;
3. administração permitida somente pela Tailscale ou por uma regra adicional de rede, se isso não impedir os callbacks dos serviços;
4. PostgreSQL local no Compose no início;
5. backup criptografado enviado para outro servidor;
6. OIDC para Proxmox, Grafana, Immich e Nextcloud;
7. LDAP apenas para Jellyfin ou software que realmente precisa dele;
8. forward auth para dashboards web sem SSO;
9. grupos pequenos e explícitos;
10. WebAuthn e TOTP para administradores;
11. uma conta local de emergência em cada serviço crítico;
12. revisão mensal de versão, eventos, certificados e backups.

Não migre todos os serviços de uma vez. SSO muda a forma de entrar, criar contas, revogar acesso e recuperar um desastre. Um serviço por vez deixa claro onde a integração realmente funciona e onde apenas parece funcionar pelo navegador.

Conclusão

O Authentik é uma das opções self-hosted mais completas para centralizar identidade em homelabs e pequenas infraestruturas. Sua força não está apenas em exibir uma tela bonita de login, mas em oferecer OIDC, SAML, LDAP, proxy auth, MFA, flows, policies, sources, outposts e auditoria dentro do mesmo sistema.

A instalação por Docker Compose é simples; a parte importante vem depois. Um Authentik bem implantado precisa de domínio estável, HTTPS correto, SMTP funcional, grupos e bindings explícitos, MFA, login de emergência, backup do PostgreSQL, atualização disciplinada e teste real de cada cliente. OIDC deve ser a escolha padrão. Proxy auth é uma ótima rede de proteção para aplicações web simples, mas não substitui integração nativa em APIs, clientes móveis e protocolos especiais.

O melhor primeiro projeto é integrar Grafana ou Immich, depois Proxmox, e só então avançar para LDAP e forward auth. Assim você aprende o modelo sem transformar o seu provedor de identidade num ponto único de falha antes de saber recuperá-lo.

Fontes consultadas

• Authentik — documentação oficial
• Instalação oficial por Docker Compose
• Arquivo Compose oficial
• Arquitetura do Authentik
• Primeiros passos
• Referência de configuração
• Configuração de e-mail
• Reverse proxy
• Providers
• OAuth2 e OpenID Connect Provider
• Criar um OAuth2 Provider
• SAML Provider
• LDAP Provider
• Proxy Provider
• Criar Proxy Provider
• Forward auth
• Template de forward auth para Nginx e Nginx Proxy Manager
• Template de forward auth para Caddy
• Template de forward auth para Traefik
• Outposts
• Integração Docker para outposts e socket proxy
• Sources
• Gerenciamento e recuperação de usuários
• Authenticator Validation Stage
• WebAuthn, FIDO2 e passkeys
• Policies
• Backup e restauração
• Atualização do Authentik
• Monitoramento e health checks
• Eventos e auditoria
• Recuperação quando não é possível entrar
• Notas da versão 2026.5
• CVE-2026-25748
• Catálogo oficial de integrações
• Integração com Grafana nos primeiros passos
• Integração com Proxmox VE
• Integração com Immich
• Integração com Nextcloud
• Integração com Jellyfin

Nota sobre atualidade

Pesquisa concluída em 28 de julho de 2026. O Authentik recebe novas versões, correções de segurança e mudanças em providers, endpoints e assistentes de configuração. Antes de instalar, atualizar ou publicar um serviço, confirme a versão suportada, o patch mais recente, as notas de release e o guia oficial específico da aplicação.