Zum Inhalt

Keycloak AD/LDAP-Anbindung — Einrichtungsanleitung

Zielgruppe: IT-Administrator bei AVS Keycloak-Version: 26.x Realm: avs-chatbot Ziel: AVS-Mitarbeiter sollen sich mit ihren bestehenden Active-Directory-Credentials am Chatbot-Admin-Dashboard anmelden können.

Inhaltsverzeichnis

  1. Voraussetzungen
  2. Variante A: Active Directory
  3. Variante B: OpenLDAP / anderer LDAP-Server
  4. SSL/TLS-Konfiguration
  5. Fehlerbehebung
  6. Testen
  7. Produktiv-Checkliste

1. Voraussetzungen

Bevor die Einrichtung beginnen kann, werden folgende Informationen vom AVS-IT-Team benötigt. Diese Tabelle kann als Vorbereitung vorab per E-Mail verschickt und ausgefüllt zurückgesendet werden.

Parameter-Checkliste

Nr. Parameter Ihr Wert Beispiel
1 LDAP-Server-URL ____ ldaps://ad.avs.de:636
2 Bind-DN (Service-Account) ____ cn=keycloak-svc,ou=Service Accounts,dc=avs,dc=de
3 Bind-Passwort ____ (sicher verwahren!)
4 Base-DN (Benutzersuche) ____ ou=Mitarbeiter,dc=avs,dc=de
5 LDAP-Filter (optional) ____ (memberOf=CN=Chatbot-Benutzer,OU=Gruppen,DC=avs,DC=de)
6 Gruppen-DN ____ ou=Gruppen,dc=avs,dc=de
7 AD-Gruppe: Admins ____ Chatbot-Admins
8 AD-Gruppe: Editoren ____ Chatbot-Editoren
9 AD-Gruppe: Betrachter ____ Chatbot-Nutzer
10 AD-Gruppe: IT-Admin (Super-Admin) ____ IT-Administratoren
11 SSL-Zertifikat (selbst-signiert?) ja / nein
12 Zertifikatsdatei (falls ja) ____ avs-ad-ca.pem

Hinweise zum Service-Account (Bind-DN): - Der Account benötigt nur Leserechte auf die Benutzer- und Gruppen-OUs. - Empfehlung: Eigenen Service-Account keycloak-svc anlegen (kein persönlicher Admin-Account). - Das Passwort sollte nicht ablaufen ("Password never expires" im AD setzen).

Zum Protokoll: - ldaps:// (Port 636) wird dringend empfohlen (SSL/TLS verschlüsselt). - ldap:// (Port 389) sollte nur zum Testen verwendet werden — niemals in Produktion!

2. Variante A: Active Directory

2.1 Keycloak Admin-Konsole öffnen

  1. Browser öffnen: https://<keycloak-url>/admin (Beispiel Entwicklung: https://auth.avs.luki-net.org/admin)
  2. Anmelden mit dem Keycloak-Admin-Account.
  3. Oben links prüfen, dass der Realm avs-chatbot ausgewählt ist. Falls nicht: Dropdown klicken und avs-chatbot auswählen.

2.2 LDAP-Provider hinzufügen

  1. Linkes Menü: User federation klicken.
  2. Button Add LDAP providers klicken.

2.3 Allgemeine Einstellungen

Folgende Felder ausfüllen:

Feld Wert Erläuterung
UI display name AVS Active Directory Frei wählbarer Anzeigename
Vendor Active Directory Aus Dropdown auswählen
Edit mode READ_ONLY Benutzer werden im AD verwaltet, nicht in Keycloak
Import users On AD-Benutzer werden in Keycloak importiert
Sync registrations Off Neue Benutzer nur im AD anlegen

2.4 Connection Settings

Feld Wert Erläuterung
Connection URL ldaps://ad.avs.de:636 Ihre LDAP-Server-URL (Parameter Nr. 1)
Enable StartTLS Off Bei ldaps:// nicht nötig (nur bei ldap:// + STARTTLS)
Connection pooling On Verbessert Performance
Connection timeout 5000 Timeout in Millisekunden

Jetzt auf Test connection klicken.

Erwartetes Ergebnis: Grüne Meldung "Successfully connected to LDAP". Falls Fehler: siehe Fehlerbehebung.

2.5 Bind Settings

Feld Wert Erläuterung
Bind type simple Standard-Authentifizierung
Bind DN (Parameter Nr. 2) z.B. cn=keycloak-svc,ou=Service Accounts,dc=avs,dc=de
Bind credential (Parameter Nr. 3) Passwort des Service-Accounts

Jetzt auf Test authentication klicken.

Erwartetes Ergebnis: Grüne Meldung "Successfully connected to LDAP". Falls Fehler: Bind-DN und Passwort prüfen.

2.6 LDAP Searching and Updating

Feld Wert Erläuterung
Users DN (Parameter Nr. 4) z.B. ou=Mitarbeiter,dc=avs,dc=de
Username LDAP attribute sAMAccountName Windows-Anmeldename
RDN LDAP attribute cn Relative Distinguished Name
UUID LDAP attribute objectGUID Eindeutige AD-ID
User object classes person, organizationalPerson, user Standard AD-Klassen
Custom user LDAP filter (Parameter Nr. 5, optional) z.B. (memberOf=CN=Chatbot-Benutzer,OU=Gruppen,DC=avs,DC=de)
Search scope Subtree Durchsucht auch Unter-OUs
Pagination On Nötig bei mehr als 1000 Benutzern

Wenn nur bestimmte AD-Benutzer Zugriff haben sollen, den Custom user LDAP filter setzen. So werden nur Mitglieder der angegebenen Gruppe synchronisiert.

2.7 Synchronization Settings

Feld Wert Erläuterung
Periodic full sync On Regelmäßig alle Benutzer abgleichen
Full sync period 86400 Alle 24 Stunden (in Sekunden)
Periodic changed users sync On Änderungen häufiger abgleichen
Changed users sync period 3600 Jede Stunde (in Sekunden)

2.8 Speichern und erste Synchronisation

  1. Ganz unten auf Save klicken.
  2. Nach dem Speichern erscheint oben ein Dropdown-Button Action.
  3. Action → Sync all users klicken.
  4. Es erscheint eine Meldung mit der Anzahl importierter Benutzer (z.B. "Successfully synced 47 users").

Falls 0 Benutzer synchronisiert werden: Users DN und Custom user LDAP filter prüfen.

2.9 Gruppen-Mapper einrichten

Damit AD-Gruppen in Keycloak verfügbar sind:

  1. Auf der LDAP-Provider-Seite den Tab Mappers öffnen.
  2. Button Add mapper klicken.
Feld Wert Erläuterung
Name AD-Gruppen Frei wählbar
Mapper type group-ldap-mapper Aus Dropdown auswählen
LDAP groups DN (Parameter Nr. 6) z.B. ou=Gruppen,dc=avs,dc=de
Group name LDAP attribute cn Gruppenname im AD
Group object classes group Standard-AD-Gruppenklasse
Preserve group inheritance On Verschachtelte Gruppen beibehalten
Membership LDAP attribute member AD-Standard für Gruppenmitgliedschaft
Membership attribute type DN Distinguished Name
Membership user LDAP attribute (leer lassen) Standard verwenden
LDAP filter (leer lassen oder einschränken) z.B. (cn=Chatbot-*) um nur relevante Gruppen zu importieren
Mode READ_ONLY Gruppen werden im AD verwaltet
User groups retrieve strategy LOAD_GROUPS_BY_MEMBER_ATTRIBUTE Empfohlen für AD
Drop non-existing groups during sync Off Vorsicht: erst testen!
  1. Auf Save klicken.
  2. Action → Sync LDAP groups to Keycloak klicken.

2.10 Rollen-Zuordnung

AD-Gruppen müssen den Keycloak Realm-Rollen zugeordnet werden. Die Chatbot-Anwendung verwendet diese vier Rollen:

Keycloak Realm-Rolle AD-Gruppe (Beispiel) Berechtigung im Chatbot
avs-viewer Chatbot-Nutzer Dashboard und Feedback einsehen
avs-editor Chatbot-Editoren Dokumente verwalten
avs-admin Chatbot-Admins Voller Admin-Zugang, Analytics
super-admin IT-Administratoren Einstellungen, Audit-Log, Lizenz

Es gibt zwei Möglichkeiten, dieses Mapping einzurichten:

Option 1: Automatisches Mapping über Gruppen-Rollen (empfohlen)

Für jede Rolle/Gruppe-Kombination:

  1. Linkes Menü: Groups klicken.
  2. Die importierte AD-Gruppe suchen und anklicken (z.B. Chatbot-Admins).
  3. Tab Role mapping öffnen.
  4. Button Assign role klicken.
  5. Die passende Realm-Rolle auswählen (z.B. avs-admin).
  6. Assign klicken.

Das Mapping wiederholen für alle vier Rollen-Gruppen-Paare.

Ab jetzt erhält jeder Benutzer, der im AD Mitglied der Gruppe Chatbot-Admins ist, automatisch die Keycloak-Rolle avs-admin.

Option 2: Manuelles Mapping pro Benutzer

Falls kein Gruppen-Mapping gewünscht ist:

  1. Linkes Menü: Users klicken.
  2. Den gewünschten Benutzer suchen und anklicken.
  3. Tab Role mapping öffnen.
  4. Assign role → Rolle auswählen → Assign.

Diese Option eignet sich nur für wenige Benutzer. Bei mehr als 5 Nutzern wird Option 1 dringend empfohlen.

3. Variante B: OpenLDAP / anderer LDAP-Server

Die Schritte sind identisch zu Variante A, mit folgenden abweichenden Einstellungen:

Abweichende Felder

Feld Active Directory OpenLDAP
Vendor Active Directory Other
Username LDAP attribute sAMAccountName uid
RDN LDAP attribute cn uid
UUID LDAP attribute objectGUID entryUUID
User object classes person, organizationalPerson, user inetOrgPerson, organizationalPerson

Abweichende Gruppen-Mapper-Felder

Feld Active Directory OpenLDAP
Group object classes group groupOfUniqueNames
Membership LDAP attribute member uniqueMember

Alle anderen Schritte (Connection, Bind, Sync, Rollen-Zuordnung) bleiben gleich.

4. SSL/TLS-Konfiguration

4.1 Wann ist dieser Schritt nötig?

  • Bei ldaps:// mit selbst-signiertem Zertifikat oder interner CA.
  • Bei öffentlich signierten Zertifikaten (z.B. Let's Encrypt) ist dieser Schritt nicht nötig.

4.2 Zertifikat vom AD-Server exportieren

Das CA-Zertifikat (oder das Server-Zertifikat) im PEM-Format bereitstellen.

Auf dem AD-Server (Windows):

# Zertifikat aus dem Windows-Zertifikatspeicher exportieren
certutil -ca.cert avs-ad-ca.cer
# In PEM konvertieren (falls .cer im DER-Format)
certutil -encode avs-ad-ca.cer avs-ad-ca.pem

Alternativ über die MMC-Konsole: certmgr.msc → Vertrauenswürdige Stammzertifizierungsstellen → Zertifikat exportieren (Base-64-codiert).

4.3 Zertifikat in den Keycloak-Container importieren

  1. Zertifikatsdatei auf den Docker-Host kopieren:
# Zertifikat in das Projektverzeichnis legen
cp avs-ad-ca.pem /opt/avs-chatbot/infra/keycloak/avs-ad-ca.pem
  1. In docker-compose.yml einen Volume-Mount hinzufügen:
  keycloak:
    # ... bestehende Konfiguration ...
    volumes:
      - ./infra/keycloak/avs-ad-ca.pem:/opt/keycloak/conf/avs-ad-ca.pem:ro
    environment:
      # ... bestehende Variablen ...
      KC_TRUSTSTORE_PATHS: /opt/keycloak/conf/avs-ad-ca.pem

Keycloak 26 unterstützt KC_TRUSTSTORE_PATHS nativ — es ist kein manueller keytool-Import nötig. Mehrere Zertifikate können kommagetrennt angegeben werden.

  1. Keycloak-Container neu starten:
docker compose restart keycloak
  1. Danach in der Keycloak Admin-Konsole erneut Test connection klicken, um die SSL-Verbindung zu prüfen.

5. Fehlerbehebung

Keycloak-Logs einsehen

# LDAP-relevante Log-Einträge anzeigen
docker compose logs keycloak | grep -i ldap

# Live-Logs verfolgen (während der Einrichtung)
docker compose logs -f keycloak

Häufige Fehler und Lösungen

Fehlermeldung Mögliche Ursache Lösung
Connection refused Firewall blockiert, falscher Port, Server nicht erreichbar Firewall-Regeln prüfen: Port 636 (LDAPS) oder 389 (LDAP) muss vom Docker-Host zum AD-Server offen sein. telnet ad.avs.de 636 zum Testen.
Invalid credentials Bind-DN oder Passwort falsch Bind-DN exakt prüfen (Groß-/Kleinschreibung, Leerzeichen). Passwort mit einem LDAP-Browser (z.B. Apache Directory Studio) verifizieren.
No users synced (0 Benutzer) Users DN falsch, Filter zu restriktiv Users DN schrittweise vergrößern (z.B. dc=avs,dc=de statt ou=Mitarbeiter,...). Custom LDAP filter temporär entfernen.
SSL handshake failed Zertifikat fehlt oder ist abgelaufen Zertifikat importieren (siehe Abschnitt 4). Ablaufdatum prüfen: openssl x509 -in avs-ad-ca.pem -noout -dates
Users visible but can't login Falsches Username-Attribut Für AD: sAMAccountName verwenden, nicht cn oder userPrincipalName.
LDAP error code 49 Authentifizierungsfehler (diverse Ursachen) Sub-Error-Code prüfen: 52e = falsches Passwort, 530 = Account gesperrt, 532 = Passwort abgelaufen, 533 = Account deaktiviert.
Size limit exceeded Mehr als 1000 Ergebnisse Pagination auf On setzen. Ggf. LDAP-Filter einschränken.

Verbindung manuell testen

Vom Docker-Host aus:

# LDAPS-Verbindung prüfen (Port 636)
openssl s_client -connect ad.avs.de:636 -showcerts </dev/null

# LDAP-Suche testen (ldapsearch muss installiert sein: apt install ldap-utils)
ldapsearch -H ldaps://ad.avs.de:636 \
  -D "cn=keycloak-svc,ou=Service Accounts,dc=avs,dc=de" \
  -W \
  -b "ou=Mitarbeiter,dc=avs,dc=de" \
  -s sub "(sAMAccountName=testuser)" \
  cn sAMAccountName memberOf

6. Testen

Nach Abschluss der Einrichtung sollten folgende Tests durchgeführt werden:

6.1 Benutzer in Keycloak sichtbar?

  1. Keycloak Admin-Konsole → Users → View all users.
  2. AD-Benutzer sollten mit dem Federation-Link AVS Active Directory erscheinen.
  3. Stichprobe: Einen bekannten Benutzer suchen und dessen Attribute prüfen.

6.2 Login am Chatbot-Admin-Dashboard

  1. Browser öffnen: https://<chatbot-url>/admin/
  2. Mit einem AD-Benutzernamen und -Passwort anmelden.
  3. Prüfen: Login funktioniert? Dashboard wird angezeigt?

6.3 Rollen korrekt zugewiesen?

Test Erwartetes Ergebnis
Login als Chatbot-Nutzer (avs-viewer) Sieht Dashboard, Feedback, Sessions. Keine Einstellungen, kein Audit-Log.
Login als Chatbot-Editor (avs-editor) Zusätzlich: Dokumente verwalten.
Login als Chatbot-Admin (avs-admin) Zusätzlich: Analytics, Feedback-Export.
Login als IT-Admin (super-admin) Sieht alles: Einstellungen, Audit-Log, Changelog, Lizenz.

6.4 Synchronisation prüfen

  1. Im AD einen neuen Testbenutzer anlegen und der Chatbot-Gruppe hinzufügen.
  2. In Keycloak: User federation → AVS Active Directory → Action → Sync changed users.
  3. Der neue Benutzer sollte sofort erscheinen.
  4. Warten, ob der automatische Sync (stündlich) den Benutzer auch ohne manuellen Sync findet.

6.5 Deaktivierung prüfen

  1. Im AD einen Testbenutzer deaktivieren.
  2. Sync auslösen.
  3. Prüfen: Der Benutzer kann sich nicht mehr anmelden.

7. Produktiv-Checkliste

Vor dem Go-Live alle Punkte abhaken:

Verbindung

  • AD-Verbindung getestet (Test connection: grün)
  • Authentifizierung getestet (Test authentication: grün)
  • SSL/TLS konfiguriert (kein unverschlüsseltes ldap:// in Produktion!)
  • Firewall-Regeln dauerhaft eingerichtet (Port 636)

Benutzer und Rollen

  • Alle relevanten Benutzer synchronisiert
  • Rollen-Mapping korrekt konfiguriert:
  • avs-viewer → AD-Gruppe für Betrachter
  • avs-editor → AD-Gruppe für Editoren
  • avs-admin → AD-Gruppe für Admins
  • super-admin → AD-Gruppe für IT-Administratoren
  • Super-Admin auf mindestens einen IT-Administrator bei AVS zugewiesen
  • Lokale Test-Benutzer deaktiviert oder gelöscht (z.B. lutz, avs-demo)

Synchronisation

  • Periodic Full Sync aktiviert (empfohlen: alle 24 Stunden)
  • Periodic Changed Users Sync aktiviert (empfohlen: jede Stunde)
  • Sync einmal manuell erfolgreich durchgeführt

Sicherheit

  • Bind-DN hat nur Leserechte (kein Domain-Admin!)
  • Bind-Passwort läuft nicht ab
  • Edit mode auf READ_ONLY gesetzt
  • Keycloak-Admin-Passwort geändert (nicht mehr das Standard-Passwort)
  • Keycloak Brute-Force-Schutz aktiviert (Realm Settings → Security Defenses)

Backup

  • Keycloak Realm-Export erstellt: 
    # Realm-Konfiguration exportieren (ohne Benutzer)
docker compose exec keycloak \
  /opt/keycloak/bin/kc.sh export \
  --realm avs-chatbot \
  --dir /tmp/export \
  --users skip
docker compose cp keycloak:/tmp/export ./keycloak-backup/
  • Docker-Compose-Konfiguration gesichert

Bei Fragen oder Problemen: Kontakt an den Chatbot-Projektverantwortlichen oder die Keycloak-Dokumentation unter https://www.keycloak.org/docs/latest/server_admin/#_ldap.