Zentrale Benutzerverzeichnisse bilden das Rückgrat der Identitätsverwaltung in Unternehmen praktisch aller Größen. Systeme wie LDAP oder Active Directory ermöglichen es, Identitäten konsistent zu verwalten, Rollen und Gruppen zu definieren und Benutzerkonten zentral zu kontrollieren. Verlassen Mitarbeiter das Unternehmen, erlaubt es erst das zentrale Benutzerverzeichnis, ihnen den Zugang zu allen relevanten Diensten und Systemen flugs zu entziehen. Firmen benötigen diese Sicherheit nicht nur aus organisatorischen Gründen, sondern vor allem auch für Compliancezwecke. Regulatorische Rahmenwerke wie ISO 27001, BSI IT-Grundschutz, NIST oder branchenspezifische Vorgaben verlangen nachvollziehbare Prozesse zur Authentifizierung, Autorisierung und Deaktivierung von Accounts. Ohne eine zentrale Stelle, die Identitäten zuverlässig verwaltet, lassen sich diese Anforderungen praktisch nicht erfüllen.

Parallel dazu gewinnen föderierte Identitäten und Single Sign-on (SSO) zunehmend an Bedeutung. Hier spielt Komfort eine zentrale Rolle. Denn Anwender erwarten, dass sie sich einmal mit ihren Daten anmelden und anschließend auf alle relevanten Systeme zugreifen können. Unternehmen benötigen daher eine zentrale Instanz, die als Identitätsprovider (IdP) fungiert, standardisierte Protokolle wie OIDC, OAuth2 oder SAML spricht und gleichzeitig flexibel genug ist, um sich in heterogene Umgebungen einzufügen. Sie bilden die Brücke zwischen der Benutzerverwaltung und der Authentifizierung von Usern – genau an dieser Stelle kommt Keycloak [1] ins Spiel.

Keycloak ist ein freies Identity- und Access-Management-System (IAM). Heute gehört Keycloak zu den am weitesten verbreiteten Open-Source-IdPs und hat sich als Standardwerkzeug in vielen IT-Landschaften etabliert. Historisch ist Keycloak aus dem JBoss-Umfeld heraus entstanden, um die Anforderungen moderner Webanwendungen zu erfüllen. Die Verbreitung von Microservices und der Wandel hin zu verteilten Architekturen führten dazu, dass Anwendungen sich zunehmend auf Token-basierte Sicherheitsmodelle stützen mussten, um überhaupt eine Benutzerverifikation durchführen zu können. Ein Token ist dabei ein Zugangsschlüssel, den eine Instanz ausstellt, der ein jeweiliger anderer Dienst per Konfiguration vertraut. Und jene Instanz ist in entsprechenden Setups eben Keycloak.

Keycloak verfügt über eine modulare Architektur, die sich durch Erweiterbarkeit und Flexibilität auszeichnet. Die Software stellt OIDC-, OAuth2- und SAML-Endpunkte bereit, übernimmt Sitzungsverwaltung, Token-Ausstellung, Multifaktor-Authentifizierung und Rollenmanagement. Durch seine Möglichkeiten für eine Integration in Active Directory, LDAP, Kerberos oder andere externe IdPs lässt sich Keycloak in bestehende Infrastrukturen einbinden, ohne bestehende Verzeichnisse abzulösen.

Unter der Haube funktioniert die Software auf Grundlage von JSON Web Tokens (JWT). Als IdP übernimmt Keycloak die Aufgabe, Benutzer zu authentifizieren und Zugriffs-Token für Anwendungen auszustellen, eben jene JWT. Anwendungen müssen sich dadurch selbst nicht mehr mit der Verwaltung von Passwörtern, Logins oder Session-Tokens beschäftigen. Stattdessen leiten sie Benutzer an Keycloak weiter, erhalten nach erfolgreicher Anmeldung ein signiertes Token und nutzen dieses zur Autorisierung.

Damit Keycloak in einer bestehenden Umgebung funktioniert, schließt der Administrator es an ein existierendes Benutzerverzeichnis an – oftamals das Active Directory (AD). Dies erfolgt über eine sogenannte User Federation. Keycloak liest Benutzerkonten, Gruppen und Attribute dann aus dem AD aus. Dabei agiert es nicht als Ersatz, sondern als Erweiterung: Die Identität selbst bleibt stets im AD gespeichert, Keycloak übernimmt aber die Authentifizierung. Optional kann das Werkzeug auch Kennwortrichtlinien, MFA-Mechanismen oder zusätzliche Attribute bereitstellen, die über die Möglichkeiten des AD hinausgehen. Und falls es kein bestehendes Verzeichnis von Nutzern geben sollte, lässt sich auch dieses mit Keycloak betreiben.

Im ersten Schritt mit Keycloak richten Sie einen LDAP-Provider ein. Dazu legen Sie in der Verwaltungskonsole eine neue "User Federation" an und tragen die LDAP-Verbindungsdaten ein: "Hostname", "Port", "Base-DN, "Bind-DN" und "Authentifizierungsmethode" sind die notwendigen Parameter. Sind die Admins von Active Directory und Keycloak nicht dieselbe Person oder dasselbe Team, ist hier möglicherweise interner Abstimmungsbedarf gegeben, um die nötigen Parameter zu erfahren.

Keycloak prüft nach vorgenommener Konfiguration die Verbindung, ruft die Struktur des LDAP-Verzeichnisses ab und ordnet Attribute wie "sAMAccountName", "mail", "givenName" oder "memberOf" automatisch zu. Sie können hier definieren, welche Attribute Keycloak in seinen Tokens hin zur Anwendungsseite exponiert und wie diese für Token-Aufrufe bereitgestellt werden. Aktivieren Sie die LDAP-Synchronisation, legt Keycloak Benutzerkonten zudem im lokalen Cache an und nutzt sie für SSO-Prozesse.

Ein Beispiel für eine moderne Anwendung in Infrastrukturumgebungen, die sich hervorragend mit Keycloak verbinden lässt, ist ArgoCD [2]. Das System verwaltet Git-Ops-Deployments für Kubernetes und bietet eine eigene Weboberfläche, die Zugriffskontrolle und sicherheitsrelevante Funktionen bereitstellt. Die Integration von ArgoCD mit Keycloak erfolgt über das OpenID-Connect-Protokoll, abgekürzt meist mit "OIDC". Keycloak agiert dabei als IdP, ArgoCD als OIDC-Client. Der Administrator legt in Keycloak einen neuen Client an, wählt den OIDC-"Flow" ("Standard") aus, definiert Redirect-URIs und legt fest, welche Rollen und Gruppen in Tokens erscheinen. ArgoCD erhält im Gegenzug Zugriff auf den OIDC-Endpunkt, das hierfür festgelegte Passwort ("Client-Secret") und die Konfigurationsparameter.

Technisch sind die anstehenden Änderungen dabei einleuchtend. Einerseits ist die Clientseite entsprechend zu konfigurieren: Der Client muss wissen, dass er sich mit Keycloak verbinden soll, um sich dort anzumelden. Dafür muss in der jeweiligen Anmeldung aber hinterlegt sein, wo der zu kontaktierende Keycloak-Dienst überhaupt läuft. Hat die Anmeldung an Keycloak dann stattgefunden, benötigt das Tool die Information, wohin es den Client umleiten soll, damit dieser sich am ursprünglichen Dienst – also am OIDC-Client – mit dem nun ausgestellten Token anmelden kann. Deshalb ist auch von einer Callback-URL die Rede: An diese leitet Keycloak den Client weiter, wenn das Token in der Welt ist. Die an dieser Stelle recht ausführlich Erklärung ist später noch hilfreich, wenn wir auf das ArgoCD-Beispiel zurückkommen.

Eine funktionierende Kopplung zwischen Keycloak und Active Directory verlangt eine Umgebung, in der der Domänencontroller (DC) eindeutig erreichbar ist und die Netzwerkinfrastruktur die LDAP-Endpunkte ohne Verzögerungen bedient. Keycloak arbeitet während jeder Anmeldung eines Benutzers mit direkten LDAP-Abfragen. Die Stabilität der Netzwerkverbindung und ihre Performance beim Zugriff auf das AD spielen deshalb eine Rolle: Funktioniert DNS nicht ordentlich, greift Keycloak ins Leere. Ist die Verbindung zwischen Keycloak und AD lahm, merkt der Nutzer das unmittelbar.

Sie legen entsprechend den Fully Qualified Domain Name (FQDN) des DC fest, sorgen für korrekte Reverse-Look-ups im DNS und richten LDAP mit gültigen Zertifikaten so ein, dass es für Keycloak mittels flotter Verbindung erreichbar ist. Ein AD-Servicekonto stellt den Zugang zu allen relevanten Benutzerattributen her. Dieses Konto dient allein Keycloak, nutzt ein langes und komplexes und mithin sicheres Passwort und verfügt über lesenden Zugriff auf sämtliche Teile des Verzeichnisses.

Sind alle Voraussetzungen erfüllt, geht es mit der Einrichtung der Verbindung zwischen Keycloak und AD weiter. Dazu navigieren Sie in der Keycloak-Verwaltungsoberfläche zum Bereich "User Federation". Dort erzeugen Sie einen neuen LDAP-Provider. Dieser erfordert die Adresse des DC, den Sie wie bei LDAPS üblich in DN-Pfad-Notation angeben. Hier tragen Sie also "ldaps://<DC>:636" samt Base-DN ein. Eine klassische Domäne mit dem Namen "ad.company.local" verwendet implizit die Base-DN "DC=ad,DC=company,DC=local". Der Bind-DN beschreibt das Servicekonto, etwa "CN=svc_keycloak,CN=Users,DC=ad,DC=company,DC=local". Ferner müssen Sie auch das Passwort des Service-Accounts angeben, das auf das AD zugreifen darf. Keycloak prüft diese Daten dann, baut eine Verbindung auf und liest die Struktur des Verzeichnisses aus.

Weiter geht es mit den Attributzuordnungen: Sie weisen in Keycloak "sAMAccountName" dem internen Feld "username" zu, ordnen "mail" der E-Mail-Adresse zu und nutzen "givenName" und "sn" für Vor- und Nachnamen. Diese Werte wandern später in die Token-Strukturen, die die jeweiligen Dienste von Keycloak ausgeliefert bekommen und interpretieren.

Keycloak erzeugt sowohl Access-Tokens als auch ID-Tokens, die alle relevanten LDAP-Attribute enthalten. Dabei sollten Sie sich die Unterschiede klar vor Augen führen: Access-Tokens dienen der Authentifizierung, ID-Tokens der Autorisierung. Innerhalb der Kommunikation zwischen jeweiligem Dienst und Keycloak wandern beide Token-Arten hin und her. Damit diese Kommunikation funktioniert, sind sowohl in Keycloak als auch im jeweiligen Dienst Anpassungen nötig. Von zentraler Bedeutung in Keycloak ist das sogenannte Claim-Mapping, mit dem Keycloak die Gruppenangaben aus LDAP (Feld "memberOf") in so genannte Claims übersetzt, also Berechtigungsaussagen im späteren, von Keycloak ausgestellten JWT-Token.

Sie öffnen dazu die Keycloak-Einstellungen und legen einen "Mapper" an. Dieser übersetzt "memberOf"-Einträge in einen Keycloak-Claim namens "groups". Die Werte erscheinen als vollständige LDAP-DN-Einträge. Diese Struktur ist wichtig, weil angebundene Dienste direkt aus dem Claim heraus Rollen ableiten. Diese Struktur im ausgestellten Token entscheidet also über Erfolg oder Misserfolg vom Zusammenspiel von Keycloak und dem jeweiligen Dienst.

ArgoCD beispielsweise liest die Claims "groups" und "preferred_username" aus. Ersteren Wert nutzt es für sein eigenes RBAC-System, also seine Rollenverwaltung. Letzteres dient dazu, für neue Nutzer, die zuvor noch nicht an ArgoCD angemeldet waren, automatisch einen Account mit passendem Benutzernamen anzulegen. Auch das ist ein wichtiger Punkt, den Sie im Kontext von Keycloak und seiner Anbindung an andere Dienste im Kopf haben sollten: Unser Werkzeug wickelt den IAM-Teil ab, trotzdem benötigt in der Regel jeder Nutzer für jeden Dienst einen eigenen Account. Dieser wird zwar implizit angelegt und mit dem IAM so verknüpft, dass er ohne laufendes IAM nicht verwendbar ist. Formal ist ein Benutzeraccount in ArgoCD aber ein eigenes Asset oder je nach Sichtweise eine eigene Liability, die in etwaiger Dokumentation zu beachten ist. Auditoren fragen nach solchen Details.

Andere Dienste lesen möglicherweise andere Attribute aus als ArgoCD – oder zusätzliche. Sie tun insofern gut daran, für jeden konfigurierten Dienst in Keycloak das Mapping gleichartig anzulegen, etwa durch die Verwendung derselben Namen für die einzelnen Claims. So vermeiden Sie Verwirrung und beugen Inkonsistenzen vor. Alle Tokens signiert Keycloak übrigens über das RS256-Verfahren. Dabei steht Keycloaks öffentlicher Schlüssel über eine eigene URL in JWKS-Format bereit. Dienste rufen diese URL regelmäßig ab und validieren damit die Schlüsselrotation, die Keycloak automatisch umsetzt.

Die konkrete Integration von ArgoCD mit Keycloak beginnt mit dem Erstellen eines dedizierten Clients. Dazu öffnen Sie den Bereich "Clients" und legen den Eintrag "argocd" an. Als Clientprotokoll wählen Sie "OIDC" und die Redirect-URI entspricht der externen Adresse des ArgoCD-Portals, die üblicherweise dem Schema "https://argocd.example.local/auth/ callback" folgt. Keycloak speichert diese Daten und erzeugt eine eindeutige Client-ID sowie ein Secret. Beide Werte bilden die zentrale Grundlage für die spätere Konfiguration in ArgoCD. Notieren Sie sich beide angezeigten Werte für die spätere Verwendung.

Nun aktivieren Sie im Client die Verwendung eines Autorisierungscodes für das Authentifizieren von Clients. Das ist ein ArgoCD-Spezifikum, denn die Software setzt für den Login über den Browser auf die Nutzung von Autorisierungscodes. Andere Dienste handhaben dies möglicherweise anders. Anschließend definieren Sie die Auswertung "Token-Attribute". ArgoCD liest im Betrieb wie beschrieben zwei Claims: den Benutzernamen im Feld "preferred_username" und die Gruppen im Claim "groups". Auf der Keycloak-Seite haben wir die nötigen Einstellungen bereits hinterlegt. Damit ArgoCD die Signaturen dieser Token validieren kann, benötigt der Dienst zusätzlich Zugriff auf die JWKS-URL des Keycloak-Realms. Keycloak stellt diese Adresse automatisch bereit. Sie tragen die URL später direkt in die Konfiguration von ArgoCD ein. Der Dienst lädt die öffentlichen Schlüssel und prüft jedes eingehende Token anhand dieser Daten. Dieser Mechanismus verhindert Manipulationen und stellt sicher, dass ArgoCD ausschließlich Tokens aus dem autorisierten Realm akzeptiert.

ArgoCD speichert seine OIDC-Parameter in der ConfigMap "argocd-cm". Sie öffnen diese Datei über den Befehl

und ergänzen den Abschnitt "dex.config". ArgoCD arbeitet intern mit Dex als Authentifizierungs-Proxy. Dieser verarbeitet die OIDC-Anfragen und reicht die Ergebnisse an ArgoCD weiter. Im Kern wickelt es die Autorisierung und Authentifizierung also gar nicht selbst ab, sondern setzt dafür auf eine Open-Source-Zusatzkomponente. Die Konfiguration von Dex in ArgoCD erhält den Eintrag für den "Issuer", der exakt der URL des Keycloak-Realms entspricht. Anschließend folgen die Endpunkte "auth", "token" und "jwks", die alle innerhalb desselben Pfades liegen. Tragen Sie noch die Client-ID und das Secret aus Keycloak ein. Dex verwendet diese Werte bei jeder Authentifizierungsanfrage.

Nach dem Speichern der Datei reagiert ArgoCD beim nächsten Login sofort auf die neue Einstellung. Eingehende Anfragen führen den Benutzer zum Keycloak-Login-Fenster. Nach erfolgreicher Eingabe der Domänen-Anmeldedaten sendet Keycloak ein signiertes Token zurück und betrachtet den Benutzer damit als authentifiziert. Dex prüft die Signatur, liest die Claims und reicht die Daten an ArgoCD weiter. Der Dienst verwendet die Gruppeninformationen aus dem Claim "groups", um die RBAC-Regeln der Kubernetes-Config-Map "argocd-rbac-cm" auszuwerten. Jede Gruppe aus dem Active Directory, die im Token erscheint, entspricht damit einer Rolle innerhalb von ArgoCD.

An dieser Stelle müssen Sie sich entscheiden, ob Sie in ArgoCD eigene Rollen für die AD-Integration anlegen oder ob Sie die bestehenden ArgoCD-Rollen auf die vorgefundenen Gruppen per Mapping umschreiben. Fast immer empfiehlt sich aber das Hinzufügen eigenständiger Gruppen mit entsprechenden Berechtigungen, statt in den ArgoCD-Standardwerten zu basteln. Denkbar ist außerdem, die Struktur direkt im Active Directory anzupassen.

Ein stabiles Berechtigungsmodell entsteht dabei aus der Kombination von AD-Gruppen, Token-Mapping und ArgoCD-RBAC. Sie haben also auch die Option im AD eindeutige Gruppen für alle Rollen anlegen. Diese besitzen sprechende Namen und erscheinen danach automatisch im "groups"-Claim. Denkbar wäre beispielsweise, im AD eine Gruppe "ArgoCD-Admins" anzulegen. Die Kubernetes-ConfigMap "argocd-rbac-cm" enthält Zeilen im Format

oder

um diesen Gruppen Berechtigungen ("admin" oder "readonly") zuzuweisen. Die eigentlichen Berechtigungen ergeben sich dabei aus den Rollen, deren Umfang Sie in ArgoCD bei Bedarf modifizieren können.

Ein funktionierendes Setup entsteht erst dann, wenn der Betrieb von Keycloak, Active Directory und ArgoCD dauerhaft stabil arbeitet. Geht einmal etwas schief, steht Debugging auf dem Plan. Die interne Fehlerdiagnose beginnt dabei immer auf der Seite von Keycloak. Das Admin-Interface liefert Ihnen eine detaillierte Ereignisliste, in der jeder fehlerhafte Login, jeder LDAP-Verbindungsfehler und jede abgelehnte Authentication Challenge erscheint.

Dort wählen Sie den betroffenen Benutzer, vergleichen die LDAP-Antworten und kontrollieren anschließend die Token-Struktur. Ein JWT-Debugger zeigt den Inhalt des Tokens an und hilft bei der Analyse. Wenn der "groups"-Claim fehlt, liegt die Ursache in der Konfiguration des Claim-Mappings. Wenn "preferred_username" leer bleibt, liefert das AD nicht das richtige Attribut. Eine kurze Anpassung der Zuordnung in Keycloak löst das Problem.

ArgoCD selbst liefert Ihnen ebenfalls einige Details zur Fehleranalyse. Die Logs des Dex-Prozesses zeigen jeden authentifizierten Benutzer und alle Fehler bei der Token-Validierung. Ein typischer Fehler entsteht, wenn ArgoCD die JWKS-URL nicht erreicht. Prüfen Sie in diesem Fall die Firewallregeln oder die TLS-Konfiguration. ArgoCD lädt den Schlüssel automatisch neu, sobald die Verbindung steht. Eine abweichende Systemzeit führt ebenfalls zu Problemen, da Token nur innerhalb einer definierten Zeitspanne gültig bleiben. Mit timedatectl set-ntp true  korrigieren Sie diese Abweichung auf allen Cluster-Knoten.

Sobald ArgoCD erfolgreich arbeitet, lassen sich weitere Anwendungen in derselben Struktur anbinden. Jede Applikation, die OIDC oder SAML implementiert, folgt denselben Schritten: Ein Client in Keycloak, ein Mapper für Attribute und eine Konfigurationszeile in der jeweiligen Anwendung. Zum Beispiel liest Grafana ebenfalls die "groups"-Information aus dem Token und ordnet Benutzern auf Basis dieser Werte Rollen zu. Auch GitLab arbeitet ähnlich und importiert die Gruppenwerte als externe Identitätsmerkmale. Damit entsteht ein durchgängiges Identitätsmodell, das von einem einzigen Verzeichnis stammt und in allen Anwendungen gleich interpretiert wird.

Achten Sie bei allen Anwendungen strikt auf eine konsistente und in sich stimmige Konfiguration. Jede Abweichung führt zu Fehlern in nachgelagerten Systemen. Deshalb erhält jeder Client denselben Mapper für Gruppen und denselben Claim-Namen. Diese Wiederverwendung erhöht die Vorhersehbarkeit der Architektur und reduziert den Wartungsaufwand erheblich. Die Token bleiben in allen Anwendungen identisch und erzeugen dadurch konsistente Benutzererfahrungen und stabile Zugriffsmechanismen.

Ein sauber angebundenes Keycloak-System erweitert die Funktionen eines bestehenden Active Directory, ohne dessen zentrales Rollenmodell zu verändern. Keycloak übernimmt die Authentifizierung, erzeugt die Tokens und verteilt die nötigen Claims an alle angebundenen Anwendungen. Dienste wie ArgoCD verarbeiten diese Claims und setzen sie auf die eigenen Rollen um. Die gesamte Prozesskette erzeugt einen klaren und nachvollziehbaren Datenfluss, der ohne redundante Benutzerverwaltung auskommt und die Verantwortlichkeiten dennoch eindeutig trennt.

IT-Verantwortliche erhalten damit eine Architektur, die jeden Zugriff lückenlos steuert und impliziert per Logeintrag auch dokumentiert. Jede Änderung im Verzeichnis wirkt sich sofort innerhalb der gesamten Plattform aus, da Keycloak keine eigenen Kopien anlegt. In Summe ergibt sich ein Setup, das die Anbindung von Onlinediensten nach den aktuellen Regeln der Kunst erlaubt und dabei zuverlässig funktioniert.