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.

Wichtig 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.

Wichtig 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}

User section information mapping

user.section

${saml:SessionIndex}
${saml:SessionNotOnOrAfter}
${saml:NameIDFormat}

   

(*) 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

Vor der Inbetriebnahme von SAML, aktivieren sie bitte das Logging für das FirstSpirit SAML Login Modul.

Das Debug-Logging muss an der Stelle aktiviert werden, wo der Login verarbeitet wird. Das ist entweder der Webserver direkt (z. B. Tomcat) oder, beim Einsatz des Jetty-Moduls, der FirstSpirit-Server:

#SAML
log4j.logger.de.espirit.firstspirit.authentication.saml.SamlLoginModule=DEBUG
log4j.logger.com.onelogin=DEBUG

Bei eingeschaltetem Debug-Logging wird jeder SAML-Request und jeder SAML-Response als XML in der entsprechenden Logdatei (z. B. im Tomcat-Log) ausgegeben.

Wichtig 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

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.

© 2005 - 2022 Crownpeak Technology GmbH | Alle Rechte vorbehalten. | FirstSpirit 2022.12 | Datenschutz