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

Ohne zentrale Anmeldung pflegen Sie für jeden selbst gehosteten Dienst ein eigenes Konto. Keycloak ist ein Open-Source-Identity-Provider (IdP), der Single Sign-On (SSO) über OpenID Connect (OIDC) und SAML 2.0 bereitstellt. Diese Anleitung richtet Keycloak als Projekt im Container Manager mit PostgreSQL als Datenbank ein. Der Dev-Mode (start-dev) mit eingebetteter H2-Datenbank ist laut Hersteller nur für Tests gedacht und scheidet für den Betrieb aus.

Voraussetzungen

1. Synology NAS mit DSM 7.2 oder neuer und installiertem Container Manager
2. Mindestens 4 GB RAM im NAS (Keycloak laut Hersteller mindestens 750 MB, empfohlen 2 GB, dazu PostgreSQL)
3. x86_64- oder ARM64-CPU (das Image ist für amd64 und arm64 verfügbar)
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 TLS-Zertifikat (Let’s Encrypt über den Nginx Proxy Manager)
6. SSH-Zugang zum NAS: nur für Log-Ausgaben und Datenbank-Backup nötig, die DSM-Oberfläche zeigt diese nicht vollständig
7. Grundkenntnisse in Docker Compose

Schritt 1: Verzeichnisstruktur anlegen

Keycloak und PostgreSQL schreiben ihre Daten in getrennte Verzeichnisse unter /volume1/docker. Diese müssen vor dem ersten Start existieren.

Per SSH (als Administrator):

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

Alternativ in der File Station: Öffnen Sie File Station → docker, erstellen Sie den Ordner keycloak mit den Unterordnern data und themes sowie den Ordner keycloakdb auf gleicher Ebene.

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

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

Erwartetes Ergebnis: Die Verzeichnisse data, themes und keycloakdb sind vorhanden und leer.

Schritt 2: Compose-Projekt im Container Manager anlegen

Öffnen Sie im DSM Container Manager → Projekt → Erstellen. Vergeben Sie den Projektnamen keycloak, wählen Sie als Pfad /volume1/docker/keycloak und fügen Sie folgende compose.yaml ein. Ersetzen Sie die Passwörter und den Hostnamen:

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.7.4
    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.ihre-domain.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 Hinweise zur Compose-Datei:

1. Image: Das offizielle Image liegt auf quay.io, nicht auf Docker Hub. Schreiben Sie die Version fest (hier 26.7.4, Stand September 2026) und prüfen Sie vor Updates die Release Notes. :latest kann ungeplant eine neue Minor- oder Major-Version einspielen.
2. Sonderzeichen in Passwörtern: Compose wertet $ als Variablenreferenz aus. Verwenden Sie in Passwörtern kein $ oder schreiben Sie es als $$.
3. command: start: Ohne diesen Befehl bleibt Keycloak im Dev-Mode mit H2-Datenbank. Für den Betrieb ist start Pflicht.

Verifizieren: Klicken Sie im Container Manager auf „Erstellen“. Beide Container (keycloak-db und keycloak) zeigen nach 30 bis 90 Sekunden den Status Läuft. Keycloak startet erst, wenn PostgreSQL den Healthcheck bestanden hat (depends_on mit condition: service_healthy). Prüfen Sie die Logs:

docker logs keycloak -f

Erwartete Ausgabe (letzte Zeilen):

Keycloak 26.7.4 on JVM (powered by Quarkus ...) started in ...
Listening on: http://0.0.0.0:8080. Management interface listening on http://0.0.0.0:9000.

Beim ersten Start initialisiert Keycloak das Datenbankschema; das dauert bis zu 90 Sekunden.

Schritt 3: Nginx Proxy Manager konfigurieren

Port 8711 soll nicht direkt aus dem Internet erreichbar sein. Der Nginx Proxy Manager terminiert TLS und setzt die Forwarded-Header, ohne die Keycloak falsche Redirect-URLs erzeugt.

Öffnen Sie im Nginx Proxy Manager → Proxy Hosts → Add Proxy Host:

1. Domain Names: keycloak.ihre-domain.de
2. Scheme: http
3. Forward Hostname / IP: die LAN-IP des NAS (nicht localhost: im NPM-Container zeigt localhost auf den Container selbst)
4. Forward Port: 8711
5. Websockets Support: aktiviert

Stellen Sie im Tab SSL ein Let’s-Encrypt-Zertifikat aus und aktivieren Sie „Force SSL“. Fügen Sie im Tab Advanced folgende Nginx-Konfiguration ein:

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 größeren Puffer verhindern 502-Fehler: Keycloak sendet große Header (Token, Session-Cookies).

Verifizieren: Öffnen Sie https://keycloak.ihre-domain.de im Browser. Die Keycloak-Startseite mit dem Link zur Admin-Konsole erscheint, der Browser zeigt ein gültiges Zertifikat. Erscheint „HTTPS required“, fehlt KC_HTTP_ENABLED oder KC_PROXY_HEADERS, oder der Proxy Host ist noch nicht gespeichert.

Schritt 4: Admin-Konsole aufrufen und sichern

Rufen Sie https://keycloak.ihre-domain.de/admin auf und melden Sie sich mit den Werten aus KC_BOOTSTRAP_ADMIN_USERNAME und KC_BOOTSTRAP_ADMIN_PASSWORD an.

Das Bootstrap-Konto ist als temporäres Konto gedacht. Ersetzen Sie es sofort:

1. Wechseln Sie oben links in den Realm master.
2. Legen Sie unter Users → Add user einen neuen Benutzer an (z. B. keycloak-admin).
3. Weisen Sie unter Role mapping die Rolle admin zu.
4. Setzen Sie unter Credentials ein starkes Passwort.
5. Melden Sie sich mit dem neuen Konto an und löschen Sie danach den Bootstrap-Benutzer unter Users → admin → Delete.

Entfernen Sie anschließend KC_BOOTSTRAP_ADMIN_USERNAME und KC_BOOTSTRAP_ADMIN_PASSWORD aus der Compose-Datei und starten Sie das Projekt neu. Sonst bleibt das Passwort im Klartext in der Konfiguration.

Verifizieren: Melden Sie sich mit dem neuen Admin-Konto an. Die Admin-Konsole lädt vollständig und zeigt links das Menü mit Realm settings, Clients, Users. Unter Users im Realm master fehlt der Benutzer admin.

Schritt 5: Eigenen Realm anlegen

Der Realm master dient nur der Verwaltung. Für Ihre Anwendungen legen Sie einen eigenen Realm an, z. B. homelab.

1. Klicken Sie oben links auf die Realm-Auswahl und wählen Sie Create realm.
2. Vergeben Sie einen Namen, z. B. homelab, und klicken Sie Create.
3. Unter Realm settings → General passen Sie den Anzeigenamen an.
4. Unter Realm settings → Login aktivieren Sie bei Bedarf Benutzerregistrierung, „Forgot password“ und E-Mail-Verifizierung.
5. Legen Sie unter Users → Add user einen Test-Benutzer an und setzen Sie unter Credentials ein Passwort (Temporary auf „Off“).

Verifizieren: Öffnen Sie die OIDC-Discovery-URL des neuen Realms im Browser:

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

Erwartetes Ergebnis: ein JSON-Dokument mit authorization_endpoint, token_endpoint und userinfo_endpoint, jeweils mit Ihrer HTTPS-Domain.

Schritt 6: OIDC-Test-Client anlegen und verifizieren

Ein Client steht in Keycloak für eine Anwendung, die sich über Keycloak anmeldet. Das Vorgehen ist für Nextcloud, Gitea und Grafana gleich.

1. Wählen Sie Ihren Realm (z. B. homelab) und öffnen Sie Clients → Create client.
2. Client type: OpenID Connect
3. Client ID: z. B. nextcloud oder test-client
4. Klicken Sie Next und aktivieren Sie Client authentication (vertraulicher Client mit Client Secret).
5. Tragen Sie unter Valid redirect URIs die Callback-URL der Anwendung ein, z. B. https://nextcloud.ihre-domain.de/apps/oidc_login/oidc. Für den Test reicht https://ihre-app.example.com/*.
6. Speichern Sie den Client.
7. Kopieren Sie im Tab Credentials das Client Secret für die Konfiguration der Anwendung.

Die Anwendung braucht folgende Werte:

Verifizieren: Rufen Sie die Autorisierungs-URL im Browser auf (CLIENT_ID und REDIRECT_URI anpassen):

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

Erwartetes Ergebnis: Die Keycloak-Anmeldeseite erscheint. Nach der Anmeldung mit dem Test-Benutzer leitet Keycloak zur redirect_uri mit einem Parameter code weiter.

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

SAML 2.0 brauchen Sie vor allem für Anwendungen wie Jira, Confluence oder Nextcloud mit SAML-Anmeldung. Authelia bietet keinen SAML-Provider, Authentik schon. Der Ablauf ähnelt dem OIDC-Client:

1. Erstellen Sie unter Clients → Create client einen Client mit Client type: SAML.
2. Tragen Sie als Client ID die Entity ID der Anwendung ein (meist eine URL, z. B. https://jira.ihre-domain.de).
3. Setzen Sie Valid redirect URIs auf die ACS-URL (Assertion Consumer Service) der Anwendung.
4. Hinterlegen Sie in der Anwendung die SAML-Metadaten-URL von Keycloak:

https://keycloak.ihre-domain.de/realms/homelab/protocol/saml/descriptor

Verifizieren: Öffnen Sie die Metadaten-URL im Browser. Erwartetes Ergebnis: ein XML-Dokument mit dem Element <EntityDescriptor> und den SAML-Endpunkten des Realms.

Eckdaten auf einen Blick

Troubleshooting: typische Fehler

1. „Database not available“, Keycloak startet nicht: PostgreSQL war beim Start von Keycloak noch nicht bereit. Prüfen Sie, ob der healthcheck im Dienst db und depends_on mit condition: service_healthy gesetzt sind.
2. „Invalid parameter: redirect_uri“: Die Callback-URL der Anwendung steht nicht unter Valid redirect URIs des Clients. Betrifft der Fehler die Admin-Konsole, stimmt KC_HOSTNAME nicht exakt mit der aufgerufenen URL überein (vollständig mit https://, ohne abschließenden Schrägstrich).
3. „HTTPS required“: Der Produktionsmodus verlangt HTTPS. Hinter einem Proxy, der TLS terminiert und intern HTTP weitergibt, sind KC_HTTP_ENABLED=true und KC_PROXY_HEADERS=xforwarded Pflicht.
4. Admin-Konsole lädt nicht hinter dem Reverse Proxy: KC_PROXY_HEADERS fehlt. Die Option KC_PROXY (Werte wie edge) ist seit Keycloak 24 veraltet und in Version 26 entfernt.
5. Datenbankpasswort mit Sonderzeichen funktioniert nicht: siehe Hinweis 2 in Schritt 2.
6. Zeitüberschreitung beim ersten Aufruf: Warten Sie in docker logs keycloak -f auf die Meldung „started“ (30 bis 90 Sekunden).
7. Hoher RAM-Verbrauch, NAS reagiert langsam: Ohne Speicherlimit darf der Java-Heap bis 70 % des verfügbaren Speichers wachsen. Begrenzen Sie ihn in der Compose-Datei unter environment, z. B. mit JAVA_OPTS_KC_HEAP: "-Xms512m -Xmx1024m".
8. Veraltete Umgebungsvariablen aus anderen Anleitungen: KEYCLOAK_USER, KEYCLOAK_PASSWORD, DB_VENDOR, DB_ADDR, DB_DATABASE und PROXY_ADDRESS_FORWARDING gehören zum alten WildFly-Image und wirken im aktuellen Image nicht.

Häufige Fragen

Was ist der Unterschied zu Authentik oder Authelia?

Authentik und Authelia sind schlanker und brauchen deutlich weniger RAM. Authelia beherrscht OIDC, aber kein SAML. Keycloak (Java/Quarkus) bietet SAML 2.0, feingranulares Realm- und Rollenmanagement sowie Anbindung an LDAP und Active Directory. Für OIDC-Anmeldung an Heimnetz-Diensten reicht oft Authentik oder Authelia, siehe Single Sign-On für den Self-Hosted-Stack: Authentik vs. Authelia.

Kann ich Keycloak ohne öffentliche Domain nur lokal betreiben?

Ja, mit Einschränkungen. KC_HOSTNAME kann eine lokale URL wie http://192.168.1.100:8711 sein. Für Anwendungen außerhalb des LANs oder solche, die eine Discovery-URL mit gültigem Zertifikat erwarten, brauchen Sie eine Domain mit TLS-Zertifikat.

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

Nein, das Schema migriert Keycloak beim Start automatisch. Sichern Sie vorher die Datenbank und lesen Sie die Release Notes.

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

Sichern Sie das Verzeichnis /volume1/docker/keycloakdb bei gestopptem Container oder erstellen Sie im laufenden Betrieb einen Dump:

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

Automatisierung und Rotation beschreibt die Anleitung MySQL & PostgreSQL Backup automatisieren mit cron.

Wie viele Realms und Clients kann ich anlegen?

Keycloak setzt keine feste Grenze. Auf einem NAS mit 4 bis 8 GB RAM ist ein Realm mit 10 bis 50 Clients gut handhabbar; mehrere Realms sind vollständig voneinander getrennt.

Wie aktualisiere ich Keycloak auf eine neue Version?

Erstellen Sie ein Datenbank-Backup, ändern Sie den Image-Tag in der Compose-Datei und bauen Sie das Projekt im Container Manager neu, oder per SSH im Projektordner docker compose pull && docker compose up -d.

Fazit

Keycloak braucht mehr Konfiguration und RAM als Authentik oder Authelia. Dafür erhalten Sie SAML 2.0, getrennte Realms und LDAP-Anbindung. Für den Betrieb ist das Compose-Projekt mit PostgreSQL und command: start der richtige Weg.

Weiterführende Anleitungen und Quellen

1. Single Sign-On für den Self-Hosted-Stack: Authentik vs. Authelia mit Traefik Forward-Auth: die schlankere SSO-Alternative
2. Nginx Proxy Manager auf der Synology mit Container Manager einrichten: Reverse Proxy und TLS als Grundlage
3. MySQL & PostgreSQL Backup automatisieren mit cron: die Keycloak-Datenbank regelmäßig sichern
4. Apache Guacamole auf dem Synology NAS installieren: ein weiterer Dienst, der von zentralem 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), Keycloak Using a reverse proxy (keycloak.org/server/reverseproxy), GitHub Releases (github.com/keycloak/keycloak/releases).