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


===== Vorbereitung SoSci Survey =====

Aktualisieren Sie Ihre Installlation von SoSci Survey auf Programmversion 3.2.37 oder neuer ([[https://www.soscisurvey.de/download/|Download-Portal]]).

Nach Bestellung des SSO-Moduls können Sie im [[https://www.soscisurvey.de/download/|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"


===== SAML2 via SimpleSAMLphp =====

SoSci Survey greift für die Shibboleth-Anbindung auf die Software [[https://simplesamlphp.org/|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: [[https://simplesamlphp.org/docs/stable/|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.

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

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.

<code conf>
'session.cookie.secure' => true
</code>

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 ([[https://simplesamlphp.org/docs/stable/cron:cron|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.


==== Anpassung der SoSci Survey-Konfiguration ====

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

<code conf>
// ***** 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'
];
</code>

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 [[http://s2survey.net/transfer/|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.


==== Abschluss der Konfiguration ====

=== Schnittstelle ===

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.

<code php>
$info = new SSOAccountInfo('example', $userID);
</code>

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.

=== Konfiguration ===

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:

  - 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.
  - The text in the button (''%%'label'%%'') can be adapted freely.
  - ''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:

{{:de:server:scr.sso-config.png?nolink|Anpassung der SSO-Konfiguration}}

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:

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


=== Konfiguration ===

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.


===== LDAP =====

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.

<code php>
$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'
];
</code>


==== Fortgeschrittene Einstellungen ====

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:


==== Konfigurationsdatei für SSO via LDAP ====

<code php>
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);
	}
	
	...
}
</code>

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

<code php>
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);
	}
	
	...
}
</code>

Die folgenden Berechtigungen können vergeben werden.

|''Account::FEATURE_PUBLISH''|Fragebogen veröffentlichen (Befragungszeitraum eintragen/ändern)|
|''Account::FEATURE_LIBERAL_SAP''|Eventuelle Einschränkungen für die Dauer des Befragungszeitraums aufheben|
|''Account::FEATURE_UPLOAD_IMAGES''|Bilder hochladen|
|''Account::FEATURE_UPLOAD_MEDIA''|Mediendateien hochladen|
|''Account::FEATURE_MAILS''|Serienmails versenden|
|''Account::FEATURE_OVERWRITE_PRESETS''|Server-Vorgaben aufheben (insbesondere individuelle Absenderadressen und Disclaimer beim Serienmailversand verwenden)|
|''Account::FEATURE_SEND_SMS''|Mithilfe der Serienmail-Funktion auch SMS versenden (vorausgesetzt für den Server ist ein SMS-Gateway konfiguriert)|
|''Account::FEATURE_ALPHA''|Eventuell in einer Programmversion vorhandene Features anzeigen, die noch in der Entwicklung/Testphase sind (nicht empfohlen)|


<file php 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;
    }
    
}
</file>




===== Troubleshooting =====

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'').