Aller au contenu
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// installation

Keycloak mit LDAP / Active Directory konfigurieren

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Keycloak unterstützt die Benutzerföderation mit LDAP-kompatiblen Verzeichnissen, darunter Microsoft Active Directory (AD), OpenLDAP und andere LDAP-v3-Server. Dieser Leitfaden führt durch die Anbindung von Keycloak an einen LDAP-Provider, das Mapping von Benutzerattributen und die laufende Synchronisation.

Voraussetzungen

  • Eine laufende Keycloak-Instanz (v21+)
  • Admin-Zugang zur Keycloak Admin Console
  • Hostname und Port des LDAP-Servers sowie ein Bind-Konto mit Lesezugriff auf Benutzereinträge
  • (Optional) TLS-Zertifikat Ihres LDAP-Servers bei Nutzung von LDAPS

1. LDAP-Provider hinzufügen

  1. Melden Sie sich an der Keycloak Admin Console an und wählen Sie Ihren Realm.
  2. Navigieren Sie in der linken Seitenleiste zu User Federation.
  3. Klicken Sie auf Add provider und wählen Sie ldap aus dem Dropdown.

Sie gelangen zum LDAP-Konfigurationsformular.

2. Verbindungseinstellungen

Legen Sie fest, wie Keycloak sich mit Ihrem Verzeichnis verbindet.

Feld Beschreibung Beispiel
Console Display Name Bezeichnung in der Admin Console Corporate AD
Vendor Füllt sinnvolle Standardwerte für bekannte Server vor Active Directory
Connection URL Adresse des LDAP-Servers ldap://ad.example.com:389 oder ldaps://ad.example.com:636
Enable StartTLS Hebt eine unverschlüsselte Verbindung auf TLS an Off (wenn möglich stattdessen LDAPS nutzen)
Bind Type Authentifizierungsmethode für das Bind-Konto simple
Bind DN Distinguished Name des Servicekontos cn=svc-keycloak,ou=ServiceAccounts,dc=example,dc=com
Bind Credential Passwort des Bind-Kontos (sicher aufbewahren)

Nach dem Ausfüllen der Verbindungsfelder klicken Sie auf Test connection, um zu prüfen, ob Keycloak den LDAP-Server erreicht, und dann auf Test authentication, um die Bind-Zugangsdaten zu validieren.

Beispiel Active Directory

Vendor:         Active Directory
Connection URL: ldaps://dc01.corp.example.com:636
Bind DN:        CN=svc-keycloak,OU=ServiceAccounts,DC=corp,DC=example,DC=com
Bind Credential: <password>

Beispiel OpenLDAP

Vendor:         Other
Connection URL: ldap://ldap.example.com:389
Bind DN:        cn=admin,dc=example,dc=com
Bind Credential: <password>

3. LDAP-Sucheinstellungen

Diese Einstellungen steuern, welche Einträge Keycloak aus dem Verzeichnis liest.

Feld Beschreibung Beispiel
Edit Mode Ob Keycloak in LDAP zurückschreiben darf READ_ONLY
Users DN Basis-DN, unter dem Benutzereinträge liegen OU=Users,DC=corp,DC=example,DC=com
Username LDAP attribute LDAP-Attribut, das auf den Keycloak-Benutzernamen abgebildet wird sAMAccountName (AD) oder uid (OpenLDAP)
RDN LDAP attribute Attribut für den RDN des Benutzers cn
UUID LDAP attribute Eindeutiger, stabiler Bezeichner je Benutzer objectGUID (AD) oder entryUUID (OpenLDAP)
User Object Classes Kommagetrennte Objektklassen zum Filtern der Benutzer person, organizationalPerson, user
User LDAP Filter Zusätzlicher LDAP-Filter (optional) (memberOf=CN=AppUsers,OU=Groups,DC=corp,DC=example,DC=com)
Search Scope Ob der Teilbaum oder nur eine Ebene durchsucht wird Subtree
Read Timeout LDAP-Lese-Timeout in Millisekunden 30000
Pagination LDAP-Ergebnispaging für große Verzeichnisse aktivieren On

Tipp – Umfang per Filter begrenzen: Soll sich nur eine Teilmenge der AD-Benutzer (z. B. Mitglieder einer bestimmten Gruppe) anmelden können, nutzen Sie das Feld User LDAP Filter. Das vermeidet den Import des gesamten Verzeichnisses nach Keycloak.

Optionen für Edit Mode

Modus Verhalten
READ_ONLY Keycloak liest aus LDAP; kein Zurückschreiben. Passwortänderungen sind blockiert.
WRITABLE Keycloak kann Benutzerattribute und Passwörter in LDAP aktualisieren.
UNSYNCED Benutzer werden in die lokale Keycloak-Datenbank importiert; Änderungen bleiben lokal.

Für die meisten Unternehmens-Setups ist READ_ONLY der sicherste Ausgangspunkt.

4. Kerberos / SSO (optional)

Nutzt Ihre Active-Directory-Umgebung Kerberos, können Sie auf derselben LDAP-Provider-Seite die Kerberos-Integration aktivieren. Das ermöglicht Desktop-SSO für Benutzer auf domänengebundenen Rechnern. Die nötige krb5.conf- und Keytab-Einrichtung beschreibt die Keycloak-Kerberos-Dokumentation.

5. Speichern und Testen

Sobald die Einstellungen ausgefüllt sind:

  1. Klicken Sie auf Save.
  2. Scrollen Sie nach oben und klicken Sie auf Synchronize all users für einen ersten Import.
  3. Navigieren Sie in der Seitenleiste zu Users und bestätigen Sie, dass LDAP-Benutzer in der Liste erscheinen.

6. Attribut-Mapper

Keycloak nutzt LDAP-Mapper, um LDAP-Attribute in Felder des Keycloak-Benutzerprofils zu übersetzen. Nach dem Speichern des Providers öffnen Sie den Tab Mappers auf der LDAP-Provider-Seite. Je nach gewähltem Vendor werden mehrere Mapper automatisch angelegt.

Übliche Standard-Mapper

Mapper-Name LDAP-Attribut Keycloak-Attribut
username sAMAccountName / uid username
first name givenName firstName
last name sn lastName
email mail email
creation date whenCreated createTimestamp

Eigenen Mapper hinzufügen

Um ein zusätzliches LDAP-Attribut (z. B. department) auf ein Keycloak-Benutzerattribut abzubilden:

  1. Klicken Sie auf Add mapper.
  2. Setzen Sie Mapper Type auf user-attribute-ldap-mapper.
  3. Setzen Sie Name auf etwas Sprechendes, z. B. department.
  4. Setzen Sie User Model Attribute auf den Keycloak-Attributnamen (z. B. department).
  5. Setzen Sie LDAP Attribute auf den LDAP-Feldnamen (z. B. department).
  6. Klicken Sie auf Save.

Gruppen-Mapper

Um LDAP-Gruppen nach Keycloak zu importieren:

  1. Klicken Sie auf Add mapper.
  2. Setzen Sie Mapper Type auf group-ldap-mapper.
  3. Richten Sie Groups DN auf den Ort Ihrer Gruppen, z. B. OU=Groups,DC=corp,DC=example,DC=com.
  4. Setzen Sie Group Name LDAP Attribute auf cn.
  5. Setzen Sie Membership LDAP Attribute auf member.
  6. Entscheiden Sie je nach Bedarf über Drop non-existing groups during sync.
  7. Klicken Sie auf Save, dann auf Sync LDAP Groups to Keycloak.

7. Periodische Synchronisation

Keycloak kann seinen lokalen Benutzer-Cache automatisch nach Zeitplan mit dem LDAP-Verzeichnis synchron halten.

Synchronisationsmodi

Modus Beschreibung
Full sync Importiert alle LDAP-Benutzer neu nach Keycloak und bildet Neuzugänge, Änderungen und Löschungen ab.
Changed users sync Importiert nur Benutzer, deren LDAP-modifyTimestamp sich seit der letzten Synchronisation geändert hat. Effizienter bei großen Verzeichnissen.

Sync-Zeitplan konfigurieren

  1. Öffnen Sie Ihre LDAP-Provider-Konfiguration.
  2. Scrollen Sie zum Abschnitt Sync Settings.
  3. Aktivieren Sie Periodic Full Sync und setzen Sie das Intervall in Sekunden, z. B. 86400 = einmal täglich.
  4. Aktivieren Sie Periodic Changed Users Sync und setzen Sie ein kürzeres Intervall, z. B. 3600 = jede Stunde.
  5. Klicken Sie auf Save.
Periodic Full Sync:          On
Full Sync Period:            86400   (24 hours)

Periodic Changed Users Sync: On
Changed Users Sync Period:   3600    (1 hour)

Hinweis: Changed users sync setzt voraus, dass der LDAP-Server modifyTimestamp unterstützt. Active Directory und OpenLDAP tun das beide. Falls Ihr Server es nicht unterstützt, nutzen Sie ausschließlich Full Sync.

Manuelle Synchronisation auslösen

Sie können jederzeit auf der LDAP-Provider-Seite eine Synchronisation auslösen:

  • Synchronize all users – vollständige Synchronisation aller Einträge.
  • Synchronize changed users – inkrementelle Synchronisation seit dem letzten Lauf.

Eine Synchronisation lässt sich auch über die REST-API auslösen:

# Full sync
curl -X POST \
  "https://keycloak.example.com/admin/realms/{realm}/user-storage/{provider-id}/sync?action=triggerFullSync" \
  -H "Authorization: Bearer <admin_token>"

# Changed users only
curl -X POST \
  "https://keycloak.example.com/admin/realms/{realm}/user-storage/{provider-id}/sync?action=triggerChangedUsersSync" \
  -H "Authorization: Bearer <admin_token>"

8. Verbindung über LDAPS (TLS)

Verwenden Sie in Produktiv-Deployments immer LDAPS (ldaps://) oder StartTLS, um den Verkehr zwischen Keycloak und Ihrem Verzeichnis zu verschlüsseln.

Nutzt Ihr LDAP-Server ein Zertifikat einer privaten CA:

  1. Importieren Sie das CA-Zertifikat in den Java-Truststore, den Keycloak verwendet:

    keytool -import -alias ldap-ca \
  -file /path/to/ca.crt \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit -noprompt

  2. Starten Sie Keycloak neu.

  3. Ändern Sie die Connection URL auf ldaps:// und Port 636.

Alternativ konfigurieren Sie einen eigenen Truststore in keycloak.conf:

https-trust-store-file=/opt/keycloak/conf/ldap-truststore.jks
https-trust-store-password=changeit

9. Troubleshooting

Symptom Wahrscheinliche Ursache Maßnahme
„Test connection" schlägt fehl Falscher Hostname, Port durch Firewall blockiert Netzzugang prüfen; telnet <host> 389 versuchen
„Test authentication" schlägt fehl Falscher Bind-DN oder falsches Passwort Zugangsdaten mit ldapsearch prüfen
Keine Benutzer nach der Synchronisation Falscher Users-DN oder falsche User Object Classes Mit einem LDAP-Browser prüfen (z. B. Apache Directory Studio)
Benutzer können sich anmelden, Attribute fehlen Mapper falsch konfiguriert oder LDAP-Attribut fehlt Tab Mappers prüfen; bestätigen, dass das Attribut am Benutzerobjekt existiert
Sync-Job läuft nie Geplante Synchronisation nicht gespeichert oder Keycloak vor dem Speichern neu gestartet Sync Settings erneut prüfen und wieder auf Save klicken

Für ausführliches LDAP-Logging ergänzen Sie in der Logging-Konfiguration von Keycloak:

quarkus.log.category."org.keycloak.storage.ldap".level=DEBUG

Weiterführend

Nächster Schritt: Server betreiben