Verwendung von SSO (Single Sign-On) mit Keycloak

Dieser Artikel zeigt Ihnen, wie Sie Ihre Benutzer auf Keycloak über Single Sign-On (SSO) mit unserer Plattform verbinden können. Diese Funktion ist nur für Unternehmenskunden verfügbar.

Dieser Artikel behandelt die SSO-Integration mit unserer Plattform anhand eines Beispiels mit Keycloak.

• Wenn Sie MS Azure Entra ID verwenden, lesen Sie unseren SSO-Beitrag für Microsoft Azure Active Directory.
• Wenn Sie Okta verwenden, lesen Sie unseren SSO Beitrag für Okta

Dieser Beitrag enthält technische Details für IAM Admins oder Ihre IT
Abteilung, die Keycloak verwalten. Bitte setzen Sie sich mit einem IT-Experten in Verbindun, der Sie bei der Einrichtung der SSO-Verbindung unterstützt.

SSO steht für Single Sign-On. Es handelt sich um einen Authentifizierungsprozess, der es einem Benutzer ermöglicht, auf mehrere Dienste, wie unsere QR Code-Plattform, mit nur einem Satz von Anmeldedaten (wie Benutzername und Passwort) zuzugreifen. Mit SSO müssen sich die Benutzer nicht für jede Anwendung, die sie nutzen, ein anderes Passwort merken, was den Anmeldeprozess vereinfacht und die Sicherheit erhöht, da weniger Anmeldedaten erforderlich sind. Nach der Authentifizierung kann der Benutzer zwischen verschiedenen Anwendungen oder Diensten navigieren, ohne sich erneut anmelden zu müssen.

Ihr Unternehmen agiert als Identity Provider (IDP), der uns Nutzerdaten zur Verfügung stellt. Unsere White-Label-Plattform fungiert als Service Provider (SP), der die Nutzerdaten entgegennimmt und den Nutzern Zugang zu unserem System gewährt.

Grundlegende Informationen über Ihren IDP und unseren SP werden über sogenannte Descriptor URLs ausgetauscht.

Hinter diesen URLs verbergen sich Dateien, die den IDP (Ihr Keycloak) oder SP (unsers White-Label-Plattform) mit Details beschreiben, die die jeweils andere Seite automatisch verarbeiten kann und die bei der Konfiguration helfen.

Die Benutzerinformationen werden über eine SAML 2.0 Nachricht gesendet. In dieser Nachricht werden die Daten in Attributen kodiert. Beim Versenden der Informationen von Ihrem Keycloak bildet ein Outbound Mapper Ihre internen IDP-Felder wie Vorname, Nachname, E-Mail usw. auf SAML 2.0-Attribute ab.

Wenn wir Ihre SAML 2.0-Nachricht erhalten, wandelt unser Inbound Mapper die SAML 2.0-Attribute zurück in unser internes Format und wir melden den Benutzer bei unserer Plattform an.

Als ersten Schritt müssen wir sicherstellen, dass Ihr Keycloak-System bereit ist, ein IDP (Identity Provider) zu sein.

Sie brauchen immer einen Realm, um damit zu arbeiten. In dem Realm sind Benutzer gespeichert. Diese Benutzer haben bestimmte Informationen wie Vorname, Nachname und E-Mail gespeichert. Sie haben auch bestimmte Rollen. Der Realm wird außerdem über einen sogenannten Client mit unserer White Label Plattform verbunden.

Für die SSO-Verbindung von Ihrem Keycloak-System zu unserer White Label Plattform können Sie entweder einen bereits existierenden Realm (mit bereits darin befindlichen Benutzern) verwenden oder einen komplett neuen erstellen.

Wenn Sie einen neuen Realm verwenden möchten, befolgen Sie einfach die folgenden Schritte.

Stellen Sie zunächst sicher, dass Sie in Ihrem Keycloak-System als Administrator angemeldet sind.

Dann klicken Sie auf das Dropdown-Menü direkt unter dem Keycloak-Logo oben links auf dem Bildschirm und auf Create realm.

Im folgenden Bildschirm Geben Sie einen Realm-Namen ein und klicken Sie auf Create. In unserem Beispiel verwenden wir YourCompanyRealm.

Achtung: Bitte achten Sie darauf, dass Sie keine Leerzeichen oder Sonderzeichen für den Realm-Namen verwenden, da dies ein technischer Feldname ist, und dies zu Problemen führen kann. Nach dem Erstellen eines Realms können Sie einen Display Name festlegen, der aussagekräftiger sein kann und auch das Feld ist, das den Benutzern tatsächlich angezeigt wird.

Nachdem Sie den Realm erstellt haben, gehen Sie zu den Realm Settings (im linken Menü).

Gehen Sie zum unteren Ende der Seite, bis Sie die Endpoints sehen können. Dort klicken Sie mit der rechten Maustaste auf

SAML 2.0 Identity Provider Metadata und wählen dann Copy link.

Die kopierte URL sollte in etwa wie folgt aussehen: 

Hinweis: Die SAML 2.0 Identity Provider Metadata Url ist die Descriptor URL Ihres Keycloak Identity Providers.

Nun ist es an der Zeit, unsere Service Provider Konfiguration im White Label Portal einzurichten.

Besuchen Sie unsere Website und melden Sie sich bei Ihrem White-Label-Konto an. Sobald Sie eingeloggt sind, gehen Sie zu Ihren Kontoeinstellungen und wählen Sie die Registerkarte SSO.

Wenn Sie sich mit einem Benutzer aus Ihrem Unternehmen auf unserer Plattform anmelden, können Sie wählen, wie dieser Benutzer auf die Plattform zugreifen kann. Es sind 2 verschiedene Szenarien möglich:

• Benutzer meldet sich als White-Label-Benutzer 1:1 an
• Benutzer kann sich unter verschiedenen White-Label-Benutzern 1:n anmelden

Um mit der Einrichtung der SSO-Verbindung fortzufahren, müssen Sie zunächst einen SSO-Typ auswählen.

Damit Sie die Konzepte so schnell wie möglich verstehen, verwenden wir in diesem Artikel ein Beispiel. Gehen wir von folgenden Annahmen aus:

• Die Benutzer Adam, Eve und Steve arbeiten in Ihrem Unternehmen und benötigen Zugang zur White Label Plattform.
• Sie verwenden Keycloak als Identity Provider (IDP) in Ihrem Unternehmen. Wenn Sie nicht Keycloak, sondern einen anderen IDP haben, brauchen Sie sich keine Sorgen zu machen.
  Sie können unseren allgemeinen SSO-Beitrag lesen.

Achtung: Im Falle von 1:1 fällt eine monatliche Gebühr für jeden Nutzer an.

Wählen Sie Benutzer, wenn Sie möchten, dass ein Benutzer in Ihrem Identity Provider (="IDP-Benutzer") genau einem (1:1) individuellen White Label-Benutzer zugeordnet wird.

Wenn sich ein IDP-Benutzer zum ersten Mal anmeldet, wird der entsprechende White Label-Benutzer erstellt. Im obigen Beispiel wird der IDP-Benutzer Adam als White-Label-Benutzer Adam erstellt, wenn er sich zum ersten Mal anmeldet.

Nehmen wir in diesem Szenario als Beispiel an, dass die White-Label-Plattform einen Benutzer für die Marketing-Abteilung und einen Benutzer für die CustomerService-Abteilung hat.

Wählen Sie Subaccount, wenn Sie möchten, dass ein Benutzer in Ihrem Identity Provider (="IDP-Benutzer") einem oder mehreren (1:n) White Label-Benutzern zugeordnet wird.

Im obigen Beispiel können die IDP-Benutzer Adam und Eve die White Label-Benutzer Marketing und CustomerService verwenden. Der IDP-Benutzer Steve kann nur den White Label-Benutzer CustomerService verwenden.

Bevor sie über SSO verwendet werden können, stellen Sie sicher, dass diese beiden Benutzer in der White Label Platform erstellt werden, indem Sie sie über das Menü Benutzer auf der linken Seite und dann Benutzer erstellen erstellen.

Nach der Erstellung sollte die Benutzerliste wie folgt aussehen:

Inspiration: Die White-Label-Benutzer müssen nicht zwangsläufig einer Abteilung wie Marketing oder Kundenservice zugeordnet sein. Wir verwenden dies hier nur als Beispiel.
Es ist auch durchaus üblich, dass es für jedes

• Land (Österreich, Spanien, Italien, Brasilien, etc.) und/oder
• Marke (MarkeA, MarkeB, MarkeC, etc.) und/oder
• Produktlinie (Schuhe, Hemden, Jacken, etc.)

einen eigenen White-Label-Benutzer gibt.

Der Anwendungsfall kann für jedes Unternehmen anders sein. Überlegen Sie also einfach, wie es für Ihr Unternehmen am sinnvollsten wäre.

Ein IDP-Benutzer agiert dann wie ein Teamleader und kann wählen, unter welchem White Label User er sich anmelden möchte. So können Adam und Eve wählen, ob sie sich als White Label User Marketing oder CustomerService anmelden wollen

Nachdem Sie den SSO Typ ausgewählt haben, müssen Sie die SSO IDP Descriptor URL Ihres Keycloak Identity Providers eingeben. Dies wird benötigt, damit wir grundlegende Informationen darüber erhalten, wie wir Ihre Benutzer mit SAML 2.0 verbinden und authentifizieren können.

Dazu müssen Sie nur die SAML 2.0 Identity Provider Metadata Url, die Sie zuvor gespeichert haben, in das Feld kopieren.

Nach der Eingabe der SSO IDP Descriptor URL werden die Service-URLs aus der Descriptor URL extrahiert und die Felder für die SSO Signon Service URL und die SSO Logout Service URL werden vorausgefüllt.

Wenn keine URLs angezeigt werden, geben Sie diese bitte manuell ein. Die SSO Logout Service URL ist optional. Ist die URL gesetzt, wird der Nutzer beim Abmelden von der QR Code Plattform zu dieser URL weitergeleitet. Er kann sich dann optional auch von seinem IDP (Keycloak) abmelden.

Für ein Keycloak-System sollte die Url etwa so aussehen: 

Klicken Sie auf die Schaltfläche Verbinden am unteren Ende des Formulars, um die Verbindung zu Ihrem Keycloak zu initialisieren.

Wir müssen nun einen sogenannten Client in Ihrem Keycloak-System erstellen. Dieser Client ist die Brücke zwischen Ihrem Keycloak und unserem White Label Platform Service Provider.

Wechseln Sie nun zurück zu Ihrem Keycloak-System und in den Realm, mit dem Sie zuvor gearbeitet haben (in unserem Beispiel YourCompanyRealm).

Klicken Sie auf das Menü Clients und dann auf Import Client (rechts neben dem Button Create client).

Klicken Sie auf dem Import-Client Schirm auf Browse und wählen Sie die Deskriptor-XML-Datei aus, die Sie zuvor heruntergeladen haben.

Der Inhalt der Deskriptor-XML-Datei wird dann in den Textbereich Resource file geladen und die Client-ID wird automatisch gesetzt.

Sie können den Client optional im Feld Name benennen, wenn Sie möchten. In unserem Beispiel nennen wir ihn QR Code Platform.

Klicken Sie auf Save, um den neuen Client zu speichern.

Als nächstes müssen wir unseren Outbound Mapper in Keycloak so konfigurieren, dass er Felder wie Vorname, Nachname und E-Mail sowie die Rollen der Benutzer übertragen kann.

In dem soeben erstellten Client (https://auth.webapp-portal.com/xxx) klicken Sie auf die Registerkarte Client Scopes.

Sie sollten nun einen Dedicated Scope (erste Zeile) und einen SAML-Rollenlisten-Scope (letzte Zeile) sehen.

Im Client Scope sehen Sie bereits die Liste der Felder, die unser Service Provider von Ihrem Keycloak Identity Provider benötigt (dank dem Descriptor XML, das wir zuvor hochgeladen haben).

Nun müssen wir nur noch die Zuordnung dafür konfigurieren. Dazu beginnen wir mit dem Vornamen. Dazu klicken wir auf firstname in der Spalte Name.

Klicken Sie nun auf das Dropdown-Menü User Attribute und wählen Sie den Eintrag firstName. Klicken Sie auf Save.

Als nächstes machen Sie dasselbe für den Nachnamen.

Nun machen Sie das Gleiche für die E-Mail.

Da die Mapper im Dedicated scope durch den Upload der Descriptor XML automatisch erstellt wurden, stimmen die SAML Attribute Names bereits mit den Einträgen im SSO IDP Inbound Mapping in unserem Service Provider überein. Es ist also keine weitere Konfiguration auf dem White Label Platform Service Provider bezüglich des Mappings notwendig.

Wenn Sie den Subaccount (1:n)-Ansatz bei der Erstellung von Benutzern auf der White Label Platform verwenden möchten (wie zuvor besprochen) oder Sie SSO für Administratoren und Manager verwenden möchten, müssen Sie dafür IDP-Rollen konfigurieren.

Mit den folgenden Schritten gelangen Sie zum entsprechenden Bildschirm:

• Klicken Sie auf Clients im linken Menü
• Klicken Sie auf den zuvor erstellten Client - in unserem Beispiel ist es die QR Code Plattform
• Klicken Sie auf den Button Create Role, um eine neue Rolle zu erstellen
  

Wenn Sie den SSO-Typ Subaccount (1:n) gewählt haben, müssen Sie angeben, welcher IDP-Benutzer auf welchen White Label-Benutzer Zugriff haben soll.

Dazu müssen wir für jeden White Label User eine zusätzliche Rolle in den Keycloak Client Rollen erstellen. Der Name der Rolle muss mit dem Namen des White Label Users identisch sein.

Standardmäßig kann sich Ihr Admin-Benutzer direkt über Benutzername und Passwort bei unserer Whitelabel-Plattform anmelden. Es ist jedoch auch möglich, SSO zu verwenden, um sich als Admin oder Manager anzumelden.

Für diesen Fall gibt es 2 spezielle Rollen: whitelabel_admin und whitelabel_manager.

In unserem Beispiel haben wir 2 Benutzer in der Organisation, die ein Admin/Manager sind. Benutzer John sollte ein Admin im Whitelabel-Portal sein, benötigt also die Rolle whitelabel_admin, Benutzer Monica sollte ein Manager sein, benötigt also die Rolle whitelabel_manager.

Zu diesem Zweck müssen wir zwei zusätzliche Rollen mit den Namen whitelabel_admin und whitelabel_manager in Keycloak erstellen. Die Namen der Rollen müssen genau so lauten.

Nachdem wir alles konfiguriert haben, ist es an der Zeit, Benutzer in Keycloak hinzuzufügen, damit sie auf die White Label Plattform zugreifen können.

Im SSO-Typ "1:n" Szenario oder wenn Sie einem Benutzer eine Admin- oder Managerrolle geben wollen, gehen Sie wie folgt vor.

Klicken Sie in Keycloak auf das Menü Users (auf der linken Seite), wählen Sie dann einen Benutzer (in unserem Beispiel Adam) und klicken Sie im Tab Role mapping auf Assign Role.

Wählen Sie im Dropdown-Menü oben links Filter by clients, um nur unsere Kundenrollen zu sehen und geben Sie webapp-portal.com in das Suchfeld ein, um nur die relevanten Rollen zu sehen.

Da Adam im 1:n-Szenario auf die White Label User Marketing und CustomerService zugreifen können soll, wählen Sie Marketing und CustomerService für den User Adam aus. Klicken Sie dann auf Assign.

Umgekehrt sollte Benutzer John ein White Label Admin sein. In diesem Fall wählen Sie die Rolle whitelabel_admin.

Im SSO-Typ "1:n" Szenario oder wenn Sie einer Gruppe eine Admin- oder Managerrolle geben wollen, gehen Sie wie folgt vor.

In unserem Beispiel möchten wir, dass jeder, der in der Marketing-Abteilung (Mitglied der Gruppe Marketing-Department) ist, Zugriff auf den White Label User Marketing hat.

Normalerweise haben Sie bereits Gruppen für Ihre Abteilungen wie Marketing und CustomerService und haben ihnen Benutzer zugewiesen. Für dieses Beispiel gehen wir davon aus, dass dies nicht der Fall ist und erstellen sie jetzt.

Geben Sie den Namen der Gruppe ein, z. B. Marketing Department, und klicken Sie auf Create.

Nun stellen wir sicher, dass jeder in der Gruppe "Marketingabteilung" die Rolle "Marketing" zugewiesen bekommt. Dazu öffnen wir die Gruppe Marketing-Department und klicken dann auf Assign role.

Das Gleiche können Sie für eine Gruppe CustomerService Abteilung und zum Beispiel auch für eine White Label Admin Gruppe oder White Label Manager Gruppe tun.

Nach der Konfiguration der Gruppen ist es an der Zeit, den Gruppen Benutzer zuzuweisen.

Klicken Sie auf das linke Menü Groups, wählen Sie die Gruppe Marketing Department und klicken Sie auf Add member.

Wählen Sie im Popup die Benutzer aus, die der Gruppe angehören sollen, in unserem Beispiel soll der Benutzer Adam der Gruppe Marketing Department angehören, und klicken Sie dann auf Add.

Jetzt würden der Benutzer Adam und jeder andere Benutzer, der der Gruppe Marketing Department hinzugefügt wird, Zugriff auf die Rolle Marketing erhalten und somit auf den White Label User Marketing zugreifen können.

In diesem Abschnitt sehen Sie, wie das White-Label-Konto nach der ersten Anmeldung der Benutzer für die 2 verschiedenen SSO-Typen aussieht.

Wenn sich ein IDP-Benutzer zum ersten Mal über SSO anmeldet, wird ein White Label-Benutzer mit demselben Namen erstellt. Im folgenden Beispiel sehen Sie die 3 IDP-Benutzer Adam, Eve und Steve, die als White Label-Benutzer im Abschnitt Benutzer erstellt wurden.

Wenn sich ein IDP-Benutzer zum ersten Mal auf unserer Plattform anmeldet, wird ein Subaccount mit der Rolle SSO erstellt und die passenden White Label-Benutzer werden diesem Subaccount zugewiesen. Sie können die Unterkonten im Bereich Konto unter der Registerkarte Subaccounts sehen.

Der folgende Screenshot zeigt den IDP-Benutzer Adam, der den White-Label-Benutzern Marketing und CustomerService zugewiesen ist.

Um die SAML 2.0-Kommunikation zwischen Ihrem Identity Provider (IDP) und unserem Service Provider (SP) zu testen, können Sie das Browser-Plugin SAML-tracer installieren.

• Firefox
• Chrome

Nachdem Sie das SAML-Tracer-Popup geöffnet haben...

1. beginnen Sie mit einem SSO-Anmeldeprozess
2. Sie werden sehen, dass sich die Liste am oberen Rand des Popups mit HTTP-Anfragen füllt.
3. Klicken Sie auf die Anfrage, die als SAML-Anfrage in oranger Farbe markiert ist.
4. Wählen Sie den Reiter Summary (oder SAML für alle Details im XML-Format). Sie können überprüfen, ob die Daten (z.B. Role) korrekt übertragen wurden. In diesem Fall wurde die Rolle whitelabel_admin übertragen. Das ist genau das, was wir brauchen, damit sich dieser Benutzer als Whitelabel-Portal-Admin anmelden kann.