Keycloak erleichtert die Verwaltung von Benutzerzugriffen in Nubus durch ein zentralisiertes Single Sign-on (SSO). Endanwendende melden sich nur einmal beim Keycloak Identity Provider (IdP) an und haben Zugriff auf alle angebundenen Webanwendungen. In diesem Artikel führen wir Sie durch die wichtigsten Funktionen der Keycloak Admin Console, um Ihnen den Einstieg in das zentrale Management von Authentifizierungsmöglichkeiten zu erleichtern.
Dank Web Single Sign-on (SSO) müssen sich Benutzer*innen in einer Nubus-Umgebung nur einmal am Identity Provider (IdP) anmelden und können dann nahtlos auf alle angebundenen Anwendungen zugreifen. Kein lästiges Einloggen bei jeder einzelnen Anwendung mehr – das spart Zeit und Nerven. Für Sie als Betreiber bedeutet das: Standardisierte Protokolle übernehmen die sichere Authentifizierung und Autorisierung. Die Passwörter bleiben da, wo sie hingehören – im eigenen Identity Management System.
Dafür sorgt Keycloak – eine Open-Source-Lösung für Identitäts- und Zugriffsverwaltung (Identity and Access Management, IAM). Im Artikel „Univention-App-Highlights: Sichere und zentrale Authentifizierung mit Keycloak“ haben wir bereits ausführlich beschrieben, wie Sie die Keycloak-App in Ihrer Nubus-Umgebung installieren und die grundlegende Konfiguration vornehmen. Dort finden Sie auch wertvolle Hinweise zur Migration von SimpleSAMLphp und Kopano Konnect, die bisherigen Standard-Identity-Provider in UCS und den Hinweis auf unsere Schritt-für-Schritt-Anleitung. Ob Ihr Nubus dabei auf einem klassischen UCS oder künftig vielleicht in einem Kubernetes-Cluster läuft, spielt für die Nutzung der Keycloak-App keine Rolle.
In diesem Artikel möchte ich Ihnen die Benutzeroberfläche der Keycloak Admin Console näher bringen. Diese mag beim ersten Kontakt ein wenig überwältigend wirken, vor allem, wenn Sie aus der SAML-Welt kommen und mit der Terminologie aus der OAuth/OIDC-Welt noch nicht so vertraut sind. Aber keine Sorge – wir erklären Ihnen die wichtigsten Funktionen und Menüpunkte der Admin Console, so dass der Einstieg nicht schwer werden sollte.
Inhaltsverzeichnis
Nubus und Keycloak: Konfigurationen für SAML und OpenID Connect
Nach der Anmeldung über die Kachel Keycloak im UCS-Portal landen Sie zunächst im sogenannten Standard-Realm. Dieser Bereich enthält die allgemeinen Einstellungen und Konfigurationen von Keycloak. Für Sie als Nubus-Admin ist jedoch besonders der ucs-Realm relevant, der speziell auf Univention Corporate Server zugeschnitten ist. Um in diesen Bereich zu gelangen, wählen Sie ihn oben links im kleinen Drop-Down-Menü aus.
Auswahl des UCS-spezifischen Konfigurationsbereiches
Über die linke Navigationsleiste gelangen Sie zu den Realm-Einstellungen. Hier konfigurieren Sie alles, was den Nubus-spezifischen Teil Ihrer Keycloak-Installation betrifft. Gleich auf dem ersten Reiter General unten finden Sie unter Endpoints zwei Links:
- eine URL zum Abruf der XML-Metadaten des Keycloak SAML IdP. Die Metadaten enthalten unter anderem die eindeutige Kennung des IdP (Entity ID), die Endpunkte für Authentifizierungsanfragen oder Logout-Requests sowie die Zertifikate, um die SAML-Kommunikation zwischen IdP und SP zu verschlüsseln und zu signieren.
- den standardisierten .well-known-URI mit der Konfiguration des OpenID Connect Providers. Hier werden Konfigurationsdetails für die Clients bereitgestellt, z. B. Endpunkte für die Authentifizierung, Token-Austausch, unterstützte Scopes und kryptografische Schlüssel.
Diese URLs benötigen Sie, um Ihre Dienste als SAML Service Provider oder OpenID Connect Relying Party mit Keycloak zu verbinden. Die Vertrauensstellung zwischen einem IdP und einem angebundenen Dienst wird dadurch aufgebaut, dass diese Metadaten vorab zwischen den Beteiligten ausgetauscht und in der Konfiguration hinterlegt werden. Je nach Bedarf geben Sie diese Links an die jeweilige Gegenstelle weiter, um die Konfiguration abzuschließen.
LDAP-Verzeichnisdienst in Keycloak: UCS als Identitätsquelle
Ein weiterer wichtiger Menüpunkt ist die User Federation/Benutzerföderierung, zur Konfiguration der Datenquellen, aus denen die Identitäten kommen. Hier finden Sie die vorkonfigurierte Anbindung an den LDAP-Verzeichnisdienst. Keycloak verwendet den UCS-Verzeichnisdienst als Backend für die Benutzerkonten und delegiert die Authentifizierung an diesen.
Wenn Keycloak Attribute zu den Benutzerkonten an die angebunden Dienste weitergeben soll, so müssen diese Attribute in Keycloak definiert werden. In der Voreinstellung sind bereits die gängigsten Attribute wie Vorname, Nachname und E-Mail-Adresse eingerichtet. Falls Sie für die Anbindung Ihrer Dienste weitere Attribute benötigen, können Sie diese ganz einfach über den Reiter Mappers hinzufügen. Klicken Sie auf Add Mapper, wählen Sie als Typ user-attribute-ldap-mapper und füllen Sie das Formular aus.
Mapping eines LDAP-Attributes in Keycloak
Clients: Angebundene Anwendungen verwalten
Der Bereich Clients wird wahrscheinlich einer der Bereiche sein, in dem Sie sich am häufigsten aufhalten werden. Hier finden Sie eine Übersicht über alle angebundenen Anwendungen, ob es sich nun um SAML Service Provider oder OpenID Connect Relying Parties handelt. Mit einem Klick auf einen Eintrag gelangen Sie direkt zur individuellen Konfiguration des jeweiligen Clients.
Um eine neue Anwendung anzubinden, klicken Sie auf den Button Create Client und füllen das Formular aus. Alternativ können Sie auch XML- und JSON-Metadaten importieren – eine besonders flexible Möglichkeit, neue Clients schnell und ohne viel Aufwand einzurichten. Es ist möglich, bestehende Client-Konfigurationen an dieser Stelle in eine Datei zu exportieren. So können Sie diese bei Bedarf sichern oder in einer anderen Umgebung wiederverwenden.
Unsere Keycloak-App bringt bereits vorkonfigurierte SAML-Client-Einträge für alle Portalserver in Ihrer UCS-Domäne mit. Ein Join-Skript sorgt dafür, dass die Metadaten des Keycloak-IdP für Logins am Portal im Dateisystem abgelegt werden. Mit nur wenigen Klicks oder Befehlen können Sie so die Portal-Konfiguration auf UCS-Seite auf den neuen IdP umstellen.
Sollten Sie auf Probleme stoßen oder mehr Informationen über die SAML-Assertions benötigen, schauen Sie ins Logfile /var/log/syslog (siehe auch Abschnitt „Troubleshooting und Best Practices“).
Scopes: Berechtigungen und Zugriffsrechte für Clients im UCS-Realm verwalten
Direkt unter dem Menüpunkt Clients finden Sie die Client Scopes, über die Sie Berechtigungen oder Zugriffsrechte für Clients im UCS-Realm definieren. Der Begriff „Scope“ stammt ursprünglich aus der OAuth/OIDC-Welt und bezeichnet eine Sammlung von Claims (Attributen), die thematisch zusammengehören. Der email-Scope beinhaltet in der Regel zwei Claims: die Mailadresse und die Information darüber, ob die E-Mail-Adresse verifiziert wurde. Die so zusammengefassten Claims können über den Scope als Bündel angefordert bzw. herausgegeben werden.
In der Übersicht der vorhandenen Scopes sehen Sie die Spalte Assigned Type. Hier können Sie einstellen, ob ein Scope standardmäßig (Default) an alle Clients ausgegeben wird, ob er nie (None) ausgegeben wird, oder ob er nur auf Anfrage (Optional) zur Verfügung steht. Dieses Setting ist entscheidend, um zu steuern, wie die Attribute von Keycloak an verschiedene Clients übermittelt werden, und ermöglicht es Ihnen, die Freigabe von Benutzerinformationen gezielt und sicher zu steuern.
Keycloak bietet die Möglichkeit, Scopes gezielt an bestimmte Clients freizugeben. Nachdem Sie unter Client Scopes einen Scope und das globale Standardverhalten des Identity Providers definiert haben, können Sie in den Einstellungen der jeweiligen Clients festlegen, welche dieser Scopes für eine bestimmte Anwendung relevant sind. Dazu navigieren Sie im Menüpunkt Clients zur gewünschten Anwendung und wechseln zum Reiter Client Scopes. Hier sehen Sie eine Übersicht aller global konfigurierten Scopes und können auswählen, welche davon für diesen speziellen Client gültig sein sollen.
Kommandozeilentools
Für die Arbeit mit der Keycloak-App stehen Ihnen zwei Kommandozeilentools zur Verfügung: univention-app configure keycloak und univention-keycloak.
Mit univention-app configure keycloak nehmen Sie die Einstellungen vor, die den Docker-Container bzw. den darin laufenden Keycloak-Prozess betreffen, nicht jedoch die Detail-Konfiguration innerhalb von Keycloak. Sie können sich die aktuellen Einstellungen eines laufenden Containers mit univention-app configure keycloak --list ausgeben lassen. Den vollständigen Überblick über die unterstützten Einstellungen finden Sie in unserer Dokumentation.
Bitte beachten Sie, dass bei Änderungen dieser Einstellungen der Container mit den neuen Settings neu erstellt wird. Keycloak ist dann für einen Moment nicht erreichbar. Das bedeutet für die Praxis, dass Sie z.B. das Loglevel nicht im laufenden Betrieb ändern können. Um das Loglevel beispielsweise auf DEBUG zu setzen, führen Sie folgenden Befehl aus:
univention-app configure keycloak --set keycloak/log/level=DEBUG – dann warten Sie einen Moment, bis der Container wieder läuft.
Übrigens sehen Sie mit dem gewohnten ucr search-Befehl auch ucr-Variablen, die mit „keycloak“ bzw. „kc“ beginnen. Sie werden vom UCS-System außerhalb des Containers benötigt. Diese Variablen mit ucr set zu ändern, zeigt jedoch keine Wirkung. Die so genannten App-Settings für Anwendungen in Containern sollten Sie stets über univention-app configure keycloak --set... setzen.
Das zweite Werkzeug, univention-keycloak, ist ein praktischer Helfer, der viele Aufgaben erleichtert. Das Tool arbeitet mit der REST API von Keycloak und ist für die eigentliche Keycloak-Konfiguration da (siehe univention-keycloak --help): Um etwa einen OIDC Client anzubinden, führen Sie folgenden Befehl aus:
univention-keycloak oidc/rp create \
--client-secret "***" \
--description "Meine OIDC-fähige Applikation" \
--name "Meine App" \
--app-url https://app.example.org \
--redirect-uri https://app.example.org/callback \
app.example.org
Die Werte, die Sie angeben müssen, erhalten Sie vom Betreiber der Client-Anwendung.
Wenn Sie für die Konfiguration eines SAML-Clients das Zertifikat benötigen, mit dem die SAML-Kommunikation für Keycloak signiert bzw. verschlüsselt werden kann, lassen Sie es sich ausgeben – univention-keycloak saml/idp/cert get – oder Sie schreiben es direkt in eine pem-Datei: univention-keycloak saml/idp/cert get --as-pem --output keycloak-idp-cert.pem.
univention-keycloak hilft ebenfalls beim Verwalten von Benutzerattributen, die von UCS nach Keycloak synchronisiert werden, beim Aktivieren der Zwei-Faktor-Authentifizierung, beim Anlegen von Links auf der Login-Seite und mehr. Es bietet sich auch zur Nutzung in eigenen Skripten an, etwa, um größere Mengen von Clients zu importieren. Weitere Anleitungen und Beispiele, wie Sie das Tool einsetzen, finden Sie in unserer Dokumentation.
Troubleshooting und Best Practices
Keycloak bietet verschiedene Möglichkeiten, um effektiv zu überwachen, was in Ihrer Umgebung vor sich geht und potenzielle Probleme frühzeitig zu erkennen. Das Menü Sessions etwa blendet eine Übersicht der aktuellen Anmeldungen am Identity Provider ein.
Übersicht über laufende Sitzungen am Keycloak IdP
Über ein Suchfeld am oberen Rand können Sie die Informationen filtern. Die Funktion Ereignisse gibt hingegen einen Überblick darüber, wer sich wann und von welcher IP-Adresse aus an welchem Dienst angemeldet hat. Die hier eingeblendeten Nutzerkennungen sind die von Keycloak generierten Pseudonyme. Klicken Sie auf einen Eintrag, um die Details zu betrachten.
Gibt es Probleme beim Single Sign-on, untersuchen Sie am besten beide Seiten: Keycloak und die betroffenen Clients. Tipp: Nutzen Sie verschiedene Browser oder Profile, leeren Sie regelmäßig alte Cookies und den Cache – das deckt so manchen Fehler auf. Darüber hinaus sollten Sie einen Blick in die Logfiles werfen. Untersuchen Sie die Logs von Keycloak, der Client-Anwendung und OpenLDAP. Um herauszufinden, welche Anfragen Keycloak an den slapd-Prozess von OpenLDAP sendet, erhöhen Sie im laufenden Betrieb temporär das Loglevel. mit printf 'dn: cn=config\nchangetype: modify\nreplace: olcLogLevel\nolcLogLevel: %s\n\n' stats | ldapmodify -xH ldapi:/// und analysieren dann die Einträge in /var/log/syslog.
Häufige Stolpersteine sind fehlerhafte Zertifikate oder private Schlüssel für die SAML-Kommunikation oder auch die Erreichbarkeit der angegebenen Endpunkte in der Konfiguration. Wenn ein Loadbalancer oder Proxy zwischen Keycloak und der Anwendung steht, kann auch das eine Fehlerquelle sein.
Wenn der Zugriff nicht direkt beim Login am IdP scheitert, sondern erst beim Zugriff auf eine geschützte Web-Ressource, lohnt sich ein genauer Blick auf die erwarteten und tatsächlich übertragenen Attribute oder Claims. Keycloak hat dafür ein praktisches Tool im Angebot: Unter Client Scopes finden Sie für jede konfigurierte Client-Anwendung einen Reiter namens Evaluate. Hier können Sie die betroffene Nutzerkennung eingeben und sich anzeigen lassen, welche Tokens Keycloak für diesen Client und diese Nutzerkennung generieren würde. So können Sie Unterschiede zwischen den erwarteten und den übermittelten Informationen schnell erkennen und korrigieren.
Teilen Sie Ihre Erfahrungen mit Keycloak mit der Univention Community
Keycloak hat sich als leistungsstarke und flexible Lösung für die zentrale Authentifizierung und Autorisierung in einer UCS-Umgebung erwiesen. Mit seinen umfangreichen Funktionen, von der Verwaltung von Clients über die Konfiguration von Scopes bis hin zu den fortschrittlichen Überwachungs- und Debugging-Tools, bietet Keycloak UCS-Administrierenden alle notwendigen Werkzeuge, um die Sicherheit und Effizienz der UCS-Umgebung zu optimieren.
Haben Sie bereits Erfahrungen mit Keycloak gemacht und die App erfolgreich in Ihrer Umgebung implementiert? Dann freuen wir uns über Ihr Feedback und Ihre Erfahrungsberichte. Steht die Migration zu Keycloak noch an? Dann zögern Sie nicht, sich bei Fragen an uns zu wenden oder sich im Forum mit anderen Administrator*innen auszutauschen.
Kommentieren Sie diesen Beitrag und besuchen Sie das Univention-Forum!
