TL;DR — Kurzzusammenfassung

Keycloak Komplett-Guide: Installation mit Docker, Realm-Konfiguration, OpenID Connect und SAML Clients, LDAP-Verbund, RBAC und Hochverfügbarkeit.

Keycloak ist die führende Open-Source-Lösung für Identity and Access Management (IAM) — sie bietet Single Sign-On (SSO), MFA, Social Login, LDAP/Active Directory-Verbund und feingranulare Autorisierung mit OpenID Connect, OAuth 2.0 und SAML 2.0. Dieser Guide deckt alles ab: von der Docker-Compose-Installation bis zu Realm-Konfiguration, RBAC, Identity Federation und Hochverfügbarkeits-Clustering.

Voraussetzungen

  • Docker 25+ und Docker Compose v2 (oder Kubernetes-Cluster für die Operator-Installation).
  • PostgreSQL 15+ für die Produktion (integriertes H2 ist nur für die Entwicklung geeignet).
  • Reverse Proxy (Nginx oder Traefik) für TLS-Terminierung in der Produktion.
  • Grundlegende Kenntnisse der OAuth-2.0-Konzepte (Client, Flows, Tokens).

Keycloak-Architektur

Keycloak organisiert alles in Realms — isolierte Sicherheitsdomänen:

KonzeptBeschreibung
RealmIsolierter Tenant. Enthält Benutzer, Clients, Rollen und Gruppen
ClientAnwendung, die für die Nutzung von Keycloak registriert ist
BenutzerIdentität im Realm (lokal oder föderiert)
RolleBerechtigungslabel. Realm-Rollen oder Client-Rollen
GruppeBenutzersammlung mit vererbten Rollen
Identity ProviderExterner IdP (Google, GitHub, SAML, LDAP)
AuthentifizierungsflussKonfigurierbarer Flow: Login, OTP, WebAuthn

Der Master-Realm ist der Super-Admin — verwenden Sie ihn nur zur Verwaltung anderer Realms, nie für Anwendungsbenutzer.

Schritt 1: Keycloak mit Docker Compose installieren

version: "3.9"
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres_data:/var/lib/postgresql/data

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: changeme
      KC_HOSTNAME: auth.beispiel.com
      KC_PROXY: edge
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: adminpass
    ports:
      - "8080:8080"
    depends_on:
      - postgres

volumes:
  postgres_data:
docker compose up -d
# Admin-Konsole unter http://localhost:8080 aufrufen

Schritt 2: Realm-Konfiguration

EinstellungEmpfohlener Wert
AnzeigenameIhr Markenname
Login-Themekeycloak oder benutzerdefiniert
SSL erforderlichexternal requests (Produktion)
SSO-Sitzungsleerlauf30 Minuten
Zugriffstoken-Lebensdauer5 Minuten

Konfigurieren Sie SMTP unter Realm-Einstellungen → E-Mail für Passwort-Reset-E-Mails.

Schritt 3: OpenID Connect Client-Konfiguration

Clients → Client erstellen:

  • Client-Typ: OpenID Connect
  • Client-ID: myapp-client
  • Client-Authentifizierung: An (vertraulich) für Server-Apps; Aus (öffentlich) für SPAs
  • Gültige Redirect-URIs: https://myapp.beispiel.com/callback
  • Web Origins: https://myapp.beispiel.com

Vertrauliche vs. Öffentliche Clients

MerkmalVertraulichÖffentlich
Hat Client-SecretJaNein
AnwendungsfallServer (Node, .NET, Python)SPA, mobile App
Auth-Code-FlowMit SecretMit PKCE

Schritt 4: Rollenbasierte Zugriffskontrolle (RBAC)

# Realm-Rolle mit kcadm.sh erstellen
kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin --password adminpass

kcadm.sh create roles -r myapp -s name=app-admin
kcadm.sh create roles -r myapp -s name=app-user

Empfohlener Ablauf: Rollen → Gruppen → Benutzer. Weisen Sie Rollen Gruppen zu und fügen Sie Benutzer den Gruppen hinzu.

Zusammengesetzte Rollen bündeln andere Rollen: Erstellen Sie superbenutzer und fügen Sie app-admin und app-user als Composites hinzu.

Schritt 5: Identity Federation

Social Login (Google, GitHub, Microsoft)

Identity Providers → Provider hinzufügen → Google:

  1. Erstellen Sie eine OAuth-2.0-App in der Google Cloud Console.
  2. Geben Sie Client-ID und Client-Secret von Google in Keycloak ein.
  3. Redirect-URI: https://auth.beispiel.com/realms/myapp/broker/google/endpoint.

LDAP / Active Directory-Verbund

EinstellungWert
AnbieterActive Directory
Verbindungs-URLldap://ad.corp.beispiel.com
Bind-DNCN=svc-keycloak,OU=Dienstkonten,DC=corp,DC=beispiel,DC=com
Benutzer-DNOU=Benutzer,DC=corp,DC=beispiel,DC=com
SynchronisierungsmodusFORCE

Führen Sie Alle Benutzer synchronisieren aus, um AD-Benutzer zu importieren.

Schritt 6: Authentifizierungsflows und MFA

TOTP und WebAuthn

Für TOTP: Authentifizierung → Flows → browser → Duplizieren → OTP-Formular als ERFORDERLICH hinzufügen.

Für WebAuthn/Passkeys (Keycloak 22+):

  1. Authentifizierung → Richtlinien → WebAuthn-Richtlinie — setzen Sie die Domain als Relying Party ID.
  2. Fügen Sie WebAuthn-Authenticator zum Browser-Flow hinzu.

Hochverfügbarkeit

environment:
  KC_CACHE: ispn
  KC_CACHE_STACK: jdbc-ping
  KC_DB: postgres
  KC_DB_URL: jdbc:postgresql://pgpool/keycloak
  • Aktivieren Sie Sticky Sessions am Load Balancer (Cookie AUTH_SESSION_ID).
  • Health-Endpunkt: GET /health/ready.

Keycloak vs. Alternativen

FunktionKeycloakAuthentikAutheliaAuth0OktaFusionAuth
Open-SourceJaJaJaNeinNeinTeilweise
Self-hostedJaJaJaNeinNeinJa
SAML 2.0JaJaNeinJaJaJa
LDAP-VerbundJaJaNeinJaJaJa
Feingranulare AuthzJa (UMA)NeinNeinJa (kostenpflichtig)Ja (kostenpflichtig)Teilweise
KomplexitätHochMittelNiedrigNiedrigNiedrigMittel

Fehlerbehebung

ProblemLösung
”Invalid redirect_uri”Prüfen Sie gültige Redirect-URIs — exakte Übereinstimmung erforderlich
”Client secret not valid”Regenerieren Sie das Secret unter Clients → Zugangsdaten
Login-SchleifePrüfen Sie ob KC_HOSTNAME mit der tatsächlichen URL übereinstimmt
E-Mail wird nicht gesendetSMTP in Realm-Einstellungen → E-Mail prüfen
LDAP-Benutzer nicht synchronisiertBind-Zugangsdaten prüfen und manuelle Synchronisation ausführen

Zusammenfassung

  • Realms isolieren Tenants — verwenden Sie immer einen dedizierten Realm für Anwendungen.
  • Vertrauliche Clients verwenden Secrets; öffentliche nutzen PKCE.
  • Gruppen mit Rollen skalieren das RBAC — vermeiden Sie die direkte Rollenzuweisung an Benutzer.
  • Die LDAP-Synchronisation mit FORCE-Modus hält AD als maßgebliche Quelle.
  • Verwenden Sie KC_CACHE=ispn mit jdbc-ping für HA ohne zusätzliche Abhängigkeiten.

Verwandte Artikel