Keycloak Quick Start: Schnell und sicher starten mit Docker

• Installiertes Docker (lokal oder remote)
• Internetzugang zum Laden des Images
• Ggf. Portfreigabe (8080 oder Alternative)

Schritt für Schritt: Keycloak starten mit Docker

1. Docker-Umgebung vorbereiten: Stellen Sie sicher, dass Docker installiert ist und läuft.

2. Terminal öffnen und folgenden Befehl ausführen:

docker run --name keycloak -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e
KC_BOOTSTRAP_ADMIN_PASSWORD=admin -p 8080:8080 -d quay.io/keycloak/keycloak:latest
start-dev

3. Keycloak-Container wird mit folgenden Eigenschaften gestartet:

1. Das Keycloak-Image in der Version 26.2.2 wird von quay.io/keycloak/keycloak heruntergeladen.
2. Der Benutzername und das Passwort für den Admin-Zugang werden über die Umgebungsvariablen
3. KC_BOOTSTRAP_ADMIN_USERNAME und KC_BOOTSTRAP_ADMIN_PASSWORD auf admin gesetzt.
4. Der Container-Port 8080 wird auf den Host-Port 8080 gemappt.

💡Hinweis: Sollte der Port 8080 bereits von einem anderen Dienst genutzt werden, kann der Host-Port angepasst werden, z. B. auf -p 9090:8080, um den Container-Port 8080 auf den Host-Port 9090 zu mappen. Nach erfolgreichem Start des Containers sollte ist die Admin-Oberfläche von Keycloak unter http://localhost:8080/ erreichbar.

4. Keycloak im Browser öffnen: http://localhost:8080

5. Anmelden mit Admin-Daten: Benutzername: admin / Passwort: admin

Nach der Anmeldung können Sie direkt Benutzer, Rollen, Clients und weitere Einstellungen verwalten.

Keycloak in Docker-Compose zur Authentifizierung und Datenbankanbindung via JDBC

Keycloak mit einer Datenbank betreiben – so geht´s

Bisher haben wir Keycloak ohne eine Datenbank verwendet. Keycloak kann und sollte mit einer externen Datenbank verwendet werden, um Daten wie Benutzerinformationen, Rollen und Sitzungen persistent zu speichern. Dies ist besonders wichtig in produktiven Umgebungen, damit die Daten bei einem Neustart des Containers nicht verloren gehen und mehrere Instanzen von Keycloak auf dieselbe Datenbank zugreifen und sich so synchronisieren können.

1. Netzwerk für die Container erstellen
Für unsere Test-Umgebung starten wir zunächst einen PostgreSQL-Container und ein Netzwerk:

docker network create keycloak-network
docker run --name keycloak-db --network keycloak-network -e POSTGRES_USER=keycloak
-e POSTGRES_PASSWORD=keycloak -e POSTGRES_DB=keycloak -d postgres:latest

2. PostgreSQL-Container starten
Dann können wir unseren alten Container beenden und einen neuen Container mit der Datenbankkonfiguration starten.

docker stop keycloak
docker run --name keycloak-with-database --network keycloak-network -e
KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin -e
KC_DB=postgres -e KC_DB_URL_HOST=keycloak-db -e KC_DB_USERNAME=keycloak -e
KC_DB_PASSWORD=keycloak -p 8080:8080 -d quay.io/keycloak/keycloak:latest start-dev

3. Vorherigen Keycloak-Container beenden (falls nötig):

docker stop <container-name>
docker rm <container-name>

4. Keycloak-Container mit DB-Anbindung starten

docker run --name keycloak --network keycloak-net \
-e KC_DB=postgres \
-e KC_DB_URL_HOST=keycloak-db \
-e KC_DB_USERNAME=keycloak \
-e KC_DB_PASSWORD=geheim \
-p 8080:8080 \
quay.io/keycloak/keycloak:26.2.2 start-dev

Was bedeuten die neuen Umgebungsvariablen?
Neu sind hier KC_DB, KC_DB_URL_HOST, KC_DB_USERNAME und KC_DB_PASSWORD. Mit KC_DB geben wir den verwendeten Datenbank-Driver an, in unserem Fall postgres. KC_DB_URL_HOST ist die Adresse der Datenbank, in unserem Fall der Name des PostgreSQL-Containers. KC_DB_USERNAME und KC_DB_PASSWORD sind die Anmeldedaten, die Keycloak verwendet, um auf die Datenbank zuzugreifen.

Keycloak via Docker Compose starten

Mit Docker Compose können Sie mehrere Container in einer Datei konfigurieren und starten.

1. Erstellen Sie eine Datei docker-compose.yaml mit folgendem Inhalt:

name: keycloak-quickstart

services:
  keycloak:
    image: quay.io/keycloak/keycloak:${TAG_KC}
    # start-dev, nicht in Produktivumgebungen
    command: start-dev
    depends_on:
      - db
    environment:
      # Datenbank-Konfiguration
      KC_DB: postgres
      KC_DB_URL_HOST: db
      KC_DB_USERNAME: ${DB_USER}
      KC_DB_PASSWORD: ${DB_PW}
      # Temporärer Admin für Ersteinrichtung
      KC_BOOTSTRAP_ADMIN_USERNAME: ${KC_ADMIN}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_ADMIN_PW}
    ports:
      #HTTP - Port. Produktiv nur TLS nutzen!
      - "8080:8080"

  db:
    image: postgres:${TAG_DB}
    restart: unless-stopped
    volumes:
      - postgresData:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PW}

volumes:
  # Backup-Strategie bedenken!
  postgresData: {}

2. Legen Sie zusätzlich eine .env-Datei an (optional aber empfohlen):
Hierbei ist es ebenfalls wichtig, entsprechende Secrets isoliert und geschützt zu verwalten.

# .env - Bitte ändere mich und nutze z.B. "SOPS: Secrets OPerationS" für Secrets

TAG_KC=26.2.2
TAG_DB=17.4
DB_USER=keycloak
DB_PW=helloKeycloak
KC_ADMIN=admin
KC_ADMIN_PW=helloKeycloak

💡 Hinweis: Ersetzen Sie die Platzhalter durch sichere Werte – vor allem für produktive Umgebungen.

3. Starten Sie die Umgebung:

Wenn Sie diese Datei in einem Verzeichnis als docker-compose.yaml und .env abspeichern und in diesem Verzeichnis docker compose up ausführen, werden die Keycloak- und PostgreSQL-Container gestartet.

Best Practices im Umgang mit Compose-Dateien

Versionskontrolle, wie zum Beispiel Git, nutzen:

• Verringert das Risiko, dass Konfigurationen verloren gehen.
• Ermöglicht Nachvollziehbarkeit, wann Änderungen gemacht wurden.

Keine Secrets wie Passwörter in der Compose-Datei hinterlegen:

• Für die produktive Nutzung sollten solche Secrets in einen Secrets-Manager oder eine separate .env-Datei ausgelagert werden. Diese .env-Datei kann dann außerhalb der Versionskontrolle geführt und zusätzlich abgesichert werden.
• Zusätzlich können so konfigurierbare Compose-Dateien erstellt werden, sodass die gleiche Datei für verschiedene Umgebungen verwendet werden kann.

Eine feste Versionsnummer der Images verwenden:

• Wenn eine Versionsangabe wie latest verwendet wird, besteht die Gefahr, dass bei einem Neustart ein unerwartetes Update durchgeführt wird. Außerdem geht die Nachvollziehbarkeit der Versionen verloren.
• Beim Dockerbetrieb ist auf eine Aufbewahrung der Protokollinformationen zu achten. Eine einfache journald oder professionellere Anbindung des ELK-Stacks bietet sich an.

Produktionsmodus vorbereiten – Typische Stolpersteine und Lösungen

Sie haben jetzt eine komplette lokale IAM-Testumgebung mit persistenter Datenhaltung und Wiederverwendbarkeit – bereit für erste Realms, Rollen, Clients und Testanwendungen. Doch sobald es Richtung Produktivbetrieb geht, steigen die Anforderungen.

Sicherheit, Verfügbarkeit, Compliance und Integrationen – all das gehört zu einer stabilen IAM-Architektur dazu. Keycloak bringt vieles schon mit. Die nötige Betriebssicherheit entsteht aber erst mit der richtigen Konfiguration. Bevor Sie in den Produktionsmodus wechseln, zeigen wir Ihnen typische Stolpersteine.

Häufige Fehler beim Wechsel in den Produktivmodus

Bevor Sie in den Produktionsmodus wechseln – typische Stolpersteine:

1. TLS-Konfiguration vergessen:
   • Ohne HTTPS bleibt die Kommunikation ungesichert – insbesondere bei externen Verbindungen ein Sicherheitsrisiko.
2. Hostname nicht festgelegt:
   • Im Produktivmodus muss ein Hostname gesetzt werden (KC_HOSTNAME).
   • Andernfalls bleibt Keycloak lokal erreichbar, aber nicht über eine feste Domain.
3. Kein Backup- und Restore-Konzept:
   • Produktivdaten benötigen ein Backup-Konzept, um Datenverlust zu vermeiden. PostgreSQL bietet z. B. automatische Dumps.
4. Keine Logging- und Monitoring-Strategie:
   • Überwachen Sie Anmeldeversuche und Fehler (journald, ELK Stack).
   • Ohne Logging bleiben Sicherheitsvorfälle unbemerkt.
5. Ports nicht angepasst:
   • Standardport 8080 kann zu Konflikten führen. Planen Sie alternative Ports oder Reverse Proxies ein.

Schritt für Schritt: Vom Testsystem zur produktiven Keycloak-Umgebung

Bisher haben wir unseren Keycloak-Container mit dem Befehl start-dev gestartet, wie der Name schonvermuten lässt, handelt es sich hierbei um den Entwicklungsmodus.

1. Wechsel vom Entwicklungs- in den Produktionsmodus: Um Keycloak im Produktionsmodus zu starten, muss der Befehl zu start geändert werden.

2. Setzen Sie einen festen Hostnamen: Da Keycloak dem Secure By Default-Prinzip folgt, ist der Produktionsmodus anspruchsvoller als der Entwicklungsmodus: Der Hostname, unter dem Keycloak erreicht werden kann, muss gesetzt werden. Hierfür kann die Umgebungsvariable KC_HOSTNAME verwendet werden.

3. TLS (HTTPS) aktivieren: TLS muss konfiguriert werden. Alternativ kann via KC_HTTP_ENABLED die Kommunikation via HTTP explizit erlaubt werden, wenn die TLS-Terminierung an einem Reverse Proxy durchgeführt wird.

💡 Jetzt, da Sie die typischen Stolpersteine kennen, lohnt sich ein Blick auf das Potenzial Ihrer produktionsreifen Umgebung. Denn mit dem richtigen Setup kann Ihre Keycloak-Instanz weit mehr leisten – von SSO über MFA bis zur Anbindung externer Systeme.

Use Cases: Was Ihre Keycloak-Umgebung jetzt leisten kann

1. Testen neuer Authentifizierungsprozesse: Setzen Sie Single Sign-On (SSO) für interne Anwendungen auf und prüfen Sie, wie nahtlos Nutzer zwischen verschiedenen Anwendungen wechseln können.
2. Mehrfaktor-Authentifizierung (MFA) einrichten: Verbinden Sie Keycloak mit YubiKeys, SMS oder anderen MFA-Lösungen, um die Sicherheitsstufe zu erhöhen.
3. Externe Verzeichnisdienste anbinden: Verbinden Sie Ihre Keycloak-Instanz mit einem Active Directory (AD), LDAP oder Azure AD – ideal für hybride IT-Landschaften.
4. OAuth2-Clients integrieren: Testen Sie die Integration einer Testanwendung via OAuth2 oder OpenID Connect und überprüfen Sie den Zugriff.
5. Datenbank-Backups testen: Überprüfen Sie Ihre PostgreSQL-Integration und richten Sie ein automatisiertes Backup ein.
6. Systemmonitoring aktivieren: Setzen Sie Monitoring-Tools wie Prometheus und Grafana auf, um Logins, Rollenänderungen und Fehler zu überwachen.

Fazit: Ihr Weg mit Keycloak – sicher, skalierbar, Open Source

Mit dem Keycloak Quick Start haben Sie erfolgreich den ersten Schritt gemacht. Die Einrichtung einer ersten Keycloak-Umgebung auf Docker-Basis ist schnell realisierbar.

Trotz der vorhandenen Online-Dokumentationen bleiben die Herausforderungen beim produktionstauglichen Einsatz von Keycloak jedoch vielseitig.

Hierzu zählen:

• der Umgang mit Konfigurationsparametern nach Updates,
• die DSGVO-konforme Protokollierung,
• die korrekte Anbindung von Drittanwendungen (Service-Providern),
• die Migration von älteren Keycloak-Ständen von Wildfly nach Quarkus,
• die Strukturfindung innerhalb von Keycloak (Realms),
• die Einrichtung von Mehrfaktor-Authentifizierungen wie YubiKeys oder SMS,
• die Anbindung von bereits vorhandenen Benutzerdatenquellen,
• die Vorkonfektionierung von Keycloak, Konfigurationen von Azure-Anbindungen und anderen Föderationen
• und nicht zuletzt der saubere Containerbetrieb samt horizontaler Skalierung.

Unsere Unterstützung: Von der Architektur bis zum laufenden Betrieb

Keycloak ist flexibel – aber komplex. Als IT-Partner mit fundierter IAM-Erfahrung helfen wir Ihnen, eine skalierbare, sichere und wartbare Lösung zu schaffen, sei es als Initialprojekt, Workshop oder laufender Support. Sie müssen nicht alles selbst konfigurieren, aber dauerhaft die Kontrolle behalten. Sprechen wir darüber: Vereinbaren Sie jetzt ein unverbindliches Erstgespräch – und erfahren Sie, wie Keycloak in Ihrer Umgebung zum zentralen IAM-Baustein wird.

Phillip Conrad

Segment Manager
p.conrad@smf.de

Bitte lasse dieses Feld leer.

Beratung anfragen

* Pflicht für alle Anfragen zu unseren Angeboten.

---

Weiterführende Links

Testen Sie Ihre Konfiguration auf Schwachstellen und Optimierungspotenziale mit unserem Keycloak Security Scanner.

Oder direkt produktiv durchstarten: vom Produktivsetup bis zur Integration. Vereinbaren Sie jetzt ein Gespräch mit unseren Experten.

---