User Federation mit Keycloak und Active Directory

In vielen Unternehmen und deren IT-Landschaften wird die zentrale Benutzerverwaltung durch ein Active Directory (AD) bestimmt. Es wird als die “Single Source of Truth” für alle Mitarbeitendendaten, Gruppen, Passwörter und Rollen genutzt, das als wichtiges Identitätsmangementtool gewissenhaft gepflegt wird.

Gleichzeitig benötigen moderne Anwendungen, insbesondere Webanwendungen, auch Unterstützung für Authentifizierungsprotokolle wie OAuth2 und OpenID Connect, um sich authentifizieren zu können. Diese modernen Protokolle unterstützt das AD von Haus aus nicht.

Wie kann es jetzt klappen, dass die modernen Protokolle gemeinsam mit Active Directory genutzt werden können? Unbedingt vermieden werden sollte es die Benutzerdaten an verschiedenen Orten und mehrfach zu speichern und zu pflegen. Eine doppelte Ablage ist wartungsintensiv und fehleranfällig. Stattdessen müssen wir es schaffen, unsere bereits in AD gepflegten Stammdaten über die modernen Protokolle auszuspielen.

An dieser Stelle kommt Keycloak ins Spiel, das bei der Unterstützung eben dieser Protokolle, insbesondere OAuth, OpenID Connect und SAML glänzen kann. Und statt nun die Benutzer in Keycloak separat zu pflegen, kann Keycloak die bereits angelegten Benutzer aus dem AD synchronisieren und über die genannten Protokolle bereitstellen.

In diesem Beitrag zeige ich kurz und bündig, wie man ein Active Directory im Rahmen einer sogenannten User Federation an Keycloak anbindet. Ziel ist ein modernes Single-Sign-On-System ohne doppelten Pflegeaufwand für die Benutzerbasis.

Active Directory einrichten und konfigurieren

Im ersten Schritt muss das Active Directory eingerichtet werden. Für die meisten Unternehmen sollte dies bereits geschehen sein. Dennoch zeige ich hier einmal sehr kurz die Basisinstallation. Dazu muss im ersten Schritt im Server Manager des Windows Servers die Rolle “Active Directory-Domänendienste” installiert werden.

Anschließend erscheint im Server Manager der “AD DS” Eintrag im linken Menü, der bei Auswahl mit einem gelben Banner darauf hinweist, dass noch Konfigurationen notwendig sind. Mit einem Klick auf das gelbe Ausrufezeichen am oberen Bildschirmrand erhalten wir den Hinweis, dass der Server noch zu einem Domänencontroller heraufgestuft werden sollte.

In den folgenden Schritten sollte eine neue Gesamtstruktur mit einem festzulegenden Namen (“ad.codecentric.test”), Passwort und NetBIOS Name (“AD”) unter den sonst vorgegebenen Standardeinstellungen installiert werden.

Nach einem Neustart erfolgt der Login entsprechend nicht mehr nur mit dem Benutzernamen, sondern mit voreingestelltem NetBIOS-Namen, also z.B. “AD\Administrator” und dem zugehörigen Passwort.

Anschließend können über das Tool “Active Directory-Benutzer und -Computer”, welches über die Suche im Startmenü aufgerufen werden kann, Benutzer angelegt werden.

Schaltet man via “Ansicht” die “Erweiterten Features” ein, kann man via Rechtsklick auf einen Benutzer -> “Eigenschaften” -> “Attribut-Editor” noch den “distinguishedName” des Users einsehen, den wir später für die Keycloak Konfiguration benötigen.

Hinweis: Um AD sicher nutzen zu können, muss noch der Active-Directory-Zertifikatsdienst installiert werden und dem Server ein gültiges Zertifikat zugewiesen werden. Ist dies ein Self-Signed Zertifikat muss das CA-Zertifikat noch mit Hilfe der KC_TRUSTSTORE_PATHS Environment-Variable dem Keycloak hinzugefügt werden. Dieses Tutorial soll jedoch nur einen kurzen Überblick über Keycloak und AD geben und klammert daher die komplexere Zertifikats-Konfiguration aus.

Active Directory in Keycloak konfigurieren

Sobald ein lauffähiger und korrekt konfiguriertes Active Directory vorliegt, kann dieses in Keycloak konfiguriert werden. Im Seitenmenü “User Federation” kann ein neues LDAP angelegt werden. Wichtige Konfigurationen hierbei sind:

Vendor	Wenn Sie ein Active Directory von Microsoft verwenden, kann hier “Active Directory” verwendet werden. Für openldap wählen Sie “other”. Zudem stehen weitere Optionen für Novell eDirectory und Red Hat Directory Server zur Verfügung. In unserem Fall wählen wir “Active Directory”.
Connection URL	Hier kommt die Domain oder der Hostname des AD-Servers hin. Dies ist für SSL-gesicherte Verbindungen “ldaps://meinadserver:636”. Sollten Sie ohne SSL arbeiten, nutzen Sie “ldap://meinadserver:389”. SSL ist hier empfohlen.
Bind type	Wählen Sie “none” für eine anonyme Anmeldung am LDAP Server, während “simple” eine Administrative Anmeldung erfordert. Meistens ist letzteres sinnvoll und wird von uns ausgewählt.
Bind DN	Der distinguishedName des Administrators (oder besser eines berechtigen Users) im AD
Bind credentials	Das Passwort des im Bind DN ausgewählten Users im AD

Über die Buttons “Test connection” und “Test authentication” kann die Verbindung zum AD getestet werden. Falls Fehler auftreten, sind die angezeigten Fehlermeldungen oft nicht besonders hilfreich. Hier lohnt sich ein Blick in den Keycloak Syslog, um das Problem zu erkennen und zu beheben.

Als letztes müssen noch Einstellungen im Block “LDAP searching and updating” vorgenommen werden.

Edit mode	Wählen Sie hier “READ_ONLY” aus, wenn Sie weiterhin alle Benutzerdaten via Active Directory pflegen wollen. Dies ist sinnvoll, wenn das AD die “Single Source of Truth” bleiben soll.
Users DN	Geben Sie hier den distinguishedName eines Benutzers ein, allerdings ohne den Teil des Benutzernamens. Über das Users DN steuern Sie, welche Benutzer importiert werden sollen.

Nach einem Klick auf “Save” werden die Benutzer importiert. Sie werden im Menü “Users” sichtbar. Enthalten sind hier der lokale Keycloak-User “admin”, der Admin des AD mit dem Namen “administrator”, unsere beiden angelegten Benutzer Michael und Stefan, sowie die deaktivierten AD-Standardbenutzer “gast” und “krbtgt”.

Je nach Konfiguration sollte es jetzt möglich sein, sich mit den Benutzern in ihre Anwendungen einzuloggen. Möglicherweise müssen vorher allerdings noch Rollen und Berechtigungen vergeben werden. Auch ist es möglich, AD-Benutzern automatisch bestimmte Rollen zuzuweisen. In der Keycloak Standard-Konfiguration kann ein einfacher Login-Test in die Account Console vorgenommen werden. Dazu wechseln wir im Menü auf den Punkt “Clients” und klicken in der Zeile “account-console” auf dessen Home URL. Dort sollte nun ein Login mit den synchronisierten AD-Benutzern möglich sein.