In this document I am going to explain how I enabled a federated single sign-on (SSO) procedure between GBrowse2, Tripal/Drupal and potentially other GMOD applications using the security assertion markup language (SAML) in a sandbox environment. This page explains setting up Drupal with simpleSAMLphp.
Here is a screen cast demonstrating the desired outcome of SSO between a Drupal and a GBrowse instance:
This documentation is provided by Michael Dondrup at the Sea Lice Research Centre, Department of Informatics, University of Bergen, Norway. Please contact me in case you have any suggestions, comments or questions (michael -dot- dondrup <at> ii -dot- uib -dot- no).
For integration of heterogeneous web-applications into a common framework it is often convenient with respect to administration overhead and user experience to provide a common authentication mechanism, also called Federated Identity (FID).
An even tighter experience of system integration can be achieved by requiring only a single login for working with multiple integrated web-applications (single sign-on, SSO). Examples of SSO solutions are OpenID and SAML.
- Running Drupal/Tripal installation
- SimpleSAMLphp + its dependencies
- SimpleSAMLphp Authentication module for Drupal
The installation follows the details outlined on the module page.
To install SimpleSAMLphp, follow the instructions given in its documentation.
If using Debian based Linux distributions, the Debian package might be a more comfortable way of installing SimpleSAMLphp.
If you are not using the package, the installation process consists of,
- Installing the required php extensions and libraries
- downloading the tar.gz package
- extracting the archive into its installation directory
- making the www subdirectory of the simplesamlphp installtion accessible for apache, e.g. by adding the following directive to httpd.conf
<VirtualHost *> ServerName service.example.com DocumentRoot /var/www/service.example.com Alias /simplesaml /var/simplesamlphp/www </VirtualHost>
Possibly enable PHP, but as you have a running Drupal already, we can assume that your web-server is at least running PHP 5.2 anyway.
- Set some configuration options to config/config.php as described in http://simplesamlphp.org/docs/stable/simplesamlphp-install#section_7.
- Set the following configurationoption as required by the Drupal module:
NOTE: Your SimpleSAMLphp SP must be configured to use something other than "phpsession" (the default) for session storage. The alternatives are memcache or sql. The sql option was added in SimpleSAMLphp version 1.7. The simplest solution for folks running SimpleSAMLphp version 1.7 or higher is to edit the SimpleSAMLphp config/config.php by setting store.type => 'sql' and 'store.sql.dsn' => 'sqlite:/path/to/sqlitedatabase.sq3'
The sqlite path can be any path accessible to the web-server (read/write), if the databasse file doesn't exist, it is created.
Check, that the frontpage of SimpleSAMLphp is accessible at the configured location.
Setting up SimpleSAMLphp as a ServiceProvider (SP)
The SimpleSAMLphp_auth module retrieves authetication information from SimpleSAMLphp via its API. SimpleSAMLphp in addition needs to be configured as a Service Provider. Such service provider needs to retrieve the account information from somewhere. This could be, for example, another remote SAML instance (running on different SAML compatible software or another SimpleSAMLphp install) which is configured as an Identity Provider (IdP). There are numerous other options for authentication sources, icluding Radius, openID, or LDAP. Some of the authentication protocols might require to install or activate additional modules in SimpleSAMLphp. A quick guide to link the local install to e.g. the FEIDE test registry is described here.
In order to build the test case in a sandbox install we will create our own very simple configuration-file based authentication for the SP. To achieve this, edit config/authsources.php and edit it to contain a entry 'default-sp' with:
<?php $config = array( 'default-sp' => array( 'exampleauth:UserPass', 'student:student' => array( 'uid' => array('student'), 'eduPersonAffiliation' => array('member', 'student', 'gbrowse'), 'displayName' => array('Vivian Student'), 'mail' => array('firstname.lastname@example.org') ), 'employee:employee' => array( 'uid' => array('employee'), 'eduPersonAffiliation' => array('member', 'employee'), ), ), );
You can keep the other example entries to try different authentication sources. Make sure to leave the 'admin' authentication source in.
Testing the Installation
Before continuing with the installation, you should check that the authetication source is configured correctly.
Point your browser to http://localhost/simplesamlphp or to whatever location the software is configured for. Go to the "Configuration" tab, and check that all required modules are installed and no further error messages appear (you might see a warning about missing HTTPS, that is ol for testing). You might have to provide the admintrator password to access the configuration interface.
Open the "Authetication" tab and click Test configured authentication sources. Choose the default-sp authentication source and log in as student, pw:student.
The result should look like this:
Click Logout to terminate the session.
Installing SimpleSAMLphp Authentication Module in Drupal
- Download the module tarbal for your Drupal version from http://drupal.org/project/simplesamlphp_auth.
- Extract the archive into the sites/all/modules directory of your Drupal installation.
- Log in as an administrator into Drupal
- Activate the module either in the Modules pages (under Other) or using drush:
drush pm-enable simplesamlphp_auth
- Under Administer/User Management a configuration option simpleSAMLphp authentication module settings will appear. Open the settings page.
- Adjust the settings according to your environment, here is an example:
Please note the following important points:
- Installation Directory must be set to the path containing SimpleSAMLphp (or empty if in the default location)
- Authentication source must be one of the sources configured in config/authsources.php, leave blank or use default-sp for the example
- Register users option will generate new user accounts, if the retrieved account doesn't exist already. If this is off, users need to be registered in the Drupal instance as well, otherwise access is denied. Can be used for more fine grained access control to individual instances at the price of loosing most of the administrative relief from the federated identities.
- Allow authentication with local Drupal accounts: It is highly recommended to enable this check-box. Otherwise, you might loose access to your local Drupal instance in case of a misconfiguration.
- The same is true for Which users should be allowed to login with local accounts? Note that this refers to numerical user ids, not names! It is recommended to leave this blank or have at least user-id 1 (site admin) in this field.
- Check the settings carefully, and then click Save.
After logging out of Drupal, you will find a link Federated Login in your Login Block, if that is enabled. This link is for using the federated login and redirects to the SimpleSAMLphp login page. Log in as student:student. Note that the normal login is only for local Drupal accounts and federated accounts will not work with it.
After a successful login, your browser will be redicted to your Drupal account page. Check if the email is successfully taken from the SAML data:
Use the normal Drupal logout to log out from Drupal and all other applications connected to the SAML session.
In case you screw up the configuration or the IdP doesn't work, you might loose access totally. In this case, you need to disable the module via drush:
drush pm-disable simplesamlphp_auth
If you don't have drush installed, temprarily removing the simplesamlphp_auth folder from the modules directory should help.
It might still be difficult to repair a screwed up configuration, because you might be immediately logged out and are then unable to access the configuration page. You might have to edit the module configuration directly in the database in this case.
Securing the Install
Note that the default certificates coming with SimpleSAMLphp are for testing purposes only and provide no security whatsoever, because they are public. When setting up a production environment, proper X509 certificates are required. These can be obtained from a certification authority. The documentation describes also, how to generate and install self-signed certificates. The use of self-signed certificates might be ok in case both IdP and SP are inside the same network or institution.
In addition, HTTPS should be enabled in Apache (at least for the SimpleSAMLphp IdP site) in order to secure authenticity of the site and secure transmission of passwords.
Federating Multiple Drupal/Tripal Instances
Disclaimer: I haven't tested this yet, but it should be quite straight forward. The Drupal Instances can all be installed on different servers. To establish such a setting via SAML authentication, you need access to a global IdP. You can either:
- Configure one of the SimpleSAMLphp installations as an IdP and link up all other installations as SP's
- Configure an additional SimpleSAMLphp installation as an IdP and link up all Drupal installations as SP's
- Use an external (or institution wide) IdP like UK access federation or InCommon or FEIDE (mainly interesting for norwegian institutions) and link all Drupal instances as SP's
- Each Drupal install needs the simplesamlphp_auth module installed and enabled.
- Each Server needs access to the global installation directory of SimpleSAMLphp or its local install.
- Each Drupal instance to federate must be configured to use the same authentication source. This is only relevant in setup 1. The IdP must use the same authentication source (e.g. default-sp) as the Drupal installation using it as a SP. In setups 2. and 3., all SP's must use the same IdP, which will automatically satisfy the condition of same authentication source.
- In all cases you will need to connect to or implement your own non-trivial authentication source, by using one of the authentication modules provided.
Federating Drupal/Tripal and GBrowse
It seems natural to integrate GBrowse and Tripal via SSO, to enable access control to restricted resources in both applications.
This setup requires that one common IdP, e.g. a SimpleSAMLphp instance is configured for this setting. There is no requirement that Drupal, GBrowse and the IdP must be installed on the same server. GBrowse and Drupal must however be configured to use the same authentication source.
To integrate Drupal/Tripal and Gbrowse user authentication, follow these instructions