Keycloak auf dem Synology NAS installieren: SSO und zentrale Logins mit OIDC und SAML

Wer mehrere Self-Hosted-Dienste betreibt – Nextcloud, Gitea, Grafana, Portainer, Jellyfin – kennt das Problem: für jeden Dienst ein eigenes Konto, eigene Passwörter, kein zentrales Benutzermanagement. Keycloak löst genau das. Als Open-Source-Identity-Provider (IdP) von Red Hat ist es der Industrie-Standard für Enterprise-SSO und beherrscht sowohl OpenID Connect (OIDC) als auch SAML 2.0 vollständig – ein klarer Vorteil gegenüber leichtgewichtigeren Alternativen wie Authentik oder Authelia, die vor allem für SAML-intensive Anwendungen Grenzen zeigen. Diese Anleitung setzt auf ein Container-Manager-Projekt mit PostgreSQL als Produktionsdatenbank, weil der standardmäßige Dev-Mode (H2 In-Memory) ausdrücklich nicht für produktiven Betrieb geeignet ist und Daten beim Neustart verliert.

Voraussetzungen

1. Synology NAS mit DSM 7.2 oder neuer und installiertem Container Manager
2. Mindestens 4 GB RAM im NAS (Keycloak benötigt min. 750 MB, empfohlen 2 GB; dazu kommt PostgreSQL)
3. x86_64-CPU (Intel/AMD) – das Image ist multi-arch, ARM64-Synology-Modelle werden ebenfalls unterstützt
4. Nginx Proxy Manager bereits auf dem NAS installiert und erreichbar (siehe Nginx Proxy Manager auf der Synology mit Container Manager einrichten)
5. Öffentliche Domain mit SSL-Zertifikat (Let's Encrypt via NPM empfohlen)
6. SSH-Zugang zum NAS oder Zugriff auf die Synology File Station
7. Grundkenntnisse in Docker Compose

Schritt 1: Verzeichnisstruktur anlegen

Bevor der Container startet, müssen die Datenpfade auf dem NAS existieren. Keycloak und PostgreSQL schreiben ihre Daten in separate Verzeichnisse unter /volume1/docker. Lege diese per SSH oder File Station an.

Per SSH (als Administrator):

mkdir -p /volume1/docker/keycloak/data mkdir -p /volume1/docker/keycloak/themes mkdir -p /volume1/docker/keycloakdb

Wer lieber die File Station nutzt: Öffne File Station → docker, erstelle den Ordner keycloak mit den Unterordnern data und themes, sowie den Ordner keycloakdb auf gleicher Ebene.

Verifizieren: Prüfe per SSH oder File Station, dass alle drei Pfade existieren:

ls -la /volume1/docker/keycloak/ ls -la /volume1/docker/keycloakdb/

Erwartete Ausgabe: Die Verzeichnisse data, themes und keycloakdb sind sichtbar, leer und gehören dem aktuellen Benutzer.

Schritt 2: Compose-Projekt im Container Manager anlegen

Öffne im DSM den Container Manager → Projekt → Erstellen. Vergib den Projektnamen keycloak und wähle als Pfad /volume1/docker/keycloak. Füge folgende compose.yaml ein – passe die markierten Passwörter und deinen Hostnamen an:

services: db: image: postgres:17 container_name: keycloak-db restart: unless-stopped environment: POSTGRES_DB: keycloak POSTGRES_USER: keycloakuser POSTGRES_PASSWORD: 'sicheres_db_passwort' volumes: - /volume1/docker/keycloakdb:/var/lib/postgresql/data networks: - keycloak-net healthcheck: test: ["CMD-SHELL", "pg_isready -U keycloakuser -d keycloak"] interval: 10s timeout: 5s retries: 5 keycloak: image: quay.io/keycloak/keycloak:26.6.3 container_name: keycloak restart: unless-stopped command: start environment: KC_DB: postgres KC_DB_URL: jdbc:postgresql://db:5432/keycloak KC_DB_USERNAME: keycloakuser KC_DB_PASSWORD: 'sicheres_db_passwort' KC_BOOTSTRAP_ADMIN_USERNAME: admin KC_BOOTSTRAP_ADMIN_PASSWORD: 'sicheres_admin_passwort' KC_HOSTNAME: https://keycloak.deinedomain.de KC_HTTP_ENABLED: "true" KC_PROXY_HEADERS: xforwarded KC_HEALTH_ENABLED: "true" ports: - "8711:8080" volumes: - /volume1/docker/keycloak/data:/opt/keycloak/data networks: - keycloak-net depends_on: db: condition: service_healthy networks: keycloak-net: driver: bridge

Drei wichtige Hinweise zum Compose:

1. Image: Das offizielle Image liegt auf quay.io, nicht auf Docker Hub. Der Tag 26.6.3 ist der aktuelle stabile Stand (Juni 2026) und behebt 16 CVEs. Wer :latest bevorzugt, sollte sich bewusst sein, dass automatische Updates das Verhalten verändern können.
2. Sonderzeichen in Passwörtern: Das Zeichen $ wird in YAML als Variablenreferenz interpretiert. Passwörter immer in einfachen Anführungszeichen angeben oder $ vermeiden.
3. command: start: Ohne diesen Befehl startet Keycloak im Dev-Mode mit flüchtiger H2-Datenbank. Für Produktion ist start Pflicht.

Verifizieren: Klicke im Container Manager auf „Erstellen“ und beobachte den Build-Prozess. Beide Container (keycloak-db und keycloak) sollten nach 30–90 Sekunden den Status Läuft (grüner Punkt) anzeigen. Keycloak startet erst, nachdem PostgreSQL den Healthcheck bestanden hat – das depends_on mit condition: service_healthy sorgt dafür. Prüfe die Logs:

docker logs keycloak -f

Erwartete Ausgabe (letzte Zeilen):

Keycloak 26.6.3 on JVM (powered by Quarkus ...) started in ... Listening on: http://0.0.0.0:8080

Solange du diese Zeile noch nicht siehst, warte weitere 30–60 Sekunden. Keycloak braucht Zeit für JVM-Warmup und Datenbankinitialisierung.

Schritt 3: Nginx Proxy Manager konfigurieren

Keycloak läuft intern auf Port 8711 des NAS und darf so nicht direkt ins Internet exponiert werden. Der Nginx Proxy Manager übernimmt TLS-Terminierung und Forward-Headers. Ohne korrekte Header stellt Keycloak falsche Redirect-URLs aus.

Öffne den Nginx Proxy Manager → Proxy Hosts → Add Proxy Host:

1. Domain Names: keycloak.deinedomain.de
2. Scheme: http
3. Forward Hostname / IP: localhost (oder die NAS-IP)
4. Forward Port: 8711
5. Websockets Support: aktiviert

Unter dem Tab SSL ein Let's-Encrypt-Zertifikat ausstellen und HTTPS erzwingen. Unter dem Tab Advanced folgende Custom Nginx-Konfiguration einfügen:

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Real-IP $remote_addr; proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k;

Die Buffer-Einstellungen sind wichtig: Keycloak sendet große HTTP-Header (JWT-Token, Session-Cookies), die ohne erhöhte Buffer-Größen zu 502-Fehlern führen können.

Verifizieren: Öffne im Browser https://keycloak.deinedomain.de. Die Keycloak-Willkommensseite mit dem Link zur Admin-Konsole muss erscheinen. Prüfe außerdem, dass das Schloss-Symbol (gültiges TLS-Zertifikat) im Browser angezeigt wird. Wenn du stattdessen einen „HTTPS required“-Fehler siehst, fehlt KC_HTTP_ENABLED=true oder die NPM-Konfiguration ist noch nicht gespeichert.

Schritt 4: Admin-Konsole aufrufen und sichern

Rufe https://keycloak.deinedomain.de/admin auf. Melde dich mit den Bootstrap-Zugangsdaten an, die du in der Compose-Datei unter KC_BOOTSTRAP_ADMIN_USERNAME und KC_BOOTSTRAP_ADMIN_PASSWORD gesetzt hast.

Das Bootstrap-Konto ist ein temporäres Konto und sollte sofort gesichert werden:

1. Wechsle oben links in den Realm master.
2. Gehe zu Users → Add user und lege einen neuen Benutzer an (z.B. keycloak-admin).
3. Unter Role mapping weise die Rolle admin zu.
4. Setze unter Credentials ein starkes Passwort.
5. Melde dich mit dem neuen Konto an und lösche anschließend den temporären Bootstrap-User unter Users → admin → Delete.

Entferne nach dem ersten erfolgreichen Login die KC_BOOTSTRAP_ADMIN_USERNAME- und KC_BOOTSTRAP_ADMIN_PASSWORD-Variablen aus der Compose-Datei und starte den Stack neu – diese Variablen werden nach dem ersten Start nicht mehr benötigt und stellen ein Sicherheitsrisiko dar, wenn ein bekannter Admin-Name in der Konfiguration bleibt.

Verifizieren: Melde dich mit dem neuen Admin-Konto an. Die Admin-Konsole sollte vollständig laden, links das Menü mit Realm Settings, Clients, Users usw. anzeigen. Wenn die Konsole hinter dem Reverse Proxy nicht lädt oder Weiterleitungs-Fehler auftreten, prüfe, ob KC_PROXY_HEADERS=xforwarded korrekt gesetzt ist – die veraltete Variable KC_PROXY existiert ab Keycloak 24 nicht mehr.

Schritt 5: Eigenen Realm anlegen

Im master-Realm verwaltest du Keycloak selbst. Für deine Anwendungen legst du einen separaten Realm an – zum Beispiel homelab oder firma. So bleiben Benutzer, Clients und Flows sauber voneinander getrennt, und du kannst bei Bedarf weitere Realms (z.B. für verschiedene Abteilungen oder Kunden) anlegen.

1. Klicke oben links auf den Realm-Selector und wähle Create realm.
2. Vergib einen Namen, z.B. homelab, und klicke Create.
3. Unter Realm Settings → General kannst du den Anzeigenamen und das Frontend-URL-Verhalten anpassen.
4. Unter Realm Settings → Login aktiviere nach Bedarf Benutzerregistrierung, „Forgot password“ und E-Mail-Verifizierung.
5. Lege unter Users → Add user einen Test-Benutzer an und setze unter Credentials ein Passwort (Temporary auf „Off“ setzen).

Verifizieren: Öffne die OIDC-Discovery-URL deines neuen Realms im Browser:

https://keycloak.deinedomain.de/realms/homelab/.well-known/openid-configuration

Du solltest ein JSON-Dokument sehen, das alle Endpunkte (authorization_endpoint, token_endpoint, userinfo_endpoint usw.) enthält. Ist dieses Dokument erreichbar, ist der Realm korrekt eingerichtet und von außen erreichbar.

Schritt 6: OIDC-Test-Client anlegen und verifizieren

Ein Client in Keycloak repräsentiert eine Anwendung, die sich über Keycloak authentifizieren soll. Hier erstellst du einen Test-Client für OIDC – das Prinzip ist für Nextcloud, Gitea, Grafana und andere Dienste identisch.

1. Wähle deinen Realm (z.B. homelab) und navigiere zu Clients → Create client.
2. Client type: OpenID Connect
3. Client ID: z.B. nextcloud oder test-client
4. Klicke Next und aktiviere Client authentication (= confidential client, hat ein Client Secret).
5. Unter Valid redirect URIs trägst du die Callback-URL deiner Anwendung ein, z.B. https://nextcloud.deinedomain.de/apps/oidc_login/oidc. Für erste Tests reicht auch https://your-app.example.com/*.
6. Speichere den Client.
7. Unter dem Tab Credentials findest du das Client Secret – kopiere es für die Konfiguration in deiner Anwendung.

Deine Anwendung braucht dann folgende Werte:

Verifizieren: Teste den Authorization Flow manuell im Browser. Rufe die Autorisierungs-URL auf (ersetze CLIENT_ID und REDIRECT_URI entsprechend):

https://keycloak.deinedomain.de/realms/homelab/protocol/openid-connect/auth?client_id=test-client&response_type=code&redirect_uri=https%3A%2F%2Fyour-app.example.com%2Fcallback&scope=openid

Es muss die Keycloak-Loginseite erscheinen. Melde dich mit dem Test-Benutzer an. Nach erfolgreichem Login wirst du zur redirect_uri mit einem code-Parameter weitergeleitet. Das beweist, dass OIDC grundsätzlich funktioniert.

Schritt 7: SAML-Client für Enterprise-Anwendungen

Einer der Hauptgründe, Keycloak statt Authentik oder Authelia zu wählen, ist die vollständige SAML 2.0-Unterstützung. Dies ist besonders relevant für Atlassian-Produkte (Jira, Confluence), Nextcloud Enterprise oder SharePoint-Verbindungen. Der Ablauf ist dem OIDC-Client ähnlich:

1. Erstelle unter Clients → Create client einen neuen Client mit Client type: SAML.
2. Trage als Client ID die Entity ID deiner Anwendung ein (meist eine URL, z.B. https://jira.deinedomain.de).
3. Setze die Valid redirect URIs auf die ACS-URL (Assertion Consumer Service) der Anwendung.
4. Lade die SAML-Metadaten-URL von Keycloak herunter und trage sie in deiner Anwendung ein:

https://keycloak.deinedomain.de/realms/homelab/protocol/saml/descriptor

Verifizieren: Öffne die Metadaten-URL im Browser. Du solltest ein XML-Dokument mit dem <EntityDescriptor>-Element sehen, das alle SAML-Endpunkte deines Realms beschreibt. Damit ist Keycloak bereit, SAML-Assertions auszustellen.

Eckdaten auf einen Blick

Troubleshooting / Typische Fehler

1. „Database not available“ / Keycloak startet nicht: PostgreSQL war noch nicht bereit, als Keycloak startete. Stelle sicher, dass der healthcheck im db-Service konfiguriert ist und depends_on mit condition: service_healthy gesetzt ist. Ohne Healthcheck startet Keycloak zu früh und scheitert an der Datenbankverbindung.
2. „Invalid parameter: redirect_uri“: KC_HOSTNAME stimmt nicht exakt mit der URL im Browser überein. Der Wert muss die vollständige öffentliche HTTPS-URL sein (inkl. https://), exakt so, wie der Browser sie aufruft – ohne abschließenden Slash.
3. „HTTPS required“: Der Produktionsmodus verlangt HTTPS. Ist KC_HTTP_ENABLED=true nicht gesetzt, lehnt Keycloak HTTP-Anfragen ab. Diese Variable ist Pflicht, wenn der Reverse Proxy HTTPS terminiert und intern HTTP weitergibt.
4. Admin-Konsole lädt nicht hinter dem Reverse Proxy: KC_PROXY_HEADERS=xforwarded fehlt oder ist falsch. Die Variable KC_PROXY (mit Werten wie edge) wurde mit Keycloak 24 entfernt. Ältere Anleitungen im Netz verwenden noch dieses veraltete Format.
5. Datenbankpasswort mit Sonderzeichen funktioniert nicht: Das Zeichen $ in YAML-Werten ohne Anführungszeichen wird als Variablenreferenz interpretiert. Passwörter immer in einfachen Anführungszeichen ('passwort') einschließen oder $ im Passwort vermeiden.
6. Timeout beim ersten Aufruf: Keycloak benötigt 30–90 Sekunden zum Hochfahren (JVM-Startup + Datenbankinitialisierung). Nicht zu früh aufrufen. Logs mit docker logs keycloak -f beobachten und auf die „started“-Meldung warten.
7. Hoher RAM-Verbrauch / NAS reagiert langsam: Keycloak (JVM-basiert) kann 1–2 GB RAM beanspruchen. Auf NAS mit wenig freiem RAM die JVM-Heap-Größe begrenzen: Füge in der Compose-Datei unter environment die Variable JAVA_OPTS_KC_HEAP: "-Xms512m -Xmx1024m" hinzu.
8. Veraltete Umgebungsvariablen aus anderen Anleitungen: Variablen wie KEYCLOAK_USER, KEYCLOAK_PASSWORD, DB_VENDOR, DB_ADDR, DB_DATABASE und PROXY_ADDRESS_FORWARDING gehören zum Legacy-Image und funktionieren im aktuellen Image nicht.

Häufige Fragen

Was ist der Unterschied zu Authentik oder Authelia?

Authentik (Python/Go) und Authelia (Go) sind schlanker, einfacher einzurichten und benötigen deutlich weniger RAM. Keycloak (Java/Quarkus) ist der Enterprise-Standard: vollständiges SAML 2.0, detailliertes Realm- und Rollenmanagement, Federation via LDAP/Active Directory und bewährter Einsatz in Unternehmensumgebungen. Wer nur OIDC für Self-Hosted-Dienste im Heimnetz benötigt, ist mit Authentik oder Authelia oft besser bedient – dazu gibt es die Anleitung Single Sign-On für den Self-Hosted-Stack: Authentik vs. Authelia. Wer SAML-fähige Enterprise-Anwendungen anbinden will, kommt an Keycloak kaum vorbei.

Kann ich Keycloak ohne öffentliche Domain nur lokal betreiben?

Ja, mit Einschränkungen. KC_HOSTNAME kann auf eine lokale URL wie http://192.168.1.100:8711 gesetzt werden. Für rein lokale Anwendungen ist das ausreichend. Für OIDC/SAML mit Apps außerhalb des LANs (oder wenn Apps eine validierbare Discovery-URL erwarten) ist eine öffentliche Domain mit gültigem TLS-Zertifikat aber empfohlen.

Muss ich nach einem Keycloak-Update die Datenbank manuell migrieren?

Nein. Keycloak führt beim Start automatisch Datenbankmigrationen durch. Vor einem Update empfiehlt es sich dennoch, ein Backup des PostgreSQL-Volumes (/volume1/docker/keycloakdb) zu erstellen und die Keycloak-Release-Notes auf Breaking Changes zu prüfen.

Wie sichere ich die PostgreSQL-Datenbank regelmäßig?

Das PostgreSQL-Volume liegt unter /volume1/docker/keycloakdb. Du kannst es direkt als Datei-Backup sichern (Container dabei stoppen) oder pg_dump innerhalb des Containers nutzen:

docker exec keycloak-db pg_dump -U keycloakuser keycloak > /volume1/backup/keycloak-$(date +%Y%m%d).sql

Mehr zur Automatisierung und Rotation von Datenbank-Backups findest du in der Anleitung MySQL & PostgreSQL Backup automatisieren mit cron.

Wie viele Realms und Clients kann ich anlegen?

Technisch gibt es keine harte Begrenzung. In der Praxis ist auf einem Heim-NAS mit 4–8 GB RAM ein Realm mit 10–50 Clients gut handhabbar. Mehrere Realms (z.B. homelab, familie, firma) sind möglich und vollständig voneinander isoliert.

Wie aktualisiere ich Keycloak auf eine neue Version?

Den Image-Tag in der Compose-Datei auf die neue Version anpassen, vorher ein PostgreSQL-Backup erstellen, dann im Container Manager Projekt → Aktualisieren oder per SSH docker compose pull && docker compose up -d. Keycloak migriert das Datenbankschema beim ersten Start automatisch.

Fazit

Keycloak auf dem Synology NAS ist kein Leichtgewicht – weder bei der Konfiguration noch beim RAM-Verbrauch. Wer aber einen echten Enterprise-Identity-Provider mit vollständigem SAML 2.0, detailliertem Realm-Management und bewährtem Einsatz in Unternehmensumgebungen sucht, bekommt mit diesem Setup eine robuste Grundlage. Das Compose-Projekt mit PostgreSQL ist der einzig sinnvolle Weg für den Produktivbetrieb; der Dev-Mode mit H2-Datenbank taugt ausschließlich für schnelle lokale Tests. Die verifizierten Konfigurationsvariablen in dieser Anleitung entsprechen dem aktuellen Keycloak 26.x-Standard – ältere Anleitungen im Netz, die noch KEYCLOAK_USER, KC_PROXY oder das Legacy-Image verwenden, werden mit dem aktuellen Image nicht funktionieren.

Weiterführende Anleitungen und Quellen

1. Single Sign-On für den Self-Hosted-Stack: Authentik vs. Authelia mit Traefik Forward-Auth – die leichtgewichtige SSO-Alternative ohne SAML-Komplexität
2. Nginx Proxy Manager auf der Synology mit Container Manager einrichten – Reverse Proxy und SSL als Grundlage für Keycloak
3. MySQL & PostgreSQL Backup automatisieren mit cron – Keycloaks PostgreSQL-Datenbank regelmäßig sichern
4. Apache Guacamole auf dem Synology NAS installieren – weiterer Dienst im Batch, der von einem zentralen SSO profitiert

Offizielle Quellen: Keycloak Running in a Container (keycloak.org/server/containers), Keycloak Getting Started with Docker (keycloak.org), Keycloak Configuring the database (keycloak.org/server/db), GitHub Releases (github.com/keycloak/keycloak/releases).