Keycloak ist ein leistungsstarkes, Open-Source Identity and Access Management System (IAM), das Single Sign-On (SSO), OAuth 2.0, OpenID Connect und viele weitere Authentifizierungs- und Autorisierungsfunktionen bietet. In diesem Tutorial zeige ich dir, wie du Keycloak mit Docker und PostgreSQL einrichtest und in Betrieb nimmst.

Was ist Keycloak?

Keycloak ist eine umfassende Lösung für die Verwaltung von Benutzeridentitäten und Zugriffsrechten. Es ermöglicht dir:

  • Single Sign-On (SSO) zwischen verschiedenen Anwendungen
  • OAuth 2.0 und OpenID Connect für moderne Authentifizierungsflows
  • Social Login Integration (Google, Facebook, GitHub, etc.)
  • Benutzerverwaltung mit Self-Service-Registrierung
  • Rollen- und Rechteverwaltung (RBAC)
  • Zwei-Faktor-Authentifizierung (2FA)
  • Token-Management für JWT und SAML

Voraussetzungen

Bevor wir mit der Installation beginnen, stelle sicher, dass du folgende Tools auf deinem System installiert hast:

Installation prüfen

Überprüfe, ob Docker und Docker Compose installiert sind:

docker --version
docker compose version

Schritt 1: Repository klonen

Klone das Keycloak Docker-Setup Repository:

git clone https://gitlab.com/pazdzewicz_docker/keycloak
cd keycloak

Dieses Repository enthält eine vorkonfigurierte Docker Compose-Datei für Keycloak mit PostgreSQL.

Schritt 2: Docker Images herunterladen

Lade die notwendigen Docker Images herunter:

docker compose pull

Dieser Befehl lädt die neuesten Images für Keycloak und PostgreSQL herunter. Je nach Internetverbindung kann dies einige Minuten dauern.

Schritt 3: Umgebungsvariablen konfigurieren

Erstelle eine .env Datei basierend auf der env.template Datei im Repository:

cp env.template .env

Öffne die .env Datei und passe die Werte an deine Bedürfnisse an. Hier sind die wichtigsten Konfigurationsoptionen:

Umgebungsvariablen im Detail

Die docker-compose.yml Datei verwendet folgende Umgebungsvariablen:

environment:
  JAVA_OPTS_APPEND: "${JAVA_OPTS_APPEND}"
  KC_HEALTH_ENABLED: "${KC_HEALTH_ENABLED}"
  KC_HTTP_ENABLED: "${KC_HTTP_ENABLED}"
  KC_METRICS_ENABLED: "${KC_METRICS_ENABLED}"
  KC_FEATURES: "${KC_FEATURES}"
  KC_FEATURES_DISABLED: "${KC_FEATURES_DISABLED}"
  KC_HOSTNAME_URL: "${KC_HOSTNAME_URL}"
  KC_PROXY: "${KC_PROXY}"
  KC_DB: "${KC_DB}"
  KC_DB_URL: "${KC_DB_URL}"
  KC_DB_USERNAME: "${KC_DB_USERNAME}"
  KC_DB_PASSWORD: "${KC_DB_PASSWORD}"
  KEYCLOAK_ADMIN: "${KEYCLOAK_ADMIN}"
  KEYCLOAK_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD}"

Wichtige Konfigurationsoptionen

Java-Optionen:

  • JAVA_OPTS_APPEND: Zusätzliche JVM-Parameter (z.B. für Memory-Einstellungen)

Health & Monitoring:

  • KC_HEALTH_ENABLED: Aktiviert Health-Check-Endpunkte (Standard: true)
  • KC_METRICS_ENABLED: Aktiviert Metriken-Endpunkte (Standard: false)

Netzwerk & Proxy:

  • KC_HTTP_ENABLED: Aktiviert HTTP-Zugriff (Standard: true)
  • KC_HOSTNAME_URL: Die öffentliche URL deines Keycloak-Servers
  • KC_PROXY: Proxy-Modus (edge, reencrypt, passthrough, none)

Datenbank:

  • KC_DB: Datenbanktyp (postgres, mysql, mariadb, etc.)
  • KC_DB_URL: JDBC-Verbindungs-URL zur Datenbank
  • KC_DB_USERNAME: Datenbank-Benutzername
  • KC_DB_PASSWORD: Datenbank-Passwort

Administration:

  • KEYCLOAK_ADMIN: Admin-Benutzername für Keycloak
  • KEYCLOAK_ADMIN_PASSWORD: Admin-Passwort für Keycloak

Features:

  • KC_FEATURES: Zu aktivierende Features (kommagetrennt)
  • KC_FEATURES_DISABLED: Zu deaktivierende Features (kommagetrennt)

Beispiel .env Datei

# Java Options
JAVA_OPTS_APPEND="-Xms512m -Xmx1024m"

# Health & Monitoring
KC_HEALTH_ENABLED=true
KC_METRICS_ENABLED=true

# Network
KC_HTTP_ENABLED=true
KC_HOSTNAME_URL=http://localhost:8080
KC_PROXY=edge

# Database
KC_DB=postgres
KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=change_me_secure_password

# Admin Credentials
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=change_me_admin_password

# Features
KC_FEATURES=token-exchange,admin-fine-grained-authz
KC_FEATURES_DISABLED=

Sicherheitshinweis: Ändere die Passwörter in deiner .env Datei! Verwende starke, eindeutige Passwörter für Production-Umgebungen.

Schritt 4: Keycloak starten

Starte die Keycloak-Container im Hintergrund:

docker compose up -d

Der -d Flag startet die Container im Detached-Modus (im Hintergrund). Du kannst den Status der Container mit folgendem Befehl überprüfen:

docker compose ps

Die Container sollten jetzt laufen. Keycloak ist standardmäßig unter http://localhost:8080 erreichbar.

Schritt 5: Erste Anmeldung

Nachdem Keycloak gestartet ist, öffne deinen Browser und navigiere zu:

http://localhost:8080

Du wirst zur Keycloak-Administrationskonsole weitergeleitet. Melde dich mit den in deiner .env Datei konfigurierten Admin-Credentials an:

  • Benutzername: Der Wert von KEYCLOAK_ADMIN
  • Passwort: Der Wert von KEYCLOAK_ADMIN_PASSWORD

SSL/HTTPS Setup

Für Production-Umgebungen wird dringend empfohlen, HTTPS zu verwenden. Eine bewährte Methode ist, einen Reverse-Proxy wie Traefik vor Keycloak zu betreiben.

Warum Traefik?

Traefik bietet:

  • Automatische SSL-Zertifikate mit Let’s Encrypt
  • Reverse-Proxy-Funktionalität
  • Load Balancing
  • Einfache Konfiguration über Labels

Keycloak hinter einem Reverse-Proxy

Wenn du Keycloak hinter einem Reverse-Proxy betreibst, setze KC_PROXY entsprechend:

  • edge: Proxy terminiert SSL, Keycloak läuft auf HTTP (häufigste Konfiguration)
  • reencrypt: Proxy terminiert SSL und verschlüsselt erneut zu Keycloak
  • passthrough: Proxy leitet SSL-Traffic durch
  • none: Kein Proxy (nur für Entwicklung)

Stelle sicher, dass KC_HOSTNAME_URL auf die öffentliche HTTPS-URL zeigt.

Keycloak Administration über CLI

Keycloak bietet umfangreiche CLI-Tools für die Administration. Du kannst in den Keycloak-Container eintreten und diese Tools verwenden.

In den Container eintreten

docker compose exec -it keycloak bash

Oder direkt zum _bin Verzeichnis:

docker compose exec -it keycloak /bin/bash

kc.sh verwenden

Das kc.sh Skript ist das Hauptwerkzeug für die Keycloak-Administration über die CLI:

cd /opt/keycloak
./bin/kc.sh --help

Verfügbare CLI-Kommandos

Keycloak bietet verschiedene Kommandos für die Administration:

Realm-Verwaltung:

  • Realm exportieren: ./bin/kc.sh export --realm myrealm
  • Realm importieren: ./bin/kc.sh import --file /path/to/realm.json

Datenbank-Verwaltung:

  • Datenbank exportieren: Backup-Skripte im _bin/ Verzeichnis
  • Datenbank importieren: Restore-Skripte im _bin/ Verzeichnis

Nützliche Skripte im _bin/ Verzeichnis

Das Repository enthält verschiedene nützliche Skripte:

  • Realm Export/Import: Automatisierte Realm-Verwaltung
  • Datenbank Backup: Regelmäßige Backups für Disaster Recovery
  • Konfigurationsmanagement: Skripte zur Konfigurationsverwaltung

Diese Skripte sind besonders nützlich für:

  • Regelmäßige Backups mit Tools wie Restic oder ähnlichen Backup-Lösungen
  • Automatisierte Deployments in CI/CD-Pipelines
  • Disaster Recovery Szenarien

Container-Logs überwachen

Um die Logs von Keycloak zu überprüfen:

docker compose logs -f keycloak

Für alle Container gleichzeitig:

docker compose logs -f

Erste Schritte mit Keycloak

Nach der erfolgreichen Installation kannst du:

  1. Einen Realm erstellen: Ein Realm ist ein isolierter Bereich für Benutzer, Clients und Konfigurationen
  2. Clients konfigurieren: Registriere deine Anwendungen als Clients
  3. Benutzer erstellen: Füge Benutzer manuell hinzu oder aktiviere Self-Registration
  4. Rollen definieren: Erstelle Rollen und weise sie Benutzern zu
  5. Identity Provider verbinden: Integriere Social Login oder andere Identity Provider

Häufige Probleme und Lösungen

Problem: Container startet nicht

Lösung:

  • Überprüfe die Logs: docker compose logs keycloak
  • Stelle sicher, dass der PostgreSQL-Container läuft: docker compose ps
  • Überprüfe die .env Datei auf korrekte Werte

Problem: Datenbankverbindungsfehler

Lösung:

  • Überprüfe, ob PostgreSQL läuft: docker compose ps postgres
  • Verifiziere die Datenbank-Credentials in der .env Datei
  • Stelle sicher, dass KC_DB_URL korrekt formatiert ist

Problem: Port bereits belegt

Lösung:

  • Finde den Prozess, der Port 8080 verwendet: sudo lsof -i :8080
  • Ändere den Port in der docker-compose.yml Datei
  • Oder beende den konfliktierenden Prozess

Problem: Admin-Login funktioniert nicht

Lösung:

  • Überprüfe, ob die Admin-Credentials in der .env Datei korrekt sind
  • Stelle sicher, dass der Container vollständig gestartet ist
  • Warte einige Sekunden nach dem Start, bevor du dich anmeldest

Problem: Keycloak startet sehr langsam

Lösung:

  • Erhöhe die Java Memory-Optionen: JAVA_OPTS_APPEND="-Xms1024m -Xmx2048m"
  • Überprüfe die verfügbaren Systemressourcen
  • Stelle sicher, dass die Datenbank schnell genug ist

Best Practices

  1. Sicherheit:
    • Verwende starke Passwörter für Admin- und Datenbank-Zugänge
    • Setze Keycloak hinter einen Reverse-Proxy mit SSL
    • Aktualisiere Keycloak regelmäßig auf die neueste Version
  2. Backups:
    • Führe regelmäßige Backups der Datenbank durch
    • Exportiere wichtige Realms regelmäßig
    • Teste die Wiederherstellung von Backups
  3. Monitoring:
    • Aktiviere Health-Checks: KC_HEALTH_ENABLED=true
    • Aktiviere Metriken: KC_METRICS_ENABLED=true
    • Überwache Container-Logs regelmäßig
  4. Performance:
    • Passe Java Memory-Optionen an deine Hardware an
    • Verwende eine leistungsstarke Datenbank
    • Cache-Konfiguration für Production optimieren

Nächste Schritte

Nach erfolgreicher Installation kannst du:

  1. Realms konfigurieren: Richte deine ersten Realms ein
  2. Clients registrieren: Verbinde deine Anwendungen mit Keycloak
  3. Social Login aktivieren: Integriere Google, GitHub oder andere Provider
  4. Custom Themes erstellen: Passe das Aussehen der Login-Seiten an
  5. User Federation einrichten: Verbinde externe User-Datenbanken

Fazit

Dieses Setup bietet dir eine solide Grundlage für die Verwendung von Keycloak mit Docker und PostgreSQL. Mit dieser Konfiguration hast du eine vollständig funktionsfähige Identity-Management-Lösung, die du nach deinen Bedürfnissen anpassen kannst.

Für fortgeschrittene Konfigurationen und Features schaue in die offizielle Keycloak-Dokumentation.

Viel Erfolg mit deinem Keycloak-Setup! 🔐