Authentik mit Docker Compose als SSO einrichten

Ein Login für jede gehostete Anwendung

Authentik ist ein selbst gehosteter SSO-Server (Single Sign-on): Ihre Benutzer melden sich einmal an, und jede dahinterliegende Anwendung akzeptiert diese Sitzung, anstatt ein eigenes Passwort anzufordern. Die Installation besteht aus einer offiziellen Docker-Compose-Datei und zwei generierten Secrets. Der aufwendige Teil folgt danach: Sie müssen einen Reverse-Proxy darauf verweisen und eine vorhandene Anwendung hinter Forward Auth schalten.

Authentik wird in dieser Compose-Datei als drei Services bereitgestellt: eine PostgreSQL-Datenbank, ein server-Prozess und ein worker-Prozess. Der Server-Container führt außerdem den eingebetteten Outpost aus. Dieser beantwortet für jede geschützte Anwendung die Frage: „Ist diese Anfrage authentifiziert?“ Version 2026.5 ist Stand Juli 2026 die aktuelle Version. Das Projekt verlangt einen Host mit mindestens 2 CPU-Kernen und 2 GB RAM. Betrachten Sie das als Untergrenze. PostgreSQL und der Worker belegen Speicher, sobald der Server einen Tag lang läuft.

Was Sie vor dem Start benötigen

Sie benötigen Docker Engine mit dem Compose-v2-Plugin. Mit docker compose version können Sie dies überprüfen. Wenn dabei statt einer Versionsangabe ein Fehler ausgegeben wird, installieren Sie das Plugin, bevor Sie fortfahren. Die Grundlagen werden unter Anwendungen mit Docker Compose auf einem VPS ausführen beschrieben. Außerdem benötigen Sie einen DNS-A-Record, der auf den Server zeigt. In den folgenden Beispielen ist dies auth.example.com. Authentik erstellt seine Weiterleitungs-URLs anhand des Hostnamens, den der Browser verwendet hat.

Führen Sie den Stack als normaler Benutzer in der Gruppe docker aus, nicht als root. Die Mitgliedschaft in dieser Gruppe entspricht auf dem Host root-Rechten. Vergeben Sie sie daher nur an ein Bereitstellungskonto und an niemanden sonst, entsprechend dem Prinzip aus Benutzerkonten mit geringstmöglichen Berechtigungen auf einem VPS.

Mit der offiziellen Compose-Datei installieren

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 sollte drei Container auflisten. postgresql sollte healthy und server melden. worker sollte running melden. Beim ersten Start werden die Datenbankmigrationen ausgeführt. Warten Sie daher eine Minute, bevor die Weboberfläche antwortet.

Beide generierten Werte sind aus unterschiedlichen Gründen wichtig. PG_PASS ist das PostgreSQL-Passwort und auf 99 Zeichen begrenzt. AUTHENTIK_SECRET_KEY signiert Sitzungen und Token. Wenn Sie den Wert später ändern, werden alle Benutzer abgemeldet und alle von Ihnen ausgestellten API-Token ungültig. Setzen Sie .env auf den Modus 600 und bewahren Sie eine Kopie an einem sicheren Ort auf. Eine Datenbank, die ohne den zugehörigen geheimen Schlüssel wiederhergestellt wurde, kann von niemandem angemeldet werden.

Die Compose-Datei liest beide Werte mit der Form ${PG_PASS:?database password required} ein. Deshalb verweigert Compose den Start, wenn die Datei fehlt. Wenn Sie docker compose up -d aus dem falschen Verzeichnis ausführen, wird required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required ausgegeben und der Vorgang beendet. Diese Meldung weist auf ein Pfadproblem hin, nicht auf ein Konfigurationsproblem.

Die relevanten Umgebungsvariablen

Alles andere kommt in dieselbe .env-Datei. Authentik ordnet zwei Unterstriche einem verschachtelten Konfigurationsschlüssel zu. Daher setzt AUTHENTIK_EMAIL__HOST den Wert email.host. Ein einzelner Unterstrich wird ohne Warnung ignoriert. Das ist der häufigste Grund dafür, dass eine Einstellung scheinbar keine Wirkung hat.

• AUTHENTIK_BOOTSTRAP_PASSWORD legt beim ersten Start das Passwort des integrierten akadmin-Benutzers fest. Sie müssen es daher nie in ein öffentliches Webformular eingeben. AUTHENTIK_BOOTSTRAP_EMAIL und AUTHENTIK_BOOTSTRAP_TOKEN legen auf dieselbe Weise die Adresse dieses Benutzers und ein API-Token fest.
• COMPOSE_PORT_HTTP und COMPOSE_PORT_HTTPS verlagern die veröffentlichten Ports von den Standardwerten 9000 und 9443.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS und AUTHENTIK_EMAIL__FROM konfigurieren den ausgehenden E-Mail-Versand. Ohne diese Werte versucht Authentik, localhost auf Port 25 zu verwenden. Dadurch schlagen E-Mails zum Zurücksetzen des Passworts fehl. Im Worker-Log erscheint dann ein Verbindungsfehler.
• AUTHENTIK_LOG_LEVEL=debug aktiviert die Detailstufe, die Sie benötigen, wenn ein Anmeldeflow fehlerhaft arbeitet. Setzen Sie den Wert anschließend wieder auf info zurück.
• AUTHENTIK_ERROR_REPORTING__ENABLED ist standardmäßig auf false gesetzt. Setzen Sie den Wert nur auf true, wenn Sie damit einverstanden sind, Absturzberichte an den Anbieter zu senden.

Diese Geheimnisse befinden sich in einer unverschlüsselten Datei. Behandeln Sie das Verzeichnis daher wie jeden anderen Speicherort für Zugangsdaten. Ein Passwortmanager wie eine selbst gehostete Vaultwarden-Instanz eignet sich besser für die Sicherungskopie als eine Notiz auf Ihrem Laptop.

Erstanmeldung und das Administratorkonto

Öffnen Sie http://SERVER_IP:9000 in einem Browser. Authentik zeigt den Ablauf für die Ersteinrichtung an und fordert Sie auf, ein Passwort für den standardmäßigen Benutzer akadmin festzulegen. Wenn Sie AUTHENTIK_BOOTSTRAP_PASSWORD bereits festgelegt haben, ist dieser Schritt abgeschlossen, und Sie gelangen direkt zur Anmeldeseite.

Erstellen Sie unter Directory und dann Users einen normalen Administrationsbenutzer für sich selbst, fügen Sie ihn der Gruppe authentik Admins hinzu und melden Sie sich mit diesem Konto an. Lassen Sie akadmin als Notfallkonto bestehen und speichern Sie dafür ein langes Passwort offline. Die tägliche Arbeit mit einem gemeinsamen integrierten Konto macht das Auditprotokoll unbrauchbar, weil jedes Ereignis akadmin angibt und nicht, wer die Aktion ausgeführt hat.

Authentik hinter Ihren Reverse-Proxy stellen

Port 9000 im Internet zu veröffentlichen funktioniert, aber Sie benötigen TLS (Transport Layer Security) und einen echten Hostnamen. Wenn Sie bereits die Einrichtung aus Traefik als Reverse-Proxy für mehrere Compose-Apps verwenden, verbinden Sie Authentik mit einer Override-Datei mit demselben externen proxy-Netzwerk. Erstellen Sie docker-compose.override.yml neben 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

Wenden Sie die Datei mit docker compose up -d an. Compose führt die Override-Datei automatisch mit der offiziellen Datei zusammen. Der Dienst server behält dadurch alle Einstellungen aus der offiziellen Datei und erhält zusätzlich die Labels. Prüfen Sie dies mit curl -I https://auth.example.com/if/user/. Der Dienst sollte auf HTTP/2 200 antworten. Ein 404 page not found von Traefik bedeutet, dass sich der Container nicht im proxy-Netzwerk befindet. Traefik kann keinen Container weiterleiten, den es nicht erreichen kann.

Sobald der Hostname funktioniert, binden Sie die veröffentlichten Ports in der Override-Datei an 127.0.0.1. Der einzige Zugriffsweg führt dann über den Proxy.

Eine App mit Forward Auth schützen

Authentiks Proxy-Provider hat drei Modi. Wenn Sie den falschen auswählen, verlieren Sie eine Stunde. Proxy bedeutet, dass der Outpost selbst den Datenverkehr an die Upstream-App weiterleitet. Forward Auth (single application) bedeutet, dass Ihr eigener Reverse Proxy den Datenverkehr weiterhin weiterleitet und Authentik nur fragt, ob die Anfrage authentifiziert ist. Forward Auth (domain level) schützt jede App unter einer gemeinsamen übergeordneten Domain mit einem einzigen Provider. Dafür fehlen Autorisierungsregeln pro Anwendung. Wenn Traefik vorgeschaltet ist, benötigen Sie Forward Auth (single application).

Öffnen Sie in der Weboberfläche Applications und anschließend Providers. Erstellen Sie einen Proxy Provider, wählen Sie den Modus Forward Auth (single application) und setzen Sie den externen Host auf https://app.example.com. Erstellen Sie eine Application, die auf diesen Provider verweist. Öffnen Sie anschließend Outposts, bearbeiten Sie authentik Embedded Outpost und verschieben Sie die neue Anwendung in die ausgewählten Anwendungen. Der Outpost antwortet nur für Anwendungen, die ihm zugewiesen wurden. Wenn Sie diesen letzten Schritt überspringen, liefert ein korrekt konfigurierter Provider weiterhin keine Antwort.

Definieren Sie die Middleware einmal am Authentik-Container und referenzieren Sie sie von jeder geschützten App:

      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 ist die Liste der Header, die Traefik aus der Antwort von Authentik in die Anfrage übernimmt, die an die Upstream-App gesendet wird. Wenn Sie diese Liste weglassen, ist die App weiterhin geschützt. Sie erfährt jedoch nie, welcher Benutzer angemeldet ist. Alles, was X-authentik-username für die automatische Anmeldung auswertet, bleibt daher abgemeldet.

Die geschützte App benötigt zwei Router, nicht einen:

    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

Der zweite Router wird häufig vergessen. Nach der Anmeldung sendet Authentik den Browser zurück an einen Pfad unter /outpost.goauthentik.io/ auf dem Hostnamen der App, nicht auf auth.example.com. Ohne einen Router, der dieses Pfadpräfix an den Authentik-Service weiterleitet, erreicht die Anfrage Ihre App. Diese antwortet mit 404, und die Anmeldung wird nicht abgeschlossen. Der höhere Wert von priority sorgt dafür, dass die spezifische Pfadregel gegenüber der einfachen Host()-Regel auf derselben Domain Vorrang hat.

Testen Sie die Konfiguration in einem privaten Browserfenster. Sie sollten zu auth.example.com weitergeleitet werden, sich anmelden können und anschließend zur App zurückkehren. docker compose logs -f server auf der Authentik-Seite gibt für jeden Versuch ein Autorisierungsereignis aus. Daran erkennen Sie, ob die Anfrage Authentik überhaupt erreicht hat.

Die Fehler, auf die Sie tatsächlich stoßen werden

Endlosschleife zwischen der Anwendung und der Anmeldeseite. Der externe Host beim Anbieter stimmt nicht mit dem Host überein, den der Browser verwendet. Üblicherweise ist dies http:// beim Anbieter gegenüber https:// in der Adressleiste. Das Sitzungscookie wird dann für einen anderen Ursprung gesetzt. Dadurch wird jede Rückkehr als neue anonyme Anfrage behandelt. Korrigieren Sie den externen Host und löschen Sie die Cookies für beide Domains, bevor Sie den Test wiederholen.

404 bei /outpost.goauthentik.io/start. Der Outpost-Router fehlt, oder seine Priorität ist niedriger als die des Catch-all-Routers für diesen Host.

Die Anwendung wird geladen, ohne eine Anmeldung anzufordern. Das Label middlewares bezeichnet eine Middleware, die nicht existiert. Traefik gibt dafür keine Warnung aus. Ein Tippfehler in authentik@docker bedeutet daher lediglich, dass keine Middleware ausgeführt wird. Öffnen Sie das Traefik-Dashboard und überprüfen Sie, ob der Router die Middleware auflistet.

403 von Authentik nach erfolgreicher Anmeldung. Der Benutzer ist authentifiziert, aber nicht autorisiert. Für die Anwendung ist eine Policy-Bindung oder eine Gruppenanforderung festgelegt, die dieser Benutzer nicht erfüllt. Das Ereignisprotokoll in der Administrationsoberfläche nennt die Policy, die den Zugriff verweigert hat.

Wenn Keycloak besser geeignet ist

Keycloak ist das ältere Projekt und wird von Red Hat unterstützt. Es ist die stärkere Wahl für klassische Identitätsverwaltung in Unternehmen. Dazu gehören umfangreiche SAML-Föderation, die Vermittlung von Anmeldungen mehrerer externer Identitätsanbieter gleichzeitig sowie der Export und Import von Realms als dokumentierter Migrationsweg. Der dahinterstehende kommerzielle Support ist für einige Organisationen auch formell relevant. Der Nachteil ist, dass Keycloak keinen eigenen Proxy bereitstellt. Für den Schutz einer Anwendung ohne OIDC (OpenID Connect) müssen Sie daher beispielsweise oauth2-proxy daneben betreiben. Der integrierte Proxy-Provider von Authentik übernimmt diese Aufgabe bereits. Deshalb entscheiden sich die meisten Self-Hoster mit einer gemischten Sammlung von Anwendungen für Authentik.

Backups und Upgrades

Für eine Wiederherstellung sind drei Dinge erforderlich: die PostgreSQL-Datenbank, das Verzeichnis ./data und .env.

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

Speichern Sie diesen Dump zusammen mit .env. Der Dump allein reicht nicht aus, weil der geheime Schlüssel zum Schutz von Sitzungs- und Tokendaten in .env liegt.

Upgrades ändern den Tag. Setzen Sie AUTHENTIK_TAG in .env auf das gewünschte Release und führen Sie anschließend docker compose pull und danach docker compose up -d aus. Lesen Sie zuerst die Versionshinweise, da Authentik datumsbasierte Versionen verwendet und einige Releases Migrationen enthalten, die voraussetzen, dass Sie vom vorherigen Release aktualisieren. Erstellen Sie den Datenbank-Dump vor dem Pull, nicht danach.

FAQ

Ist Authentik für den Self-Hosting-Betrieb kostenlos?

Die Open-Source-Edition ist kostenlos und deckt alle oben genannten Funktionen ab: den Proxy-Provider, Forward Auth, OIDC (OpenID Connect), SAML und die Flows-Engine. Eine kostenpflichtige Enterprise-Stufe bietet zusätzlich Support und einige Enterprise-Funktionen. Für die hier beschriebenen Funktionen benötigen Sie jedoch keine Lizenz.

Benötige ich Traefik für die Verwendung von Authentik?

Nein. Forward Auth funktioniert mit nginx über auth_request und mit Caddy über forward_auth. Das Muster ist in jedem Fall gleich: Der Reverse Proxy fragt Authentik für jede Anfrage ab. Das Pfadpräfix /outpost.goauthentik.io/ auf dem geschützten Hostnamen muss zu Authentik statt zur Anwendung weitergeleitet werden.

Warum wechselt meine geschützte Anwendung dauerhaft zwischen Anmeldung und Fehler?

Der auf dem Proxy-Provider konfigurierte externe Host stimmt nicht mit der URL überein, die der Browser verwendet. Am häufigsten ist das bei http gegenüber https der Fall. Das Sitzungs-Cookie wird für einen Ursprung ausgestellt und von einem anderen gelesen. Daher sieht Authentik jedes Mal eine nicht authentifizierte Anfrage. Korrigieren Sie den externen Host. Löschen Sie anschließend die Cookies für beide Hostnamen, bevor Sie den Test wiederholen.

Wie viel RAM benötigt Authentik?

Die dokumentierte Mindestanforderung beträgt seit Juli 2026 2 CPU-Kerne und 2 GB RAM. Das umfasst PostgreSQL, den Server und den Worker zusammen. Auf einem System mit 2 GB beendet der Kernel bei Speicherdruck zuerst den Worker. Das äußert sich darin, dass Hintergrundaufgaben und ausgehende E-Mails stoppen, während die Anmeldeseite weiterhin funktioniert. Weisen Sie dem System 4 GB zu, wenn auf demselben Server auch die von Ihnen geschützten Anwendungen laufen.