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

// installation

Keycloak mit LDAP / Active Directory verbinden

Gilt für

Produkt: Server · Zielgruppe: Platform Operator · Administrator

Keycloak unterstützt LDAP und Active Directory von Haus aus – keine Plugins, kein Scripting. Sie füllen ein Formular aus, klicken auf Test connection, und Ihre Benutzer sind da. Diese Seite führt Sie genau dadurch.

Die vollständige Referenz finden Sie in der offiziellen Keycloak-Dokumentation.

Was Sie brauchen

  • Keycloak-Master-Admin-Zugang
  • Adresse und Port Ihres LDAP-Servers (389 für unverschlüsselt, 636 für LDAPS)
  • Ein Servicekonto (Bind-DN + Passwort) mit Lesezugriff auf Benutzereinträge
  • Den Basis-DN, unter dem Ihre Benutzer liegen
  • URL/Domain Ihrer basebox-Installation

Einrichtung

  1. Gehen Sie in der Keycloak Admin Console zu Ihrem Realm → User Federation → Add provider → ldap.

Note

Die URL Ihrer Keycloak Admin Console ist http://base-domain/auth, wobei base-domain die Domain Ihrer basebox-Installation ist.

Der Name Ihres Realms ist in der Regel primary.

  1. Tragen Sie die Verbindungsdaten ein:

    Feld Eintrag
    Vendor Active Directory oder Other (OpenLDAP etc.) – füllt sinnvolle Standardwerte vor
    Connection URL ldap://your-server:389 oder ldaps://your-server:636
    Bind DN Ihr Servicekonto, z. B. CN=svc-keycloak,OU=ServiceAccounts,DC=corp,DC=example,DC=com
    Bind Credential Das Passwort des Servicekontos
    Users DN Wo Ihre Benutzer liegen, z. B. OU=Users,DC=corp,DC=example,DC=com
    Username LDAP attribute sAMAccountName für AD, uid für OpenLDAP

  2. Klicken Sie auf Test connection, dann auf Test authentication – beides sollte grün werden.

  3. Klicken Sie auf Save, dann auf Synchronize all users.

Das war's. Unter Users in der Seitenleiste sehen Sie Ihre Verzeichnisbenutzer bereits.

Benutzer synchron halten

Keycloak kann neue und geänderte Benutzer automatisch nach Zeitplan übernehmen. Im Abschnitt Sync Settings Ihres LDAP-Providers:

  • Aktivieren Sie Periodic Changed Users Sync – auf 3600 (jede Stunde) setzen, um Tagesänderungen schnell zu erfassen.
  • Aktivieren Sie Periodic Full Sync – auf 86400 (einmal täglich) setzen, um Löschungen und alles Durchgerutschte zu erfassen.
Periodic Changed Users Sync:  On  →  3600 s
Periodic Full Sync:           On  →  86400 s

Beide Synchronisationen können Sie auf derselben Seite jederzeit auch manuell auslösen.

Gut zu wissen

Sie müssen das nicht alles lesen, um loszulegen – es ist aber nützlich, sobald Sie produktiv sind.

Edit mode steuert, ob Keycloak in LDAP zurückschreiben darf. Der Standard ist READ_ONLY, für die meisten Setups die richtige Wahl. Soll Keycloak Attribute oder Passwörter in Ihrem Verzeichnis ändern, wechseln Sie auf WRITABLE.

Attribute mappers werden automatisch anhand des gewählten Vendors angelegt (Vorname, Nachname, E-Mail etc.). Wollen Sie weitere Felder abbilden – etwa department oder employeeID –, gehen Sie auf den Tab Mappers des Providers und fügen Sie einen user-attribute-ldap-mapper hinzu.

Gruppensynchronisation gibt es über einen group-ldap-mapper. Richten Sie ihn auf Ihren Groups-DN, und Keycloak spiegelt Ihre LDAP-Gruppen als Keycloak-Gruppen.

LDAPS (TLS) wird für den Produktivbetrieb dringend empfohlen. Nutzt Ihr Server ein Zertifikat einer privaten CA, müssen Sie es in den Truststore von Keycloak importieren – die genauen Schritte stehen in der Keycloak-TLS-Dokumentation.

Benutzer filtern – soll sich nur eine Teilmenge Ihres Verzeichnisses (z. B. Mitglieder einer bestimmten AD-Gruppe) anmelden können, nutzen Sie das Feld User LDAP Filter: 

(memberOf=CN=AppUsers,OU=Groups,DC=corp,DC=example,DC=com)

Troubleshooting

Problem Wahrscheinlichste Ursache Lösung
Test connection schlägt fehl Port blockiert oder falscher Hostname Firewall prüfen; telnet your-server 389 versuchen
Test authentication schlägt fehl Falscher Bind-DN oder falsches Passwort Zugangsdaten mit ldapsearch gegenprüfen
Keine Benutzer nach der Synchronisation Falscher Users-DN oder falsche Objektklassen Pfad mit einem LDAP-Browser (z. B. Apache Directory Studio) bestätigen
Attribute fehlen bei Benutzern Mapper nicht konfiguriert Tab Mappers prüfen; LDAP-Attributname muss exakt übereinstimmen
Sync-Zeitplan läuft nicht Einstellungen vor Neustart nicht gespeichert Provider erneut öffnen, Sync Settings prüfen und erneut speichern

Für alles jenseits dieses Leitfadens – eigene Auth-Flows, Kerberos-SSO, Connection Pooling – ist der Keycloak Server Administration Guide umfassend und gut gepflegt.