Einführung / Konfiguration des FirstSpirit-Servers / Einrichten von SSO über das FS-SAML-Login-Modul
Einrichten von SSO über das FirstSpirit SAML Login Modul
Allgemeine Informationen zu SAML 2.0
| Inhaltsverzeichnis |
Die Security Assertion Markup Language (SAML) in der Version 2.0 ist ein XML-basiertes Framework, welches Möglichkeiten bietet, browserbasiert sicherheitsrelevante Informationen auszutauschen. So können innerhalb eines Unternehmens oder auch zwischen Unternehmen Informationen über Identität, Attribute und Berechtigungen einer Entität (meist ein Benutzer) gemeinsam genutzt werden. Damit kann unter anderem in Verbindung mit anderen Tools Single Sign-on realisiert werden. SAML V2.0 wurde von OASIS (Organization for the Advancement of Structured Information Standards) entwickelt. Eine technische Übersicht zu SAML V2.0 ist hier zu finden: technische Übersicht von OASIS.
Beschreibung des Moduls
Grafische Übersicht des Login-Prozesses (vereinfacht)
Das FirstSpirit SAML Login Modul unterstützt eine „Single sign-on“ (SSO) Anmeldung in FirstSpirit per SAML V2.0 Standard. Anders als bisher gewohnt, entfällt auf diese Weise eine direkte Anmeldung über FirstSpirit. Stattdessen erfolgt die Anmeldung unterstützt durch das SAML-Login-Modul über einen Identity Provider.
Wenn sich der Benutzer im Browser mit FirstSpirit (--> Service Provider) verbinden will, wird die Authentifizierungsanfrage an das SAML Login Modul geleitet. Hier wird ein SAML-Request aufgebaut und über den Browser an einen Identity Provider weitergeleitet. Dieser bearbeitet den Request. Sollte der Nutzer bereits über eine gültige Session eingeloggt sein, wird eine SAML-Response über den Browser an das SAML Login Modul gesendet. Sollte der Benutzer nicht angemeldet sein, wird über den Identity Provider eine Authentifizierung durchgeführt, und danach die SAML-Response gesendet. Die Response wird dann vom Modul verarbeitet und der Benutzer in FirstSpirit eingeloggt. Die Daten, die die Response enthält, werden in FirstSpirit gespeichert und ggf. der Benutzer hier neu angelegt.
Einschränkungen
Beim Einsatz des Moduls sind einige Einschränkungen zu beachten:
- Beim Einsatz des SAML Login Moduls muss beachtet werden, dass nur der Vorgang des Einloggens realisiert ist. Es gibt zwischen dem Modul und dem Identity Provider keine Kommunikation über das Ausloggen eines Benutzers. Das führt dazu, dass wenn sich der Benutzer beim Identity Provider ausloggt, dies keine direkte Auswirkung auf die Anmeldung bei FirstSpirit hat. Ebenso wird der Benutzer nicht aus dem Identity Provider ausgeloggt bzw. die Session ungültig, sollte er sich bei FirstSpirit abmelden.
- Die benutzte API, OneLogin's SAML Java Toolkit, bietet nur „Single Group/ Role Attribute“.
- Es kann nur jeweils ein Identity Provider per FirstSpirit Server konfiguriert werden. Es können keine verschiedenen Identity Provider pro Projekt konfiguriert werden.
- Das Parsen und Generieren von (Service Provider oder Identity Provider) SAML-XML-Metadaten ist nicht implementiert.
Installation und Einrichtung des Moduls
Installation über den ServerManager
Zunächst wird das Modul in der gewünschten Version über den ServerManager installiert (siehe auch Seite Module).
Konfiguration fs-saml.conf
Die Konfiguration kann über den Button „Konfigurieren“ im FirstSpirit ServerManager oder direkt über die Datei fs-saml.conf vorgenommen werden.
Globale Web-Apps konfigurieren
Nach der Installation des Moduls muss die Web-Komponente noch den globalen Web-Apps hinzugefügt werden (siehe auch Seite Web-Applikationen).
Authentifizierung über JAAS einrichten
Zur Benutzerauthentifizierung verwendet FirstSpirit den Java-Standard JAAS (Java Authentication and Authorization Service). Mehrere JAAS-Login-Module sind bereits in FirstSpirit integriert und stellen unterschiedliche Verfahren zur Benutzerauthentifizierung bereit.
Zur Verwendung des SAML-Login-Moduls muss die Konfigurationsdatei fs-jaas.conf angepasst werden (siehe auch Seite Konfiguration des Anmeldevorgangs (fs-jaas.conf)):
/* FirstSpirit start page with SSO: ContentCreator, SiteArchitect */
websso {
de.espirit.firstspirit.server.authentication.FSTicketLoginModule sufficient;
de.espirit.firstspirit.server.authentication.LdapLoginModule optional section="LDAP";
de.espirit.firstspirit.server.authentication.FSUserLoginModule optional;
de.espirit.firstspirit.authentication.saml.SamlLoginModule sufficient;
};
Die Datei fs-jaas.conf enthält alle Login-Module, die für diese Anwendung konfiguriert sind. Bei Eintragung mehrerer Login-Module werden diese in der angegebenen Reihenfolge abgearbeitet, bis eine erfolgreiche Authentifizierung des Benutzers erfolgt ist. Zusätzlich kann über die Flags required, sufficient, optional und requisite das Gesamtverhalten bei der Authentifizierung über die angegebenen Login-Module gesteuert werden.
 |
Das Saml-Login-Modul muss in der Datei fs-jaas.conf an der letzten Position stehen! |
Hintergrund: Das SAML-Login-Modul führt einen Redirect im Browser aus. Dabei wird der SAML-Request über den Browser zum Identity Provider weitergeleitet. Dieser Redirect soll nur stattfinden, wenn bisher noch keine Authentifizierung (über ein anderes Login-Modul) erfolgreich war.
Für das oben angegebene Beispiel heißt das:
- Zuerst wird ein Login über das FSTicketLoginModule versucht. Zur Authentifizierung reicht ein Berechtigungsnachweis (Ticket) aus, der zuvor vom FirstSpirit-Server generiert wurde. Der Berechtigungsnachweis wird bei der Anmeldung auf der FirstSpirit-Startseite generiert und über den Webbrowser weitergereicht. Dieses Verfahren ist das Standardverfahren nach der FirstSpirit-Installation. Das Flag sufficient sorgt dafür, dass bei einem erfolgreichen Login die weiteren Login-Module nicht mehr durchlaufen werden. Schlägt der Login fehl, wird das nächste Login-Modul versucht.
- Im nächsten Schritt werden zuerst das LdapLoginModule (Authentifizierung gegen einen externen LDAP-Server) und anschließend das FSUserLoginModule (Authentifizierung gegen die FirstSpirit-interne Benutzerdatenbank) durchlaufen. Das Flag optional sorgt dafür, dass unabhängig davon, ob der Login hier erfolgreich ist oder fehlschlägt, das nächste Login-Modul in der Liste aufgerufen wird.
- SamlLoginModule (sufficient): Zuletzt wird die Authentifizierungsanfrage an das SAML Login Modul geleitet. Haben die vorhergehenden Module noch keinen erfolgreichen Login ausgeführt, wird über das SamlLoginModule ein SAML-Request aufgebaut und über den Browser an einen Identity Provider weitergeleitet. Dieser bearbeitet den Request. Sollte der Nutzer bereits über eine gültige Session eingeloggt sein, wird eine SAML-Response über den Browser an das SAML Login Modul gesendet. Sollte der Benutzer nicht angemeldet sein, wird über den Identity Provider eine Authentifizierung durchgeführt, und danach die SAML-Response gesendet. Die Response wird dann vom Modul verarbeitet und der Benutzer in FirstSpirit eingeloggt. Die Daten, die die Response enthält, werden in FirstSpirit gespeichert und ggf. der Benutzer hier neu angelegt.
Konfigurationsparameter
In der Konfiguration des Moduls wird eine Variablen-Ersetzung vorgenommen:
# The following variable substitutions are available in parameter values:
# ${saml:NameID} - the NameId of the SAML login
# ${saml:NameIDFormat} - the NameId format of the SAML login
# ${saml:SessionIndex} - the SessionIndex of the SAML login
# ${saml:SessionNotOnOrAfter} - the SessionNotOnOrAfter value of the SAML login, ISO-8601 compatible
# ${saml:attributeName} - a SAML assertion attribute value
# ${fs:propertyName} - a FirstSpirit server configuration property
# ${request:URL} - current HTTP request URL. The returned URL contains a protocol, server name, port number, and server path, but it does not include query string parameters.
# ----- ----- ----- ----- -----
# Signatures and encryption is only available if a keystore and the key parameters are configured
Diese Variablen kommen entweder aus der FirstSpirit Server-Konfiguration oder sind Attribute des SAML-Login-Vorgangs.
In der Konfiguration sollte der Keystore hochgeladen werden (Button „Keystore-Datei aktualisieren“ - siehe auch Konfiguration des Keystores) sowie ID- und URL-Parameter für Identity und Service Provider konfiguriert werden (siehe Identity Provider konfigurieren). Nicht benötigte Zeilen mit Variablen-Ersetzungen sollten auskommentiert werden.
|
Weitere Anhaltspunkte für die individuelle Konfiguration können auch den SAML Metadaten entnommen werden. |
Es gibt zwei Arten von Konfigurations-Parametern:
Die zuvor beschriebenen Variablen beziehen sich hauptsächlich auf die benutzerspezifischen Parameter, und werden bei jedem Login-Prozess ausgewertet. Das bedeutet auch, dass die Benutzer-Attribute in FirstSpirit im Hinblick auf die SAML-Attribute aktualisiert werden.
Globale Parameter
Kurzbeschreibung | Parametername | mögliche Werte * |
|---|---|---|
Keystore password | keystore.password | String |
Identity provider public certificate alias | key.idp.alias | String |
Keystore type | keystore.type | jks / pkcs12 |
Service provider private key and public certificate alias | key.sp.alias | String |
Service provider private key password | key.sp.password | String |
Identity provider identifier | idp.entityid | String |
Identity provider single sign on service url | idp.sso.url | String |
Service provider identifier | sp.entityid | ${fs:URL} |
Service provider assertion consumer service url | sp.assertion.url | ${fs:URL} / ${request:URL} |
Algorithm used for service provider signing purposes | saml.signature.algorithm | rsa-sha1 / dsa-sha1 / rsa-sha256, rsa-sha384 / rsa-sha512 |
If the service provider expects a NameID | saml.want.nameid | true / false |
NameID format | saml.nameid.format | urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified |
If the service provider expects a NameID to be encrypted | saml.want.nameid.encrypted | true / false |
The requested AuthNContext sent in the AuthNRequest by the service provider, comma separated list, empty for none | saml.requested.authncontext | urn:oasis:names:tc:SAML:2.0:ac:classes:Password |
The AuthNContext comparison parameter, defaults to 'exact' | saml.requested.authncontext.comparison | exact |
If the service provider expects assertions to be encrypted | saml.want.assertions.encrypted | true / false |
If the service provider expects assertions to be signed | saml.want.assertions.signed | true / false |
If the service provider expects messages to be signed | saml.want.messages.signed | true / false |
Create or update user from the SAML attributes (true) / Authenticate existing FirstSpirit user only (false) | import.user | true / false |
(*) Hinweis: Die hier aufgeführten Werte dienen nur als Beispiele. In einer individuellen Konfiguration sind beliebige, von diesen Beispielen abweichende Werte möglich und sinnvoll.
Benutzerspezifische Parameter
Kurzbeschreibung | Parametername | mögliche Werte * |
|---|---|---|
User login mapping | user.login | ${saml:NameID} |
User email mapping | user.email | ${saml:email} |
User phone numer mapping | user.phone | ${saml:phone} |
User abbreviation mapping | user.abbreviation | ${saml:initials} |
Full user name mapping | user.realname | ${saml:givenName} ${saml:surname} |
User groups mapping, comma separated list of group names | user.groups | ${saml:groups} |
Match mode for external group names | group.match.mode | contains (default) |
External group name mapping, allows you to add a prefix or suffix to a SAML group name | group.name | ${saml:groupName} |
User section information mapping | user.section | ${saml:SessionIndex} |
(*) Hinweis: Die hier aufgeführten Werte dienen nur als Beispiele. In einer individuellen Konfiguration sind beliebige, von diesen Beispielen abweichende Werte möglich und sinnvoll.
Weitere Konfiguration
Identity Provider konfigurieren
Damit die SAML-Authentifizierung funktioniert, muss immer auch die Konfiguration des Identity Providers angepasst werden. Um eine Vertrauensbeziehung zwischen dem Service Provider (hier: FirstSpirit) und einem Identity-Provider einzurichten, muss:
- mindestens die Client-ID (in der Konfiguration frei wählbar) und
- die URL der FS Root-Webanwendung dem Identity Provider bekannt gemacht werden.
Eine vollständige Dokumentation ist an dieser Stelle nicht möglich.
Bitte konsultieren Sie hierfür die Dokumentation des verwendeten Identity Providers.
Keystore konfigurieren
SAML-Request und SAML-Response müssen signiert sein. Die dazu erforderlichen Zertifikate müssen in der Konfiguration des Identity Providers und der Konfiguration des Service Providers hinterlegt sein.
Das Zertifikat und der Private-Key des Service Providers können entweder mit Java Keytool angelegt werden. Einige Identity Provider, z. B. Keycloak, bieten aber auch eine Funktion an, um den Keystore anzulegen, zu exportieren und direkt zu verwenden (z. B. Keycloak).
Probleme erkennen und beheben
Debugging aktivieren
Für das Debug-Logging wird Java-Util-Logging (JUL) verwendet. Es muss an der Stelle aktiviert werden, wo der Login verarbeitet wird. Das ist entweder der Webserver direkt (z. B. Tomcat, logging.properties in conf-Verzeichnis) oder, beim Einsatz des Jetty-Moduls, der FirstSpirit-Server (fs-server.conf):
#SAML
de.espirit.firstspirit.authentication.saml.level = FINE
com.onelogin.level = FINE
Bei eingeschaltetem Debug-Logging wird jeder SAML-Request und jeder SAML-Response in der entsprechenden Logdatei (z. B. in catalina.*.log unter tomcat/log oder fs-server.log bei der Verwendung von Jetty) ausgegeben.
|
Für das Debugging sollte eine Verschlüsselung der SAML-Nachrichten deaktivert werden. Wenn HTTPS benutzt wird, ist eine zweite Verschlüsselung meist nicht nötig. Nach erfolgreicher Inbetriebnahme kann die Verschlüsselung wieder aktiviert werden. |
Unterstützung durch die SAML Developer Tools
Ist eine Authentifizierung über das FirstSpirit SAML Login Modul nicht erfolgreich, kann das unterschiedliche Ursachen haben. Bei der Suche nach der Fehlerursache und der Analyse der Debug-Ausgaben (SAML-Request und-Response) können die folgenden SAML Developer Tools unterstützen:
https://www.samltool.com/online_tools.php
- Schritt 1) Base64 Decode + Inflate ,
- Schritt 2) XML Pretty Print
Mögliche Fehlerursachen
Wenn der Response nicht ankommt
Bei der Analyse der Debugausgaben stellt sich heraus, dass bei der Authentifizierungsanfrage an das SAML Login Modul zwar:
- ein SAML-Request aufgebaut und
- über den Browser an einen Identity Provider weitergeleitet wird (in diesem Fall ist das Login-Formular im Browser sichtbar),
- der SAML-Response jedoch nicht im Tomcat ankommt
Mögliche Fehlerursachen:
1) Konfiguration des Identity Providers fehlt oder ist fehlerhaft (siehe Identity Provider konfigurieren)
2) Konfiguration des Proxys bzw. der Firewall fehlt oder ist fehlerhaft
Wenn der Response ankommt, aber keine Assertions enthält
Bei der Analyse der Debugausgaben stellt sich heraus, dass bei der Authentifizierungsanfrage an das SAML Login Modul zwar:
- ein SAML-Request aufgebaut und
- über den Browser an einen Identity Provider weitergeleitet wird (in diesem Fall ist das Login-Formular im Browser sichtbar) und
- der SAML-Response auch im Tomcat ankommt, aber keine Assertions (= User-Attribute), sondern nur einen Status-Code mit einer Fehlermeldung enthält
Mögliche Fehlerursachen:
1) Konfiguration des Identity Providers fehlt oder ist fehlerhaft (siehe Identity Provider konfigurieren)
2) Das Attribut-Mapping der SAML Assertions auf FirstSpirit ist fehlerhaft. In diesem Fall hilft es, sich die Assertions der SAML-Response anzuschauen und dann die Mapping-Konfiguration in FirstSpirit entsprechend anzupassen.
Wenn die Signaturüberprüfung von Request und Response fehlschlägt
Mögliche Fehlerursachen:
1) Die Konfiguration des Keystores fehlt oder ist fehlerhaft (siehe Keystore konfigurieren)
2) Die Zertifikate für die Signierung sind nicht in der Konfiguration des Identity Providers und/oder in der Konfiguration des Service Providers hinterlegt.