Single Sign-On (SSO) via Shibboleth/SAML2

Für SoSci Survey an additional module is available to enable login via Shibboleth/SAML2 or LDAP. This chapter explaines preparation and use of this additional module.

Update your installtion of SoSci Survey to version 3.2.37 or later (Download-Portal).

After ordering the SSO-Module you can download the “Single Sign-On (SSO)” here Download-Portal. The ZIP-File contains a file component.SingleSignOn.php. Copy this PHP-file to the subdirectory /modules/ of your installation of SoSci Survey.

Open the Server-Settings of SoSci Survey.

• Please ad your licence-key in the tab Server at software licence server and save for SoSci Survey to retrieve the upgraded licence containing the SSO-Modul.
• Under Server → Licence Server (down) please fill in your licence-key for SoSci Survey and confirm with OK to retrieve the upgraded SoSci Survey licence that supports SSO.
• Under add-ons → activate components (down) “Single Sign On (SSO)” should be listed, now. Click activate components (below). A checkbox symbol indicates successfull activation.
• At Register → please select the option “Button for SSO-Login under Login-Password” as Single-Sign-On Mode.

For Shibboleth-Connection SoSci Survey accesses the software SimpleSAMLphp which must be installed on the same server as SoSci Survey.

SimpleSAMLphp is available as a package for several linux distributions and can be downloaded and copied to the server. In the second case, configuration should be saved outside simplesamlphp-directory, to simplify updates.

Installing SimpleSAMLphp is not trivial. A step-by-step instruction is provided here: SimpleSAMLphp Documentation.

After installing and configuring SimpleSAMLphp you can access the software via you own URL. Under Federation → show meta-data you find an URL to give to your Identity-Provider (IdP) so they can unlock your SoSci Survey (Service Provider, SP) for Campus-Login. At the IdP a “transient connection” must be configured, (not a persistant connection).

Please inform IdP, that you need the following user attributes:

• PersistentID (e.g. eduPersonTargetedId)
• First name
• Second name
• E-mail adress

For the interaction of SimpleSAMLphp and SoSci Survey to function, please ad the session-path of SoSci Survey in the config.php of SimpleSAMLphp. The exact path depends on your installation.

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

Also please adapt the session.cookie.secure configuration for otherwise authentification will not work when using HTTPS/SSL (which of course needs to be supported by your server) in the latest version of SimpleSAML, Chrome and Edge.

'session.cookie.secure' => true

Make sure that under Federation the funtion Metarefresh: fetch metadata is working and that the Cronjon for regular retrieval of meta-data is active (SimpleSAMLphp: Cron).

If login works test if configured sources of authentification works under authentification → and check if the attributes are shown as listed above (first name, second name, e-mail adress and and ID), everything is ready for the connection of SoSci Survey.

Now please edit the file system/config.php in your SoSci Survey directory. Please add the following content before the end (?>):

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

What you need to adjust is…

• the path where SoSci Survey finds your installation of SimpleSAMLphp ('simplesaml').
• the internal identifier which you used in config/authsources.php for SoSci Survey ('sp', Standard: default-sp)
• the URL of your Identity Provider ('saml:idp') which you find in the configuation of SimpleSAMLphp as attribute 'idp'.

Please leave all other settings unchanged, for testing the general connection and transmitted keys for the data, first.

When opening SoSci Survey on your server, under the regular sign-in button a button SSO Setup should show. Clicking on it will bring you to your identity provider. After logging in with your Campus-Login you should see an overview “Shibboleth Data”. Please save this overview and send it via e-mail or encrypted via s2survey.net/transfer to SoSci Survey. On this basis we can generate an adapted SSO module for you.

Further we need the following information from you:

• How long shall SSO user accounts (including projects) be saved after the last login to SoSci Survey? We recommend 2 years.
• Shall existing user accounts on your server be changed to SSO-accounts, when first logging in via SSO? Accounts are identified by the e-mail-adress.

You recieve the adapted SSO-Modul for your server via e-mail. Please save this PHP-file under plugins/SSO/ in the SoSci directory.

This line in the file contains a distinct identifier for your SSO (example in the example below). This identifier is used by SoSci Survey, to attribute user accounts to the IdP.

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

You can adapt this identifier if you want. Later changes are not possible. Please note down the identifier, you will need it in the next step.

Still some changes to the file system/config.php are required. You already added the part for SSO-Setup. In the part $GLOBALS['oFb']['sso']['idp']['setup'] the following needs to be adapted:

1. The entry contains a key different from setup – please use the same key that was used in the file plugins/SSO/.
2. The text of the button ('label') can be adjusted freely.
3. SSOSetup needs to be replaced with the correct name in two places. The correct name is the file name of the SSO-PHP file, you received via e-mail. SSOExample in the following demonstration.

The 'label' can be choosen freely. It is a text that can can be displayed on the button of the login-page. It is possible to use an english and a german text.

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

You can choose whether users have both optins for logging in the SoSci Survey Server-Settings under registration → Single-Sign-On mode. If you also have users with local user accounts we recommend activating to show both options. Via the link /admin/?sso=sosci the login page can be accessed at any time, and you can log in for example with your admin user account. It is useful to deactivate the registration of new local user accounts. This can be done at registration under registration.

Configuration of a LDAP-Login also requires an adapted configuration in /plugins/SSO (see below an example for a configuration file).

Also edit the file system/config.php in your SoSci Survey directory. Add the following content before (?>), and adjust the settings in your infrastructure.

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

The connection between the identity provider (via SAML or LDAP) and the user administration of SoSci Survey is made via a class that inherits either SSO4SAML2Handler or SSO4LDAPHandler.

A central method for both SSO connections is decodeData(). It receives the data from SAML or LDAP and defines the name and e-mail address for the user account as well as its authorizations. The data for the user account and the authorizations are written to an instance of the SSOAccountInfo class. In the Server-Settings in the Rights management you can set general authorizations for all users of the server. In addition, the SSO connection allows differentiated authorizations to be assigned depending on the transmitted attributes.

The assignment of authorizations for uploading media files and sending serial mails in a SAML connection to employees (but not to students) could look like this:

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 a LDAP-enviroment group membership will be checked.

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

The following authorizations can be given:

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

If SSO-Login does not work, please check the SoSci Survey Errorlog unter /system/logfiles/errorlog.txt first and the logfile of SimpleSAMLphp (e.g. /var/log/syslog).