Authentik: SSO self-hosted para suas aplicações

Um login para todas as aplicações que aloja

O Authentik é um servidor SSO (single sign-on) self-hosted: os utilizadores iniciam sessão uma vez e todas as aplicações atrás dele 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 ele 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 integrado, que é o componente que responde a "esta sessão está autenticada?" para cada aplicação protegida. A versão 2026.8.5 é a versão atual em 25 October 2026. Foi publicada em 21 October 2026 como a versão de correção mais recente da série 2026.8, iniciada com 2026.8.0 em 18 August, e substitui a versão 2026.8.4 de 14 October como tag de imagem predefinida no ficheiro oficial do Compose. O projeto requer um host com pelo menos 2 CPU cores e 2 GB de RAM. Considere isto o mínimo. O PostgreSQL e o worker mantêm memória alocada depois de o servidor estar ligado durante um dia.

O que é necessário antes de começar

É necessário ter o Docker Engine com o plugin Compose v2. Pode confirmar isso 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 ter um registo DNS A a apontar 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 browser.

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

Instalar com o ficheiro oficial do Compose

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, todos ativos, com postgresql a indicar healthy depois de a verificação passar. O primeiro arranque executa as migrações da base de dados, por isso aguarde um minuto antes de esperar uma resposta da interface web.

Ambos os valores gerados são importantes, por razões diferentes. PG_PASS é a palavra-passe do PostgreSQL. A documentação de instalação do Authentik indica que não são suportadas palavras-passe com mais de 99 caracteres, por isso mantenha abaixo desse limite qualquer palavra-passe que escolha; a palavra-passe gerada é muito mais curta. AUTHENTIK_SECRET_KEY é a chave que o Authentik usa para assinar cookies, e a documentação de configuração indica que alterá-la invalida as sessões ativas. Uma nova chave termina, portanto, a sessão de todos os utilizadores autenticados. Mantenha .env com o modo 600 e guarde uma cópia num local seguro juntamente com as cópias de segurança, para que um restauro volte a usar a mesma chave.

O ficheiro do Compose marca ambos os valores como obrigatórios com a forma ${VAR:?message}: ${PG_PASS:?database password required} no serviço PostgreSQL e ${AUTHENTIK_SECRET_KEY:?secret key required} no servidor e no worker. Isso faz com que o Compose recuse iniciar quando o ficheiro não existe. Executar docker compose up -d a partir do diretório errado apresenta uma linha como 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 restante fica no mesmo ficheiro .env. O Authentik mapeia um sublinhado duplo para uma chave de configuração aninhada, por isso AUTHENTIK_EMAIL__HOST define email.host. Um único sublinhado não faz esse mapeamento, que é o motivo mais comum para uma configuração parecer não produzir efeito.

• AUTHENTIK_BOOTSTRAP_PASSWORD define a palavra-passe do utilizador akadmin integrado na primeira inicialização, para nunca ter 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 dos valores predefinidos 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, pelo que as mensagens de reposição de palavra-passe terminam com um erro de ligação no log do worker.
• AUTHENTIK_LOG_LEVEL=debug ativa os detalhes necessários enquanto um fluxo de início de sessão apresenta problemas. Depois, altere-o novamente para info.
• AUTHENTIK_ERROR_REPORTING__ENABLED é false por predefinição. Defina-o como true apenas se aceitar enviar relatórios de falhas para os responsáveis pelo projeto.

Estas são credenciais armazenadas 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 autoalojada do Vaultwarden, é um local melhor para guardar a cópia de recuperação do que uma nota no seu portátil.

Primeiro login e a conta de administração

Abra http://SERVER_IP:9000 num browser. O Authentik apresenta o fluxo de configuração inicial e pede que defina uma palavra-passe para o utilizador akadmin predefinido. Se já tiver definido AUTHENTIK_BOOTSTRAP_PASSWORD, essa etapa está concluída e irá diretamente para a página de login.

Crie um utilizador de administração normal para si 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. Se um fluxo ou estágio com problemas alguma vez o impedir de iniciar sessão, docker compose run --rm server create_recovery_key 10 akadmin, executado a partir de /opt/authentik, apresenta um link que inicia diretamente a sessão como akadmin. Qualquer pessoa que tenha esse link dispõe do mesmo acesso, por isso trate-o como uma palavra-passe. O trabalho diário com uma conta integrada partilhada destrói o registo de auditoria, porque todos os eventos indicam akadmin e nada identifica o utilizador. Isto também se aplica depois do Authentik: algo como um harness self-hosted do OneCLI que fornece um agente próprio a cada pessoa só deixa um registo legível se a identidade que chega até ele pertencer a uma pessoa, em vez de ser um login partilhado por toda a equipa.

Colocar o Authentik atrás do reverse proxy

Publicar a porta 9000 na Internet funciona, mas é necessário usar TLS (transport layer security) e um nome de domínio 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 automaticamente o override, por isso 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/, que deve responder HTTP/2 200. Um 404 page not found do Traefik indica que nenhum router correspondeu ao pedido. Confirme se os labels chegaram ao contentor, se a regra Host() corresponde exatamente ao nome de domínio e se o pedido chegou ao entry point HTTPS em que o router está a escutar.

Quando o nome de domínio funcionar, associe as portas publicadas a 127.0.0.1 no override. Assim, a única forma de acesso será através do proxy.

Proteger uma aplicação com forward auth

O proxy provider 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 a sessão está autenticada. Forward auth (domain level) protege todas as aplicações num domínio pai com um único provider, mas não permite definir regras de autorização por aplicação. Com o Traefik à frente, deve usar forward auth (single application). Se quiser uma aplicação concreta para testar, algo como um workspace AFFiNE self-hosted é um bom primeiro candidato, porque é o tipo de ferramenta interna que deve estar 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 Chatwoot self-hosted atrás do mesmo provider, para que todas as pessoas que respondem à caixa de entrada iniciem sessão uma vez por dia, em vez de partilharem mais uma palavra-passe.

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. Depois abra Outposts, edite o authentik Embedded Outpost e mova a nova aplicação para a lista de aplicações selecionadas. O outpost só responde pelas aplicações que lhe foram atribuídas. Se ignorar este último passo, o provider pode estar corretamente configurado e continuar sem devolver 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-entitlements,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 à aplicação upstream. Se omitir essa lista, a aplicação continua protegida, mas não fica a saber quem é o utilizador. Assim, qualquer componente que leia X-authentik-username para iniciar sessão automaticamente continua a considerar o utilizador como não autenticado. Esta diferença é mais evidente diante de uma aplicação que mantém o seu próprio início de sessão, como um monitor de treinos openGym self-hosted e o respetivo início de sessão 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 costuma ser esquecida. Depois do início de sessão, o Authentik envia o navegador de volta para um caminho sob /outpost.goauthentik.io/ no hostname da aplicação, não sob auth.example.com. Sem um router que envie esse prefixo de caminho para o serviço Authentik, o pedido chega à aplicação, que responde com 404, e o início de sessão nunca termina. O valor mais alto de priority faz com que a regra do caminho específico tenha precedência sobre a regra simples Host() no mesmo domínio.

Teste numa janela privada do navegador. Deve ser redirecionado 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. Isso indica se o pedido chegou ao Authentik.

As falhas que você realmente encontrará

Loop infinito de redirecionamento entre a aplicação e a página de login. O host externo no provider não corresponde ao host usado pelo browser, normalmente http:// no provider e https:// na barra de endereços. 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 para esse host.

A aplicação carrega sem pedir um login. O rótulo middlewares referencia um middleware que não existe. O Traefik não avisa sobre isso, por isso um erro de digitação 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 login 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 abrangente, 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 é importante para algumas organizações, pelo menos formalmente. A desvantagem é que o Keycloak não tem um proxy próprio. Para proteger uma aplicação que não utiliza OIDC (OpenID Connect) nem SAML, é necessário executar algo como o oauth2-proxy ao lado do Keycloak. O fornecedor de proxy integrado do Authentik já inclui essa funcionalidade. Por isso, a maioria dos administradores de servidores próprios com um conjunto diversificado de aplicações acaba por escolher o Authentik.

Cópias de segurança e atualizações

Três elementos permitem fazer um restauro: 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

Guarde esse dump juntamente com .env. O dump não contém uma cópia de AUTHENTIK_SECRET_KEY e o restauro com uma chave diferente invalida todas as sessões ativas. Manter a chave original permite que o servidor restaurado continue no mesmo estado.

As atualizações consistem em alterar uma tag. Defina AUTHENTIK_TAG em .env para a versão pretendida e execute docker compose pull, seguido de docker compose up -d. Se nunca definir AUTHENTIK_TAG, a versão vem do valor predefinido escrito no próprio compose.yml. Nesse caso, descarregar uma cópia mais recente desse ficheiro é a atualização, e é esse o procedimento descrito na documentação oficial de atualização. Leia primeiro as notas da versão. O Authentik usa versões baseadas em datas e, em October 2026, a documentação indica que as atualizações devem seguir a sequência das versões principais: avance para a versão de correção mais recente da série que está a executar e depois passe por cada série posterior pela ordem, sem saltar nenhuma. O Authentik não suporta downgrade, por isso faça o dump da base de dados antes do pull, não depois.

FAQ

O Authentik é gratuito para autoalojar?

A edição open source é gratuita e cobre tudo o que foi mencionado acima: o proxy provider, forward auth, OIDC (OpenID Connect), SAML e o motor de fluxos. Uma versão enterprise paga adiciona suporte e algumas funcionalidades empresariais, mas nada aqui requer uma licença.

Preciso do Traefik para usar o Authentik?

Não. O forward auth funciona com o nginx através do auth_request e com o Caddy através do forward_auth. O padrão é o mesmo em todos os casos: o reverse proxy pergunta ao Authentik sobre cada pedido, e o prefixo de caminho /outpost.goauthentik.io/ no hostname protegido deve encaminhar para o Authentik em vez de para a aplicação.

Porque é que a minha aplicação protegida alterna infinitamente entre o login e um erro?

O host externo configurado no proxy provider não corresponde ao URL que o browser está a utilizar, mais frequentemente http contra https. O cookie de sessão é emitido para uma origem e lido noutra, por isso o Authentik vê um pedido anónimo de cada vez. Corrija o host externo e, em seguida, limpe os cookies de ambos os hostnames antes de testar novamente.

Quanta RAM o Authentik precisa?

O mínimo documentado é de 2 núcleos de CPU e 2 GB de RAM a partir de outubro de 2026, cobrindo o PostgreSQL, o servidor e o worker em conjunto. Numa máquina com 2 GB, a pressão de memória pode ativar o OOM killer do kernel, que termina o processo com a pontuação de "badness" mais elevada: aproximadamente a quota de memória permitida que utiliza, mais o seu oom_score_adj. Quando isso acontece com o worker, o sintoma é a paragem das tarefas em segundo plano e do envio de e-mail, enquanto a página de login continua a funcionar. Disponibilize 4 GB se o mesmo servidor também executar as aplicações que está a proteger.