Wer mehrere selbst gehostete Anwendungen betreibt, muss häufig für jeden Dienst eigene Benutzerkonten, Passwörter und Zwei-Faktor-Anmeldungen verwalten. Mit Authentik lässt sich diese Benutzerverwaltung zentralisieren.

Authentik ist eine quelloffene Identity-and-Access-Management-Lösung. Sie kann unter anderem als Single-Sign-on-System, OpenID-Connect-Provider, SAML-Provider oder Forward-Auth-Dienst vor bestehenden Webanwendungen eingesetzt werden.

In dieser Anleitung installieren wir Authentik als vollständigen Docker-Stack mit PostgreSQL, Traefik-Anbindung und einem eingeschränkten Docker-Socket-Proxy.

Das verwendete Repository findest du unter:

https://github.com/happylippo/authentik-stack

Was ist Authentik?

Authentik übernimmt die zentrale Authentifizierung für unterschiedliche Anwendungen und Dienste.

Statt beispielsweise für Grafana, Portainer, das Traefik-Dashboard oder interne Verwaltungsoberflächen jeweils eigene Zugangsdaten zu pflegen, können sich Benutzer über eine gemeinsame Authentik-Anmeldeseite anmelden.

Authentik unterstützt unter anderem:

• Single Sign-on
• OpenID Connect
• OAuth 2.0
• SAML
• LDAP
• Forward Auth
• Passkeys und WebAuthn
• TOTP
• Benutzer- und Gruppenverwaltung
• rollenbasierte Zugriffsregeln
• anpassbare Anmeldeabläufe
• selbst gehostete Outposts

Gerade in Kombination mit Traefik eignet sich Authentik sehr gut, um bestehende Anwendungen nachträglich mit einer zentralen Anmeldung und Zwei-Faktor-Authentifizierung abzusichern.

Funktionen des Docker-Stacks

Der hier verwendete Stack enthält alle wesentlichen Komponenten für den Betrieb von Authentik:

• Authentik-Server für Weboberfläche und API
• Authentik-Worker für Hintergrundaufgaben
• PostgreSQL 16 als Datenbank
• eingeschränkter Docker-Socket-Proxy
• vorbereitete Traefik-Anbindung
• Forward-Auth-Middleware für Traefik
• Docker-Service-Verbindung als Authentik-Blueprint
• interaktives Installationsskript
• automatisch erzeugte Passwörter und Secret Keys
• getrennte interne Docker-Netzwerke
• keine unnötig veröffentlichten Host-Ports

Die Konfiguration wurde bewusst in mehrere Compose-Dateien aufgeteilt. Dadurch bleibt der Stack übersichtlich und einzelne Komponenten können leichter angepasst oder entfernt werden.

Aufbau des Authentik-Stacks

Das Repository besitzt ungefähr folgende Struktur:

authentik-stack/
├── blueprints/
│   └── socket-proxy.yaml
├── compose/
│   ├── authentik-database.yml
│   ├── authentik-server.yml
│   ├── authentik-socketproxy.yml
│   ├── authentik-worker.yml
│   └── networks.yml
├── config/
│   └── html.middleware.authentik.yml
├── .env.example
├── compose.yml
├── first_install.sh
└── README.md

Authentik-Server

Der Container authentik-server stellt die Weboberfläche, die API und die eigentlichen Authentifizierungsabläufe bereit.

Der Server ist mit zwei Netzwerken verbunden:

• dem internen Authentik-Netzwerk
• dem vorhandenen externen Traefik-Netzwerk

Dadurch kann Traefik Authentik direkt über das gemeinsame Docker-Netzwerk erreichen. Der Authentik-Port muss nicht auf dem Docker-Host veröffentlicht werden.

Authentik-Worker

Der Container authentik-worker übernimmt Hintergrundaufgaben wie:

• Verarbeitung von Ereignissen
• Ausführung von Blueprints
• Verwaltung von Outposts
• Versand von Benachrichtigungen
• Kommunikation mit der Docker-API

Der Worker erhält keinen direkten Zugriff auf /var/run/docker.sock. Stattdessen greift er über einen eingeschränkten Socket-Proxy auf die benötigten Docker-Funktionen zu.

PostgreSQL-Datenbank

Als Datenbank verwendet der Stack PostgreSQL 16.

Der Datenbankcontainer ist ausschließlich mit dem internen Authentik-Netzwerk verbunden. Er wird weder auf dem Host veröffentlicht noch an das öffentliche Proxy-Netzwerk angeschlossen.

Das reduziert die Angriffsfläche und verhindert, dass PostgreSQL direkt aus anderen Netzen erreichbar ist.

Docker-Socket-Proxy

Authentik kann eingebettete Outposts automatisch als Docker-Container verwalten. Dafür benötigt der Worker Zugriff auf Teile der Docker-API.

Ein direkter Socket-Mount wäre zwar einfach:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Er würde dem Authentik-Worker jedoch sehr weitreichenden Zugriff auf den gesamten Docker-Host ermöglichen.

Der Stack verwendet deshalb einen separaten Docker-Socket-Proxy. Der Worker erreicht die Docker-API intern über:

tcp://authentik-socket-proxy:2375

Der Port wird nicht auf dem Host veröffentlicht.

Voraussetzungen

Für die Installation werden folgende Komponenten benötigt:

• Linux-Server
• Docker Engine
• Docker Compose v2
• OpenSSL
• vorhandener Traefik-Stack
• aktivierter Docker-Provider in Traefik
• aktivierter File-Provider in Traefik
• externes Docker-Netzwerk für Traefik
• mindestens zwei CPU-Kerne
• mindestens zwei Gigabyte Arbeitsspeicher

Standardmäßig erwartet der Stack ein externes Docker-Netzwerk mit dem Namen:

proxy

Falls das Netzwerk noch nicht existiert, kann es erstellt werden:

docker network create proxy

Verwendet dein Traefik-Stack einen anderen Netzwerknamen, kannst du diesen bei der Installation angeben.

Authentik mit Docker installieren

Repository herunterladen

Klone zunächst das GitHub-Repository:

git clone https://github.com/happylippo/authentik-stack.git
cd authentik-stack

Mache anschließend das Installationsskript ausführbar:

chmod +x first_install.sh

Automatische Erstinstallation starten

Starte den Installer:

./first_install.sh

Das Skript fragt die wichtigsten Einstellungen interaktiv ab. Dazu gehören unter anderem:

• Hauptdomain
• Authentik-Hostname
• gewünschte Authentik-Version
• PostgreSQL-Datenbankname
• PostgreSQL-Benutzer
• Traefik-Netzwerk
• Traefik Certificate Resolver
• Trusted-Proxy-Adressen
• IP-Adresse des Authentik-Servers im Proxy-Netzwerk

Sensible Werte werden automatisch erzeugt.

Das Skript erstellt unter anderem:

• ein zufälliges PostgreSQL-Passwort
• einen zufälligen Authentik-Secret-Key
• die lokale .env
• die benötigten Datenverzeichnisse

Existiert bereits eine .env, fragt das Skript vor dem Überschreiben nach. Die vorhandene Datei wird zuvor mit einem UTC-Zeitstempel gesichert.

Der Installer prüft außerdem:

• ob Docker installiert ist
• ob Docker Compose verfügbar ist
• ob OpenSSL vorhanden ist
• ob das Traefik-Netzwerk existiert
• ob die Compose-Konfiguration gültig ist

Zum Schluss wird sinngemäß folgende Prüfung ausgeführt:

docker compose config --quiet

Docker-Stack starten

Lade zunächst die benötigten Images herunter:

docker compose pull

Starte danach den Stack:

docker compose up -d

Überprüfe den Zustand der Container:

docker compose ps

Je nach Konfiguration sollten folgende Dienste gestartet sein:

authentik-server
authentik-worker
authentik-database
authentik-socket-proxy

Die Logs von Server und Worker können gemeinsam angezeigt werden:

docker compose logs -f authentik-server authentik-worker

Authentik erstmals einrichten

Nach dem Start erfolgt die Ersteinrichtung über den konfigurierten Authentik-Hostnamen.

Die URL lautet:

https://authentik.example.com/if/flow/initial-setup/

Der abschließende Schrägstrich ist wichtig.

Während der Ersteinrichtung legst du das erste Administratorkonto und dessen Passwort fest. Anschließend kannst du dich an der Authentik-Oberfläche anmelden.

Nach der ersten Anmeldung solltest du das Administratorkonto zusätzlich mit WebAuthn, einem Passkey oder mindestens TOTP absichern.

.env manuell erstellen

Alternativ zum Installationsskript kannst du die .env manuell erstellen:

cp .env.example .env
chmod 600 .env

Danach müssen sämtliche Werte vollständig geprüft werden.

Besonders wichtig sind:

ABSOLUTE_PATH=
PG_PASS=
AUTHENTIK_SECRET_KEY=
AUTHENTIK_HOST=
AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS=
TRAEFIK_NETWORK=

Die statischen IP-Adressen der Container müssen innerhalb der konfigurierten Docker-Subnetze liegen und dürfen nicht bereits vergeben sein.

Die .env enthält Geheimnisse und darf niemals in das Git-Repository aufgenommen werden.

Trusted Proxies sicher konfigurieren

Authentik muss wissen, welchen Reverse-Proxys es vertrauen darf.

Dafür wird die Variable AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS verwendet.

Hier sollten ausschließlich die tatsächlichen IP-Adressen oder Netzbereiche des Reverse-Proxys eingetragen werden.

Eine Konfiguration wie diese ist zu weit gefasst:

AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS=0.0.0.0/0,::/0

Damit würde Authentik weitergeleiteten Headern aus beliebigen Quellen vertrauen.

Besser ist die konkrete Angabe des Traefik-Netzes:

AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS=172.20.0.0/24

Noch restriktiver ist die Angabe einer einzelnen festen Traefik-IP:

AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS=172.20.0.2/32

Traefik mit Authentik verbinden

Im Repository befindet sich eine vorbereitete Middleware-Datei:

config/html.middleware.authentik.yml

Diese Datei ist eine Vorlage. Sie muss in das Verzeichnis kopiert werden, das vom Traefik-File-Provider überwacht wird.

Beispiel:

cp config/html.middleware.authentik.yml \
  /pfad/zum/traefik-stack/data/traefik/dynamic/html.middleware.authentik.yml

Die Middleware kommuniziert intern mit Authentik:

http://authentik-server:9000/outpost.goauthentik.io/auth/traefik

Die Anfrage muss dadurch nicht über die öffentliche Authentik-Domain geleitet werden.

Traefik und authentik-server müssen dafür mit demselben externen Docker-Netzwerk verbunden sein.

Anwendung mit Authentik Forward Auth schützen

Nachdem in Authentik ein Proxy Provider und eine zugehörige Anwendung eingerichtet wurden, kann ein Traefik-Router über die Middleware geschützt werden.

Die Middleware wird über den File-Provider geladen:

labels:
  traefik.http.routers.meine-app.middlewares: authentik@file

Das Suffix @file bedeutet, dass die Middleware aus der dynamischen Traefik-Dateikonfiguration stammt.

Ein vollständiges Beispiel sieht folgendermaßen aus:

labels:
  traefik.enable: "true"

  traefik.http.routers.meine-app.entrypoints: websecure
  traefik.http.routers.meine-app.rule: Host(`app.example.com`)
  traefik.http.routers.meine-app.middlewares: authentik@file
  traefik.http.routers.meine-app.tls: "true"
  traefik.http.routers.meine-app.tls.certresolver: cloudflare_resolver

  traefik.http.services.meine-app.loadbalancer.server.port: "8080"

Beim Aufruf der Anwendung fragt Traefik zunächst die Authentik-Middleware ab.

Ist der Benutzer nicht angemeldet, wird er zur Authentik-Anmeldeseite weitergeleitet. Nach erfolgreicher Anmeldung gelangt er zurück zur ursprünglichen Anwendung.

Outpost-Pfad separat routen

Bei einer Single-Application-Forward-Auth muss folgender Pfad erreichbar sein:

/outpost.goauthentik.io/

Dafür wird üblicherweise ein zusätzlicher Router mit höherer Priorität angelegt:

labels:
  traefik.http.routers.meine-app-outpost.entrypoints: websecure
  traefik.http.routers.meine-app-outpost.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
  traefik.http.routers.meine-app-outpost.priority: "100"
  traefik.http.routers.meine-app-outpost.service: authentik@docker
  traefik.http.routers.meine-app-outpost.tls: "true"

Dieser Router darf nicht selbst durch die Authentik-Middleware geschützt werden. Andernfalls kann eine Authentifizierungsschleife entstehen.

Bei einem korrekt konfigurierten eingebetteten Outpost kann Authentik die benötigten Docker-Labels automatisch verwalten.

Docker-Verbindung per Blueprint

Im Verzeichnis blueprints/ befindet sich eine vorbereitete Konfiguration für die interne Docker-Verbindung.

Der Blueprint legt in Authentik eine Docker-Service-Verbindung mit dem Namen:

Local Docker connection

an.

Die Docker-API wird über folgende interne Adresse angesprochen:

tcp://authentik-socket-proxy:2375

Authentik kann dadurch eingebettete Outposts verwalten, ohne dass der Docker-Socket direkt in den Worker eingebunden wird.

Warum keine Host-Ports veröffentlicht werden

Der Authentik-Server muss in dieser Architektur nicht mit einem Port auf dem Docker-Host veröffentlicht werden:

ports:
  - "9000:9000"

Der Zugriff erfolgt ausschließlich über Traefik und das gemeinsame Docker-Netzwerk.

Das bringt mehrere Vorteile:

• Authentik ist nicht zusätzlich über die Server-IP erreichbar.
• TLS wird zentral von Traefik verwaltet.
• Die interne Kommunikation bleibt im Docker-Netzwerk.
• Zugriffskontrolle und Middlewares werden zentral verwaltet.
• Die öffentlich erreichbare Angriffsfläche wird reduziert.

Authentik aktualisieren

Innerhalb der konfigurierten Version kann der Stack mit folgenden Befehlen aktualisiert werden:

docker compose pull
docker compose up -d

Anschließend sollten Status und Logs geprüft werden:

docker compose ps
docker compose logs --tail=100 authentik-server authentik-worker

Vor größeren Authentik-Versionssprüngen solltest du die offiziellen Release Notes lesen.

Verwende für zentrale Infrastruktur möglichst keine unkontrollierten latest-Tags. Eine bewusst gewählte Version oder ein definierter Release-Zweig erleichtert die Planung von Updates und Rollbacks.

Backup erstellen

Vor Updates sollte mindestens die PostgreSQL-Datenbank gesichert werden.

Ein einfacher Datenbank-Dump kann folgendermaßen erstellt werden:

docker exec authentik-database \
  pg_dump -U authentik authentik \
  > authentik-database.sql

Benutzer- und Datenbankname müssen gegebenenfalls an die eigene .env angepasst werden.

Zusätzlich sollten folgende Dateien und Verzeichnisse gesichert werden:

.env
data/
certs/
custom-templates/
blueprints/

Die .env enthält geheime Schlüssel. Sie sollte verschlüsselt oder zumindest mit restriktiven Dateirechten gesichert werden.

Ein Backup gilt erst dann als zuverlässig, wenn auch ein Restore erfolgreich getestet wurde.

PostgreSQL-Datenbank wiederherstellen

Stoppe vor einem Restore zunächst den Authentik-Server und Worker:

docker compose stop authentik-server authentik-worker

Spiele anschließend den Datenbank-Dump ein:

cat authentik-database.sql | \
docker exec -i authentik-database \
psql -U authentik authentik

Danach werden die Dienste wieder gestartet:

docker compose start authentik-server authentik-worker

Je nach Zustand der Datenbank kann es notwendig sein, die vorhandene Datenbank vor dem Restore neu anzulegen. Ein Restore sollte deshalb zuerst in einer Testumgebung geprüft werden.

Fehlerbehebung

Compose-Konfiguration überprüfen

Prüfe zunächst die gesamte Compose-Konfiguration:

docker compose config --quiet

Wird keine Ausgabe angezeigt, ist die Konfiguration syntaktisch gültig.

Authentik startet nicht

Zeige die Logs an:

docker compose logs authentik-server authentik-worker

Typische Ursachen sind:

• falsches PostgreSQL-Passwort
• falscher Datenbankbenutzer
• Datenbank nicht erreichbar
• ungültiger Authentik-Secret-Key
• falsche Dateirechte
• fehlerhafte Netzwerkadressen

PostgreSQL-Passwort stimmt nicht

PostgreSQL übernimmt Benutzername und Passwort nur bei der ersten Initialisierung eines leeren Datenverzeichnisses.

Wird später lediglich PG_PASS in der .env geändert, verwendet die bestehende Datenbank weiterhin das ursprüngliche Passwort.

Du kannst entweder das ursprüngliche Passwort wieder in die .env eintragen oder das Passwort direkt in PostgreSQL ändern.

Öffne zunächst die PostgreSQL-Konsole:

docker exec -it authentik-database \
  psql -U authentik -d authentik

Ändere anschließend das Passwort:

ALTER USER authentik WITH PASSWORD 'NEUES_SICHERES_PASSWORT';

Trage dasselbe Passwort in der .env ein und starte den Stack neu:

docker compose up -d

Bei einer noch leeren Testinstallation kann alternativ das Datenbank-Volume entfernt und neu initialisiert werden. Dabei gehen jedoch alle vorhandenen Authentik-Daten verloren.

Traefik erreicht Authentik nicht

Kontrolliere das externe Proxy-Netzwerk:

docker network inspect proxy

Prüfe anschließend die Netzwerke des Authentik-Servers:

docker inspect authentik-server

Traefik und Authentik müssen mit demselben externen Docker-Netzwerk verbunden sein.

Outposts werden nicht automatisch erstellt

Zeige die Logs von Worker und Socket-Proxy an:

docker compose logs authentik-worker authentik-socket-proxy

Prüfe außerdem:

• Ist DOCKER_HOST korrekt gesetzt?
• Ist der Socket-Proxy erreichbar?
• Wurde der Blueprint geladen?
• Darf der Proxy die benötigten Docker-API-Endpunkte verwenden?
• Wurde Port 2375 versehentlich auf dem Host veröffentlicht?
• Ist die Docker-Service-Verbindung in Authentik aktiv?

Ersteinrichtung zeigt „Not Found“

Stelle sicher, dass die URL exakt mit einem Schrägstrich endet:

https://authentik.example.com/if/flow/initial-setup/

Sicherheitshinweise

Authentik ist in dieser Architektur ein zentraler Identity-Provider. Ein Ausfall oder eine Kompromittierung kann daher mehrere geschützte Anwendungen gleichzeitig betreffen.

Folgende Sicherheitsmaßnahmen sind empfehlenswert:

• .env niemals committen
• Dateirechte der .env auf 600 setzen
• Port 2375 niemals auf dem Host veröffentlichen
• PostgreSQL ausschließlich intern erreichbar machen
• Authentik nur über HTTPS bereitstellen
• Trusted Proxies möglichst eng begrenzen
• Administratorkonten mit Passkeys oder WebAuthn schützen
• regelmäßige Datenbank-Backups erstellen
• Restore-Vorgänge regelmäßig testen
• Sicherheitsupdates zeitnah installieren
• Versionswechsel bewusst durchführen
• unkontrollierte latest-Tags vermeiden
• Zugriff auf die Administrationsoberfläche einschränken
• Authentik-Logs auf ungewöhnliche Anmeldeversuche überwachen

Der Authentik-Secret-Key sollte nach der Inbetriebnahme nicht ohne zwingenden Grund geändert werden. Er wird für kryptografische Funktionen innerhalb von Authentik verwendet.

Vorteile dieses Authentik Docker-Stacks

Der vorgestellte Stack bringt gegenüber einer einfachen Standardinstallation mehrere Vorteile:

• automatisierte Erstinstallation
• automatisch erzeugte Geheimnisse
• klar getrennte Compose-Dateien
• internes PostgreSQL-Netzwerk
• keine unnötigen Host-Ports
• direkte Traefik-Anbindung
• vorbereitete Forward-Auth-Middleware
• eingeschränkter Docker-Socket-Proxy
• vorkonfigurierte Docker-Verbindung per Blueprint
• reproduzierbare Konfiguration
• gute Grundlage für weitere Selfhosting-Dienste

Besonders der Socket-Proxy verbessert die Architektur. Er beseitigt nicht jedes Risiko eines schreibenden Docker-API-Zugriffs, vermeidet jedoch den deutlich weiterreichenden direkten Docker-Socket-Mount im Authentik-Worker.

Fazit

Authentik ist eine leistungsfähige Lösung, um Benutzerkonten und Zugriffe auf selbst gehostete Anwendungen zentral zu verwalten.

In Verbindung mit Traefik können auch Dienste geschützt werden, die selbst kein modernes Single Sign-on oder keine Zwei-Faktor-Authentifizierung unterstützen.

Der hier vorgestellte Docker-Stack kombiniert Authentik mit PostgreSQL, Traefik und einem eingeschränkten Docker-Socket-Proxy. Das Installationsskript fragt die wichtigsten Variablen ab, erzeugt sichere Geheimnisse und prüft die Compose-Konfiguration vor dem ersten Start.

Damit eignet sich der Stack sowohl für Homelabs als auch für kleinere produktive Selfhosting-Umgebungen.

Das vollständige Repository findest du hier:

https://github.com/happylippo/authentik-stack

Häufig gestellte Fragen zu Authentik und Docker

Was ist Authentik?

Authentik ist eine selbst gehostete Identity-and-Access-Management-Lösung. Sie stellt unter anderem Single Sign-on, OpenID Connect, OAuth 2.0, SAML, LDAP und Forward Auth bereit.

Kann Authentik Anwendungen ohne eigene SSO-Unterstützung schützen?

Ja. Über einen Proxy Provider und die Traefik-Forward-Auth-Middleware können auch Anwendungen geschützt werden, die selbst kein OpenID Connect oder SAML unterstützen.

Benötigt Authentik eine Datenbank?

Ja. Authentik benötigt PostgreSQL zur dauerhaften Speicherung von Benutzern, Anwendungen, Providern, Richtlinien und Ereignissen.

Muss Port 9000 veröffentlicht werden?

Nein. Wenn Traefik und Authentik dasselbe Docker-Netzwerk verwenden, kann Traefik den Authentik-Server intern über Port 9000 erreichen. Eine Veröffentlichung auf dem Host ist nicht erforderlich.

Warum verwendet der Stack einen Docker-Socket-Proxy?

Authentik benötigt für die automatische Verwaltung eingebetteter Outposts Zugriff auf Teile der Docker-API. Der Socket-Proxy begrenzt diesen Zugriff und verhindert einen direkten Socket-Mount im Authentik-Worker.

Ist ein Docker-Socket-Proxy vollständig sicher?

Nein. Auch eingeschränkter schreibender Zugriff auf die Docker-API bleibt sicherheitsrelevant. Der Proxy reduziert jedoch die erreichbaren API-Funktionen und ist kontrollierbarer als ein direkter Docker-Socket-Mount.

Kann der Socket-Proxy entfernt werden?

Ja. Wenn keine automatische Verwaltung eingebetteter Outposts benötigt wird, können Socket-Proxy, Docker-Service-Verbindung und die zugehörige Worker-Konfiguration entfernt werden. Outposts müssen dann manuell verwaltet werden.

Wie wird Authentik aktualisiert?

In der Regel werden die neuen Images mit docker compose pull geladen und anschließend mit docker compose up -d gestartet. Vor größeren Versionswechseln sollten die Release Notes geprüft und ein Datenbank-Backup erstellt werden.

Welche Daten müssen gesichert werden?

Mindestens die PostgreSQL-Datenbank und die .env sollten gesichert werden. Abhängig von der Konfiguration sind außerdem data/, certs/, custom-templates/ und blueprints/ relevant.

Warum funktioniert ein neues PostgreSQL-Passwort nicht?

PostgreSQL übernimmt das Startpasswort nur bei der ersten Initialisierung eines leeren Datenverzeichnisses. Eine spätere Änderung der .env ändert das Passwort innerhalb der bestehenden Datenbank nicht automatisch.

Weiterführende Links:

Traefik-Stack

Authentik Homepage

Traefik Homepage