Single Sign-On (SSO) via Shibboleth/SAML2

Für SoSci Survey ist ein Zusatzmodul verfügbar, welches die Anmeldung via Shibboleth/SAML2 oder LDAP erlaubt. Im folgenden wird die Vorbereitung zur Nutzung dieses Zusatzmoduls erläutert.

Aktualisieren Sie Ihre Installlation von SoSci Survey auf Programmversion 3.2.37 oder neuer (Download-Portal).

Nach Bestellung des SSO-Moduls können Sie im Download-Portal das Modul „Single Sign-On (SSO)“ herunterladen. Die ZIP-Datie enthält eine Datei component.SingleSignOn.php. Kopieren Sie diese PHP-Datei in das Unterverzeichnis /modules/ Ihrer Installation von SoSci Survey.

Öffnen Sie die Server-Einstellungen von SoSci Survey.

• Tragen Sie zunächst im Karteireiter Server bei Softwarelizenz Server Ihren Lizenzschlüssel ein und speichern Sie, damit SoSci Survey um das SSO-Modul ergänzte, aktualisierte Lizenz abruft.
• Unter Server → Softwarelizenz Server (unten) tragen Sie bitte Ihren Lizenzschlüssel für SoSci Survey ein und rufen mit OK die aktuelle Lizenz für SoSci Survey mit SSO-Unterstüzung ab.
• Unter Erweiterungen → Komponenten aktivieren (unten) sollte in der Liste „Single Sign On (SSO)“ auftauchen. Klicken Sie auf den Knopf Komponenten aktivieren (unten), anschließend sollte ein Kreuzchen vor dem Modul angezeigt werden.
• Unter Registrierung → wählen Sie nun für Single-Sign-On Modus die Option „Knopf für SSO-Login unter dem Login-Passwort“

SoSci Survey greift für die Shibboleth-Anbindung auf die Software SimpleSAMLphp zurück. Diese muss auf demselben Server installiert werden, auf welcher auf SoSci Survey läuft.

Es gibt SimpleSAMLphp als Paket für unterschiedliche Linux-Distributionen. Ebenso kann die Software heruntergeladen und auf den Server kopiert werden. Wenn Sie die zweite Möglichkeit nutzen, sollten Sie die Konfiguration außerhalb des simplesamlphp-Verzeichnis ablegen, um Aktualisierungen zu vereinfachen.

Die Installation von SimpleSAMLphp ist nicht ganz trivial, wird in folgender Anleitung aber Schritt für Schritt beschrieben: SimpleSAMLphp Documentation

Nach Installation und Konfiguration von SimpleSAMLphp können Sie Software über eine eigene URL aufrufen. Dort finden Sie unter Föderdation → Meta-Daten anzeigen eine URL, welche Sie Ihrem Identity-Provider (IdP) mitteilen können, damit dieser Ihre Installation von SoSci Survey (Service Provider, SP) für den Campus-Login freischaltet. Auf dem IdP muss für den SP eine „transient connection“ konfiguriert werden (keine „persistent connection“).

Teilen Sie dem IdP bitte mit, dass Sie folgende Attribute der Nutzer:innen benötigen:

• PersistentID (z.B. eduPersonTargetedId)
• Vorname
• Nachname
• E-Mail-Adresse

Damit das Zusammenspiel von SimpleSAMLphp mit SoSci Survey funktioniert, tragen Sie in der config.php von SimpleSAMLphp bitte den Session-Pfad von SoSci Survey ein. Der genaue Pfad hängt von Ihrer SoSci Survey Installation ab.

'session.phpsession.savepath' => '/var/www/s2survey/html/system/session'

Weiterhin passen Sie bitte die Konfiguration für session.cookie.secure an, sonst funktioniert die Authentifizierung bei Verwendung von HTTPS/SSL (was Ihr Server selbstverständlich unterstützen sollte) in der aktellen Version von SimpleSAML nicht in Chrome und Edge.

'session.cookie.secure' => true

Stellen Sie nun sicher, dass unter Föderation die Funktion Metarefresh: fetch metadata funktioniert und dass der Cronjon zum regelmäßigen Abruf der Metadaten aktiv ist (SimpleSAMLphp: Cron).

Wenn der Login unter Authentifizierung → Teste die konfigurierten Authentifizierungsquellen funktioniert, und wenn dort die o.g. Attribute (Vorname, Nachname, E-Mail-Adresse und eine ID) angezeigt werden, dann ist alles bereit für die Anbindung von SoSci Survey.

Nun bearbeiten Sie bitte die Datei system/config.php in Ihrem SoSci Survey Verzeichnis. Fügen Sie vor dem Ende (?>) folgenden Inhalt ein:

// ***** Single Sign On (SSO) *****
// Absolute path to the SimpleSAMLPHP directory
$GLOBALS['oFb']['sso']['simplesaml'] = '/var/www/shibboleth/simplesaml/';
// ID configured for the login in (see SimpleSAMLPHP -> config/authsources.php)
$GLOBALS['oFb']['sso']['sp'] = 'SoSciSurvey';
// Information about the Identity Provider (IdP)
$GLOBALS['oFb']['sso']['idp']['setup'] = [
    'label' => 'SSO Setup',
    // For the IDP URL see SimpleSAMLPHP -> config/authsources.php
    'saml:idp' => 'https://YOUR-IDP-URL-HERE/idp/shibboleth',
    'handler.file' => 'plugins/SSO/SSOSetup.php',
    'handler.class' => 's2survey\account\SSOSetup'
];

Anpassen müssen Sie hier…

• den Pfad, wo SoSci Survey Ihre Installation von SimpleSAMLphp findet ('simplesaml').
• die interne Kennung, welche Sie in config/authsources.php für SoSci Survey verwendet haben ('sp', Standard: default-sp)
• die URL Ihres Identity-Providers ('saml:idp'), diese finden Sie auch in der Konfiguration von SimpleSAMLphp als Attribut 'idp'.

Belassen Sie die weiteren Einstellungen bitte wie gehabt, es geht zunächst darum, die generelle Anbidung zu testen und die übermittelten Schlüssel für die Daten zu prüfen.

Wenn Sie anschließend SoSci Survey auf Ihrem Befragungsserver aufrufen, sollte unter dem regulären Anmeldungsfeld ein Knopf SSO Setup erscheinen. Klicken Sie diesen Knopf. Sie sollten nun zum Identity Provider weitergeleitet werden. Nach den Anmeldung mit dem Campus-Login sollten Sie eine Übersicht „Shibboleth Data“ sehen.

Speichern Sie diese Übersicht und übermitteln Sie diese via E-Mail oder verschlüsselt via s2survey.net/transfer an SoSci Survey. Auf diese Basis können wir dann ein angepasstes SSO-Modul für Sie erstellen.

Weiterhin benötigen wir folgende Informationen von Ihnen:

• Wie lange sollen SSO-Benutzerkonten (inkl. Projekten) nach dem letzten Login in SoSci Survey gespeichert bleiben? Wir empfehlen 2 Jahre.
• Sollen existierende Benutzerkonten auf Ihrem Befragungsserver in SSO-Konten umgewandelt werden, wenn der erste Login via SSO erfolgt? The E-Mail adress would be used for identification, then.

Das SSO-Modul, welches wir für Ihren Server anpassen, erhalten Sie per E-Mail. Bitte speichern Sie diese PHP-Datei unter plugins/SSO/ im SoSci-Verzeichnis.

In der Datei finden sie folgende Zeile, die eine eindeutige Kennung für Ihren SSO enthält (im Beispiel ist das example). Diese Kennung verwendet SoSci Survey, um Benutzerkonten dem IdPs zuzuordnen.

$info = new SSOAccountInfo('example', $userID);

Sie können diese Kennung nun anpassen, falls gewünscht. Eine spätere Änderung ist nicht mehr möglich. Notieren Sie sich die Kennung, Sie benötigen Sie gleich.

Als nächstes ist in der Datei system/config.php noch eine Anpassung erforderlich. Sie hatten bereits den Teil zum SSO-Setup eingefügt. Im Teil $GLOBALS['oFb']['sso']['idp']['setup'] wird jetzt folgendes geändert:

1. Der Eintrag erhält einen anderen Schlüssel als setup – bitte verwenden Sie hier denselben Schlüssel, der auch in der Datei unter plugins/SSO/ verwendet wurde.
2. The text in the button ('label') can be adapted freely.
3. SSOSetup needs to be replaced by the correct name in two places. The correct name is the file name of the SSO-PHP-Datei, you received via e-mail. SSOExample in the following demontration:

Das 'label' können Sie frei wählen, es ist der Text, welcher ggf. auf dem Knopf im Login-Formular angezeigt wird. Auch die Angabe einer deutschen und englischen Beschriftung ist möglich:

    'label' => [
        'de' => 'Campus-Login Unsere Hochschule',
        'en' => 'Campus Login Our Univerity'
    ],

Zuletzt können Sie in den Server-Einstellungen von SoSci Survey unter Registrierung → Single-Sign-On Modus auswählen, ob die Nutzer:innen beide Login-Optionen zur Auswahl angeboten bekommen oder nicht. Falls Sie auch Nutzer:innen haben, die ein lokales Benutzerkonto angelegt hatten, empfehlen wir zunächst die Option „Auswahl anbieten“.

Über den Link /admin/?sso=sosci kann jederzeit das klassische Login-Formular aufgerufen werden, damit Sie sich z.B. im admin Benutzerkonto einloggen können.

Es ist zielführend, die Registrierung neuer lokaler Benutzerkonten zu deaktivieren. Dies können Sie im Karteireiter Registrierung bei dem Punkt Registrierung ändern.

Die Konfiguration eines LDAP-Login erfordert ebenfalls eine angepasste Konfiguration unter /plugins/SSO (Beispiel für eine Konfigurationsdatei s. unten).

Bearbeiten Sie außerdem die Datei system/config.php in Ihrem SoSci Survey Verzeichnis. Fügen Sie vor dem Ende (?>) folgenden Inhalt ein, und passen Sie die Angaben an Ihre Infrastruktur an.

$GLOBALS['oFb']['sso']['idp']['example'] = [
    // Label to display on the login form (may be an array with keys 'de' and 'en')
    'label' => 'LDAP Login',
    // The PHP file and class to be used for decoding the response
    'handler.file' => 'plugins/SSO/SSO_LDAP_Example.php',
    'handler.class' => 's2survey\account\SSO_LDAP_Example',
    // The LDAP server to use
    'ldap.host' => 'ldaps://ads.example.com',
    // The DN base for users
    'ldap.base' => 'OU=Users,OU=LM,OU=IAM,DC=ads,DC=example,DC=com',
    // If we need a separate user for the lookup, specify a full distuingished name (DN) here and the password
    // 'ldap.user' => 'CN=specuser,OU=Users,OU=LM,OU=IAM,DC=ads,DC=example,DC=com',
    // 'ldap.pass' => 'PASSWORD_IN_PLAIN_TEXT'
];

Die Verbindung zwischen dem Identity Provider (via SAML oder LDAP) und der Benutzerverwaltung von SoSci Survey erfolgt über eine Klasse, welche entweder SSO4SAML2Handler oder SSO4LDAPHandler beerbt.

Eine zentrale Methode für beide SSO-Anbindungen ist die decodeData(). Sie nimmt die Daten von SAML oder LDAP entgegen und definiert neben Name und E-Mail-Adresse für das Benutzerkonto auch dessen Berechtigungen. Die Daten für das Benutzerkonto und die Berechtigungen werden in eine Instanz der Klasse SSOAccountInfo geschrieben.

Sie können in den Server-Einstellungen in der Rechte-Verwaltung allgemeine Berechtigungen für alle Nutzer:innen des Servers einstellen. Darüber hinaus erlaubt die SSO-Anbindung es, abhängig von den übermittelten Attributen differenzierte Berechtigungen zu vergeben.

Die Vergabe der Berechtigungen zum Upload von Mediendateien und zum Versand von Serienmails in einer SAML-Anbindung an Beschäftigte (nicht aber an Studierende) könnte aussehen wie folgt:

protected function decodeData($authority, \SAML2\XML\saml\NameID $nameID, array $attributes): SSOAccountInfo
{
	$info = new SSOAccountInfo('uniname', $cn);
 
	...
 
	// eduPersonScopedAffiliation
	if (
		array_key_exists('eduPersonScopedAffiliation', $attributes) &&
		is_array($attributes['eduPersonScopedAffiliation']) &&
		in_array('staff@example.com', $attributes['eduPersonScopedAffiliation'])
	) {
		$info->addFeature(Account::FEATURE_UPLOAD_MEDIA);
		$info->addFeature(Account::FEATURE_MAILS);
	}
 
	...
}

In eine LDAP-Umgebung würde die Gruppenmitgliedschaft überprüft.

protected function decodeData(array $data): SSOAccountInfo
{
	$cn = $this->getFirstValue($data, 'cn');
	$dn = $this->getFirstValue($data, 'dn');
	$info = new SSOAccountInfo('uniname', $cn);
 
	...
 
	if ($this->memberOf($dn, 'CN=STAFF,OU=F,OU=Groups,OU=UNINETZ,DC=ad,DC=example,DC=com')) {
		$info->addFeature(Account::FEATURE_UPLOAD_MEDIA);
		$info->addFeature(Account::FEATURE_MAILS);
	}
 
	...
}

Die folgenden Berechtigungen können vergeben werden.

SSO_LDAP_Example.php

<?php
namespace s2survey\account;
 
use Account;
 
class SSO_LDAP_Example extends SSO4LDAPHandler
{
 
    /**
     * Create the distuingished name (DN) from a username as entered in the form.
     * This function is used if there is no @ in the username.
     * Ignore this function, if we need to look up the DN by using a separate user.
     */
    protected function getDNName(string $username)
    {
        return 'CN='.$username.',OU=Users,OU=LM,OU=IAM,DC=ads,DC=example,DC=com';
    }
 
    /**
     * Copy data from LDAP into the account
     * and eventually specify additonal authorisations.
     */
    protected function decodeData(array $data): SSOAccountInfo
    {
        $cn = $this->getFirstValue($data, 'cn');
        $dn = $this->getFirstValue($data, 'dn');
 
        // This must match the ID in the config.php
        $info = new SSOAccountInfo('example', $cn);
 
        // Set validity
        $info->expire = strtotime('+2 years');
 
        // Set name and email address
        $info->nameFirst = $this->getFirstValue($data, 'givenname');
        $info->nameLast = $this->getFirstValue($data, 'sn');
        $info->email = $this->getFirstValue($data, 'mail');
 
        // Eventually allow server administration
        if ($this->memberOf($dn, 'CN=SoSci_Admins,OU=F,OU=Groups,OU=LM,OU=IAM,DC=ads,DC=example,DC=com')) {
            $info->authorized = true;
            $info->addServerAuth(Account::SERVER_ADMIN);
        } else {
            // Specify survey usage auth
            $info->authorized = $this->memberOf($dn, 'CN=SoSci_Users,OU=F,OU=Groups,OU=LM,OU=IAM,DC=ads,DC=example,DC=com');
        }
 
        return $info;
    }
 
    /**
     * Tell whether to convert existing account with the same email address to SSO accounts.
     * @return boolean
     */
    public function getConvertAccount()
    {
        return true;
    }
 
}

Falls der SSO-Login nicht funktioniert, prüfen Sie bitte zunächst das SoSci Survey Errorlog unter /system/logfiles/errorlog.txt und ggf. das Logfile von SimpleSAMLphp (z.B. /var/log/syslog).