Keycloak SAML2 SSO
26.4.7 erstellt. Ältere oder neuere Versionen sollten ebenfalls funktionieren. Die Konfigurationsschritte können leicht abweichen und die Benutzeroberfläche kann anders aussehen.Einführung
Verbinden Sie Flexopus über SAML2 für Single Sign-On (SSO) mit Keycloak. Mit der Integration können Sie über Ihr Keycloak Directory verwalten, welche Nutzer Zugriff auf Flexopus haben sollen, und diese dazu verpflichten, ihre Keycloak-Zugangsdaten für den Login zu verwenden.
Basierend auf den SAML2-Einstellungen in Flexopus können Sie Nutzerprofile nach dem ersten erfolgreichen SAML2 SSO-Loginversuch automatisch erstellen lassen. Dadurch vermeiden Sie die manuelle Erstellung von Nutzern in Flexopus.
Einrichtungsanleitung
Folgen Sie der Schritt-für-Schritt-Anleitung, um die Integration zu konfigurieren. Die Anleitung enthält außerdem Best Practices und Lösungen für einige häufige Fehler während der Konfiguration. Falls Sie dennoch Unterstützung bei der Einrichtung benötigen, wenden Sie sich gerne an unser Support-Team unter support@flexopus.com.
SCHRITT 1 - SAML2-App erstellen
Navigieren Sie in Flexopus als Administrator zu Dashboard > Globale Einstellungen > Authentifizierung. Klicken Sie auf Anbieter hinzufügen und wählen Sie die Option SAML2 SSO aus.
Laden Sie die Metadatendatei herunter.
Öffnen Sie Ihre Keycloak Admin-Konsole in Keycloak und wählen Sie Clients > Import client aus.
Laden Sie die Flexopus-Metadatendatei in Keycloak hoch.
Sie müssen manuell den Namen Flexopus und die Beschreibung Workplace Management Software eingeben. Klicken Sie auf den Button Speichern.
Öffnen Sie die Access Settings.
Root URL: URL der Flexopus-AnwendungHome URL: URL der Flexopus-AnwendungIdP-initiated SSO URL name: Identisch mit der Callback (ACS) URLIDP initiated SSO Relay State: initiate-sp-login
Öffnen Sie Signature and Encryption.
Metadata descriptor URL: Geben Sie die URL der Flexopus-Metadatendatei ein.Use metadata descriptor URL: AktivierenEncryption algorithm: AES_256_GCMKey transport algorithm: RSA1_5
Speichern Sie die Änderungen.
Öffnen Sie Client Scope und wählen Sie den dedizierten Scope aus.
Klicken Sie auf Mappers > Add predefined scope. Wählen Sie X500 email, X500 givenName und X500 surname aus. Klicken Sie auf Add.
Nun müssen wir den UPN hinzufügen. Wählen Sie Add mappers > By configuration aus.
Die Zuordnung sollte wie folgt aussehen:
Sie können außerdem die Attribute department, jobtitle, phone und costcenter synchronisieren, sofern diese als Textfelder im System vorhanden sind. Weitere Informationen finden Sie in der Zuordnung hier:
Vanessa Erk
In Ihrer Flexopus-Instanz können Sie nun die folgende URL unter METADATA URL hinterlegen. Öffnen Sie Configure > Realm settings > Endpoints. Kopieren Sie die SAML 2.0 Identity Provider Metadata URL.
SCHRITT 2 - Flexopus konfigurieren
Navigieren Sie in Flexopus zu Dashboard > Einstellungen > Authentifizierung und wählen Sie den erstellten SAML2-Anbieter aus. Aktivieren Sie SAML2 SSO und fügen Sie die Metadata URL in das Konfigurationsfeld ein.
Geben Sie den Namen für den SAML2-Login-Button ein, der auf der Login-Seite angezeigt werden soll. Empfehlung: „SSO Login“.
Optional: Aktivieren Sie die Synchronisierung der Felder, die Sie in den SAML2-Einstellungen konfiguriert haben, zum Beispiel jobtitle oder department.
Legen Sie in den Sicherheitseinstellungen die erlaubten Domains für SSO auf * (Stern) fest und drücken Sie ENTER. Dadurch kann sich jeder Nutzer in Ihrem Verzeichnis anmelden.
Standardmäßig werden SAML2 SSO-Nutzer nach ihrem ersten Loginversuch automatisch registriert. Dadurch müssen Nutzerprofile nicht vor dem ersten Login manuell erstellt werden. Sie können diese Einstellung bei Bedarf deaktivieren, dies wird jedoch nicht empfohlen.
SCHRITT 3 - Konfigurieren, wer sich anmelden darf
Wenn Sie jetzt versuchen, sich in Flexopus anzumelden, wird eine Fehlermeldung angezeigt, da die Login-Berechtigungen aus Ihrem Keycloak-Nutzerverzeichnis noch nicht konfiguriert wurden. Weisen Sie der Anwendung einen Testnutzer zu und testen Sie die Verbindung in Flexopus.
Öffnen Sie die Keycloak-Einstellungen und legen Sie fest, welche Nutzer oder Gruppen auf die Anwendung zugreifen dürfen. Es wird empfohlen, den Login für die gesamte Organisation zu aktivieren, sofern keine spezifischen Zugriffseinschränkungen bestehen. Dieser Ansatz reduziert den laufenden Pflegeaufwand für Zugriffsrechte und verringert mögliche Supportanfragen zur Login-Konfiguration.
SCHRITT 4 - Optional: memberOf-Gruppensynchronisierung
Optional können Sie ein Array von Gruppen über das SAML2-Attribut memberOf an Flexopus senden. Auf diese Weise können Sie Gruppen über Keycloak in Flexopus verwalten. Weitere Informationen finden Sie in diesem Artikel:
Vanessa Erk
Navigieren Sie in Flexopus als Administrator zu Dashboard > Einstellungen > Authentifizierung. Klicken Sie auf den vorkonfigurierten SAML2-Anbieter und suchen Sie die Einstellung Gruppen synchronisieren. Standardmäßig ist diese Einstellung deaktiviert. Ändern Sie sie auf Array.
Navigieren Sie in Keycloak als Administrator zu den Mappers und fügen Sie eine neue Attributzuordnung memberOf hinzu. Wählen Sie Add Mapper > By configuration > Group list.
Melden Sie sich erneut an und prüfen Sie anschließend, ob die Gruppen übertragen wurden.
Sobald Sie eine Gruppe zugewiesen und getestet haben, können Sie die folgenden Änderungen in Flexopus erwarten: Die Gruppen werden mit einer externen Statuskennzeichnung aktualisiert oder erstellt. Das bedeutet, dass Sie die Gruppen nicht lokal in Flexopus bearbeiten können. Sie können weder die Namen ändern noch Nutzer hinzufügen oder Nutzer aus der Gruppe löschen. Die Single Source of Truth ist die Gruppenstruktur in Ihrem Keycloak Directory.
Sie können die Gruppen für das Zugriffsmanagement innerhalb von Flexopus ähnlich wie andere interne Gruppen oder Systemgruppen verwenden. Weitere Informationen zu Gruppen finden Sie hier:
Vanessa Erk
Fehlerbehebung / FAQ
Server responded with an unsuccessful status:
urn:oasis:names:tc:SAML:2.0:status:Responder, message: authentication_expired
Manchmal ist Keycloak im Hintergrund mit LDAP konfiguriert und die Verbindung ist schreibgeschützt. Flexopus benötigt eine persistente NameID. Dafür muss Flexopus eine persistente ID in das Nutzerprofil schreiben. Da LDAP schreibgeschützt ist, schlägt dies mit einem Fehler fehl. In der Regel wird angezeigt, dass die Authentifizierung abgelaufen ist.
Sie haben nun zwei Optionen, um dies zu lösen:
Option A:
Setzen Sie die NameID auf „transient“ statt „persistent“ und aktivieren Sie die Einstellung „force name id format“.
Option B:
Ich erhalte beim Login einen 500-Fehler.
Wenn Sie einen 500-Fehler erhalten, haben Sie möglicherweise die URLs oder Attribute falsch konfiguriert. Prüfen Sie die Einstellungen anhand der Anleitung erneut. Wenn Sie das Problem nicht finden können, kontaktieren Sie uns unter support@flexopus.com. Wir verfügen über Serverprotokolle, mit denen wir nachvollziehen können, wo das Problem liegt.
Kann ich den UPN der Nutzer ändern?
Wie Sie wissen, steht UPN für Unique Principal Name. Eindeutige Attribute sollten niemals geändert werden. Insbesondere der UPN des Nutzers sollte gleich bleiben. Er kann eine Nummer oder ein anderer eindeutiger Wert sein. Externe Anwendungen identifizieren Nutzer anhand ihres UPN. Wenn Sie ihn ändern, riskieren Sie, dass in Flexopus ein neuer Nutzer erstellt wird. Dennoch kann es Gründe geben, den UPN zu ändern. Kontaktieren Sie uns in diesem Fall unter support@flexopus.com. Wir können Sie unterstützen, indem wir die UPNs und External IDs der Nutzer löschen, damit Sie die UPNs in Ihrem IdP ändern können.
Kann ich auch die Profilbilder der Nutzer synchronisieren?
Leider unterstützt das SAML2 SSO-Protokoll keine Synchronisierung von Profilbildern.
Kann ich auch die Profilbilder der Nutzer synchronisieren?
Leider unterstützt das SAML2 SSO-Protokoll keine Synchronisierung von Profilbildern.
Unterstützt Flexopus Identity Provider (IdP) Initiated Single Sign-On Login?
Ja und nein. Wir stellen einen Workaround für IdP-initiierte Logins bereit. Sie müssen den Parameter initiate-sp-login für den RelayState konfigurieren. Dadurch wird die IdP-initiierte Login-Anfrage in einen SP-initiierten Login umgewandelt. Auf diese Weise können wir einen sicheren Login-Prozess gewährleisten. Grund: Ein klassischer IdP-initiierter Login würde Hackern einen Man-in-the-Middle-Angriff ermöglichen. Durch einen SP-initiierten Login können wir dies vermeiden. Dieser Artikel erklärt die Gründe ausführlicher: https://www.identityserver.com/articles/the-dangers-of-saml-idp-initiated-sso
authentication_expired-Fehler
Server responded with an unsuccessful status: urn:oasis:names:tc:SAML:2.0:status:Responder, message: authentication_expired
Manchmal ist Keycloak im Hintergrund mit LDAP konfiguriert und die Verbindung ist schreibgeschützt. Flexopus benötigt eine persistente NameID. Dafür muss Flexopus eine persistente ID in das Nutzerprofil schreiben. Da LDAP schreibgeschützt ist, schlägt dies mit einem Fehler fehl. In der Regel wird angezeigt, dass die Authentifizierung abgelaufen ist.
Sie haben nun zwei Optionen, um dies zu lösen:
Option A: empfohlene Lösung
Option B: transiente NameID
Setzen Sie die NameID auf „transient“ statt „persistent“ und aktivieren Sie die Einstellung „force name id format“.