Como instalar o Authentik com Docker e Traefik

Um login para todas as aplicações alojadas

O Authentik é um servidor SSO (single sign-on) autogerido: os utilizadores iniciam sessão uma vez, e todas as aplicações protegidas aceitam essa sessão em vez de pedirem a sua própria palavra-passe. A instalação usa um ficheiro oficial do Docker Compose e dois segredos gerados. A parte que exige mais atenção vem depois: apontar um reverse proxy para o Authentik e colocar uma aplicação existente atrás de forward auth.

O Authentik é composto por três serviços nesse ficheiro do Compose: uma base de dados PostgreSQL, um processo server e um processo worker. O contentor do servidor também executa o outpost incorporado. Este é o componente que responde a "esta ligação tem uma sessão autenticada?" para cada aplicação protegida. A versão 2026.5 é a versão atual em julho de 2026, e o projeto requer um host com pelo menos 2 núcleos de CPU e 2 GB de RAM. Considere estes valores como o mínimo. O PostgreSQL e o worker mantêm memória ocupada depois de o servidor estar em funcionamento durante um dia.

O que é necessário antes de começar

É necessário ter o Docker Engine com o plugin Compose v2. Pode confirmar a instalação com docker compose version. Se o comando apresentar um erro em vez de uma versão, instale o plugin antes de continuar. Os conceitos básicos estão descritos em executar aplicações com Docker Compose numa VPS. Também é necessário um registo DNS A apontado para o servidor, auth.example.com nos exemplos abaixo, porque o Authentik cria os URLs de redirecionamento com base no nome do host utilizado pelo navegador.

Execute a stack com um utilizador normal pertencente ao grupo docker, e não como root. A associação a esse grupo equivale a root no host. Por isso, atribua-a a uma única conta de deploy e a mais ninguém, seguindo a abordagem descrita em contas de utilizador com privilégios mínimos numa VPS.

Instalar com o ficheiro Compose oficial

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
wget https://docs.goauthentik.io/compose.yml
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
docker compose pull
docker compose up -d

docker compose ps deve listar três contentores, com postgresql a indicar healthy e server a indicar worker e running. O primeiro arranque executa as migrações da base de dados, por isso aguarde um minuto antes de aceder à interface Web.

Ambos os valores gerados são importantes, por motivos diferentes. PG_PASS é a palavra-passe do PostgreSQL e tem um limite máximo de 99 caracteres. AUTHENTIK_SECRET_KEY assina sessões e tokens, por isso alterá-lo termina a sessão de todos os utilizadores e invalida todos os tokens de API emitidos. Mantenha .env com o modo 600 e guarde uma cópia num local seguro, porque uma base de dados restaurada sem a chave secreta correspondente é uma base de dados na qual ninguém consegue iniciar sessão.

O ficheiro Compose lê ambos os valores com a forma ${PG_PASS:?database password required}, o que faz com que o Compose recuse arrancar quando o ficheiro não existe. Executar docker compose up -d no diretório errado apresenta required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required e termina. Essa mensagem indica um problema de caminho, não um problema de configuração.

Os valores do ambiente que importam

Todo o resto fica no mesmo ficheiro .env. O Authentik converte um sublinhado duplo numa chave de configuração aninhada, por isso AUTHENTIK_EMAIL__HOST define email.host. Um único sublinhado é ignorado sem aviso. Esta é a razão mais comum para uma definição parecer não produzir efeito.

• AUTHENTIK_BOOTSTRAP_PASSWORD define a palavra-passe do utilizador incorporado akadmin no primeiro arranque. Assim, nunca precisa de a introduzir num formulário Web público. AUTHENTIK_BOOTSTRAP_EMAIL e AUTHENTIK_BOOTSTRAP_TOKEN definem, da mesma forma, o endereço desse utilizador e um token de API.
• COMPOSE_PORT_HTTP e COMPOSE_PORT_HTTPS alteram as portas publicadas, afastando-as das predefinições 9000 e 9443.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS e AUTHENTIK_EMAIL__FROM configuram o correio de saída. Sem estes valores, o Authentik tenta usar localhost na porta 25. Por isso, as mensagens de reposição de palavra-passe terminam com um erro de ligação no log do worker.
• AUTHENTIK_LOG_LEVEL=debug ativa o nível de detalhe necessário enquanto um fluxo de início de sessão apresenta problemas. Depois, volte a defini-lo como info.
• AUTHENTIK_ERROR_REPORTING__ENABLED é false por predefinição. Defina-o como true apenas se aceitar enviar relatórios de falhas para o fornecedor.

Estas são informações secretas num ficheiro de texto simples. Trate o diretório como trataria qualquer outro repositório de credenciais. Um gestor de palavras-passe, como uma instância self-hosted do Vaultwarden, é um local melhor para guardar a cópia de recuperação do que uma nota no seu portátil.

Primeiro início de sessão e a conta de administrador

Abra http://SERVER_IP:9000 num navegador. O Authentik apresenta o fluxo de configuração inicial e pede que defina uma palavra-passe para o utilizador akadmin predefinido. Se já definiu AUTHENTIK_BOOTSTRAP_PASSWORD, esse passo está concluído e será encaminhado diretamente para a página de início de sessão.

Crie um utilizador administrador normal em Directory e depois em Users, adicione-o ao grupo authentik Admins e inicie sessão com essa conta. Mantenha akadmin como conta de emergência, com uma palavra-passe longa guardada offline. O trabalho diário com uma conta integrada partilhada destrói o registo de auditoria, porque todos os eventos indicam akadmin e não identificam o autor. Esse argumento também se aplica a jusante do Authentik: algo como um harness OneCLI autoalojado que atribui o seu próprio agente a cada pessoa só produz um registo legível se a identidade que lhe chega pertencer a uma pessoa, e não a um login partilhado por toda a equipa.

Coloque o Authentik atrás do seu reverse proxy

Publicar a porta 9000 na Internet funciona, mas é necessário usar TLS (transport layer security) e um hostname real. Se já utiliza a configuração de Traefik como reverse proxy para várias aplicações Compose, ligue o Authentik à mesma rede externa proxy com um ficheiro de override. Crie docker-compose.override.yml junto de compose.yml:

services:
  server:
    networks:
      - default
      - proxy
    labels:
      traefik.enable: "true"
      traefik.docker.network: proxy
      traefik.http.routers.authentik.rule: Host(`auth.example.com`)
      traefik.http.routers.authentik.entrypoints: websecure
      traefik.http.routers.authentik.tls.certresolver: le
      traefik.http.services.authentik.loadbalancer.server.port: "9000"

networks:
  proxy:
    external: true

Aplique-o com docker compose up -d. O Compose combina o override automaticamente. Assim, o serviço server mantém tudo o que está no ficheiro oficial e recebe também os labels. Verifique com curl -I https://auth.example.com/if/user/. O comando deve devolver HTTP/2 200. Um 404 page not found do Traefik indica que o contentor não está na rede proxy. Nesse caso, o Traefik não consegue encaminhar tráfego para um contentor ao qual não consegue chegar.

Quando o hostname funcionar, associe as portas publicadas a 127.0.0.1 no override. Dessa forma, a única entrada será através do proxy.

Proteger uma aplicação com forward auth

O provider de proxy do Authentik tem três modos, e escolher o modo errado pode custar uma hora. Proxy significa que o próprio outpost encaminha o tráfego para a aplicação upstream. Forward auth (single application) significa que o seu reverse proxy continua a encaminhar o tráfego e apenas pergunta ao Authentik se o pedido tem uma sessão autenticada. Forward auth (domain level) protege todas as aplicações sob um domínio principal com um único provider, mas limita as regras de autorização por aplicação. Com o Traefik à frente, deve usar forward auth (single application). Se quiser uma aplicação concreta para praticar, algo como um workspace AFFiNE self-hosted é um bom primeiro candidato, porque é o tipo de ferramenta interna que deve ficar acessível a partir dos seus próprios dispositivos e de mais nenhum local. Uma ferramenta de equipa torna o caso ainda mais claro: coloque um help desk de suporte Chatwoot self-hosted atrás do mesmo provider, e todas as pessoas que respondem à caixa de entrada iniciam sessão uma vez por dia, em vez de partilharem mais uma password.

Na interface web, abra Applications e depois Providers, crie um Proxy Provider, escolha o modo forward auth single application e defina o host externo como https://app.example.com. Crie uma Application que aponte para esse provider. Em seguida, abra Outposts, edite o authentik Embedded Outpost e adicione a nova aplicação às aplicações selecionadas. O outpost só responde pelas aplicações que lhe foram atribuídas. Por isso, se ignorar esse último passo, um provider corretamente configurado continua sem devolver qualquer resposta.

Defina o middleware uma única vez, no contentor do Authentik, e faça referência a ele em todas as aplicações protegidas:

      traefik.http.middlewares.authentik.forwardauth.address: http://server:9000/outpost.goauthentik.io/auth/traefik
      traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: "true"
      traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-authentik-username,X-authentik-groups,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version

authResponseHeaders é a lista de cabeçalhos que o Traefik copia da resposta do Authentik para o pedido que envia a montante. Se a omitir, a aplicação continua protegida, mas nunca fica a saber quem é o utilizador. Assim, qualquer componente que leia X-authentik-username para iniciar sessão automaticamente permanece sem sessão. Esta falha é mais evidente quando a aplicação também mantém um início de sessão próprio, como um tracker de treinos openGym self-hosted e o respetivo login com passkey. Nesse caso, os cabeçalhos determinam se a mesma página apresenta um pedido de autenticação ou dois.

A aplicação protegida precisa de dois routers, não de um:

    labels:
      traefik.enable: "true"
      traefik.http.routers.myapp.rule: Host(`app.example.com`)
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls.certresolver: le
      traefik.http.routers.myapp.middlewares: authentik@docker
      traefik.http.routers.myapp-auth.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
      traefik.http.routers.myapp-auth.entrypoints: websecure
      traefik.http.routers.myapp-auth.tls.certresolver: le
      traefik.http.routers.myapp-auth.priority: "15"
      traefik.http.routers.myapp-auth.service: authentik

O segundo router é a parte que todos costumam omitir. Depois de iniciar sessão, o Authentik envia o browser de volta para um caminho sob /outpost.goauthentik.io/ no hostname da aplicação, não sob auth.example.com. Sem um router que encaminhe esse prefixo de caminho para o serviço Authentik, o pedido chega à aplicação, que responde com 404, e o login nunca termina. O valor mais alto de priority faz com que a regra específica do caminho tenha prioridade sobre a regra simples Host() no mesmo domínio.

Teste numa janela privada do browser. Deve ser encaminhado para auth.example.com, iniciar sessão e regressar à aplicação. docker compose logs -f server no lado do Authentik apresenta um evento de autorização por tentativa. Isto permite confirmar se o pedido chegou sequer ao Authentik.

Falhas que você realmente encontrará

Loop infinito de redirecionamento entre a aplicação e a página de início de sessão. O host externo no fornecedor não corresponde ao que o navegador utiliza, normalmente http:// no fornecedor contra https:// na barra de endereço. O cookie de sessão é então definido para uma origem diferente, por isso cada retorno parece um novo pedido anónimo. Corrija o host externo e limpe os cookies de ambos os domínios antes de testar novamente.

404 em /outpost.goauthentik.io/start. Falta o router do outpost, ou a sua prioridade é inferior à do router abrangente desse host.

A aplicação carrega sem nunca pedir início de sessão. A etiqueta middlewares identifica um middleware que não existe. O Traefik não avisa sobre isso, por isso um erro de escrita em authentik@docker significa simplesmente que nenhum middleware é executado. Abra o dashboard do Traefik e confirme se o router lista o middleware.

403 do Authentik depois de um início de sessão bem-sucedido. O utilizador está autenticado, mas não está autorizado: a aplicação tem uma associação a uma policy ou um requisito de grupo que este utilizador não satisfaz. O log Events na interface de administração identifica a policy que negou o acesso.

Quando o Keycloak é a melhor opção

O Keycloak é o projeto mais antigo, apoiado pela Red Hat, e é a opção mais forte para o trabalho clássico de identidade empresarial: federação SAML intensiva, intermediação de logins de vários fornecedores de identidade externos em simultâneo e exportação e importação de realms como caminho de migração documentado. O suporte comercial associado ao projeto é relevante, pelo menos no papel, para algumas organizações. A desvantagem é que o Keycloak não tem um proxy próprio. Para proteger uma aplicação que não utiliza OIDC (OpenID Connect), é necessário executar algo como oauth2-proxy ao lado dele. O fornecedor de proxy integrado do Authentik já inclui essa função. Por isso, a maioria dos administradores que alojam uma combinação variada de aplicações acaba por escolher o Authentik.

Backups e atualizações

Três elementos tornam possível uma restauração: a base de dados PostgreSQL, o diretório ./data e .env.

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik authentik | gzip > authentik-$(date +%F).sql.gz

Armazene esse dump juntamente com .env. O dump, por si só, não é suficiente, porque a chave secreta que protege os dados de sessão e de tokens está em .env.

As atualizações consistem em alterar uma tag. Defina AUTHENTIK_TAG em .env para a versão que pretende e, em seguida, execute docker compose pull seguido de docker compose up -d. Leia primeiro as notas da versão, porque Authentik usa versões baseadas em datas e algumas versões incluem migrações que esperam que a atualização seja feita a partir da versão anterior. Crie o dump da base de dados antes do pull, não depois.

FAQ

O Authentik é gratuito para alojamento próprio?

A edição de código aberto é gratuita e inclui tudo o que foi descrito acima: o fornecedor de proxy, a autenticação delegada, OIDC (OpenID Connect), SAML e o motor de fluxos. Um nível empresarial pago acrescenta suporte e algumas funcionalidades empresariais, mas nada do que é descrito aqui requer uma licença.

Preciso do Traefik para usar o Authentik?

Não. A autenticação delegada funciona com nginx através de auth_request e com Caddy através de forward_auth. O padrão é igual em todos os casos: o reverse proxy pergunta ao Authentik sobre cada pedido, e o prefixo de caminho /outpost.goauthentik.io/ no hostname protegido tem de ser encaminhado para o Authentik, e não para a aplicação.

Porque é que a minha aplicação protegida alterna continuamente entre o início de sessão e um erro?

O host externo configurado no fornecedor de proxy não corresponde ao URL utilizado pelo browser, normalmente http em vez de https. O cookie de sessão é emitido para uma origem e lido noutra, por isso o Authentik vê sempre um pedido anónimo. Corrija o host externo e limpe os cookies de ambos os hostnames antes de testar novamente.

De quanta RAM precisa o Authentik?

O mínimo documentado é 2 núcleos de CPU e 2 GB de RAM desde julho de 2026, para o PostgreSQL, o servidor e o worker em conjunto. Num servidor com 2 GB, o worker é o primeiro processo terminado pelo kernel sob pressão de memória. O sintoma é a paragem das tarefas em segundo plano e do envio de correio eletrónico, enquanto a página de início de sessão continua a funcionar. Atribua 4 GB se o mesmo servidor também executar as aplicações que está a proteger.