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:

Konzept Beschreibung
Realm Isolierter Tenant. Enthält Benutzer, Clients, Rollen und Gruppen
Client Anwendung, die für die Nutzung von Keycloak registriert ist
Benutzer Identität im Realm (lokal oder föderiert)
Rolle Berechtigungslabel. Realm-Rollen oder Client-Rollen
Gruppe Benutzersammlung mit vererbten Rollen
Identity Provider Externer IdP (Google, GitHub, SAML, LDAP)
Authentifizierungsfluss Konfigurierbarer 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

Einstellung Empfohlener Wert
Anzeigename Ihr Markenname
Login-Theme keycloak oder benutzerdefiniert
SSL erforderlich external requests (Produktion)
SSO-Sitzungsleerlauf 30 Minuten
Zugriffstoken-Lebensdauer 5 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

Merkmal Vertraulich Öffentlich
Hat Client-Secret Ja Nein
Anwendungsfall Server (Node, .NET, Python) SPA, mobile App
Auth-Code-Flow Mit Secret Mit 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

Einstellung Wert
Anbieter Active Directory
Verbindungs-URL ldap://ad.corp.beispiel.com
Bind-DN CN=svc-keycloak,OU=Dienstkonten,DC=corp,DC=beispiel,DC=com
Benutzer-DN OU=Benutzer,DC=corp,DC=beispiel,DC=com
Synchronisierungsmodus FORCE

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

Funktion Keycloak Authentik Authelia Auth0 Okta FusionAuth
Open-Source Ja Ja Ja Nein Nein Teilweise
Self-hosted Ja Ja Ja Nein Nein Ja
SAML 2.0 Ja Ja Nein Ja Ja Ja
LDAP-Verbund Ja Ja Nein Ja Ja Ja
Feingranulare Authz Ja (UMA) Nein Nein Ja (kostenpflichtig) Ja (kostenpflichtig) Teilweise
Komplexität Hoch Mittel Niedrig Niedrig Niedrig Mittel

Fehlerbehebung

Problem Lö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-Schleife Prüfen Sie ob KC_HOSTNAME mit der tatsächlichen URL übereinstimmt
E-Mail wird nicht gesendet SMTP in Realm-Einstellungen → E-Mail prüfen
LDAP-Benutzer nicht synchronisiert Bind-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