Simple SAML

WARNING: This plugin should only be enabled and configured by system administrators as it affects how users log in to ResourceSpace.

This plugin allows users to log on to ResourceSpace using a SAML compliant single sign-on (SSO) Identity Provider (IdP)

Important information

  • Please note that use of this plugin is dependent on your organisation having implemented a SAML 2.0 compliant single sign-on solution (IdP). Configuration of this plugin will require co-operation between your ResourceSpace hosting provider and the administrators of your Single Sign-On system.
  • Implementing a new single sign-on solution is not trivial and is normally an organisation wide decision requiring a significant amount of work. If you are at all unsure as to whether you have a single sign-on solution in place please speak to your IT team.

Preliminary Configuration

This plugin utilises the simplesamlphp application (https://simplesamlphp.org/). Please refer to the documentation for this project if you require more advanced configuration instructions.

Please select the relevant instructions for the version of ResourceSpace you are running

Instructions for version 9.7 and later

From ResourceSpace 9.7 the SimpleSAMLphp plugin can now be configured using the UI and the ResourceSpace configuration file.

For advanced configurations you can still configure SAML by manually editing the configuration files that have been copied from plugins/simplesaml/lib/, in which case you need to follow the original instructions and refer to the authoritative SimpleSAMLphp documentation

The plugin setup page

The first step is to set up the SP (Service Provider). To do this you need to generate the configuration and add it to the ResourceSpace configuration file (include/config.php)

To generate the required text to add to the ResourceSpace configuration file:-

  1. Enable the simplesaml plugin by adding
    $plugins[]='simplesaml';
    to your config file
  2. Navigate to Admin - System - Plugins
  3. Click on 'Options' for the simpleSaml plugin
  4. Click on the 'Generate SP config' link
  5. Set technical contact details and an admin password for the SP test site (see 'Testing the SP' below)
  6. If you are using a previously generated certificate and key, enter the paths to the certificate and key files in PEM format. These fields can be left blank to automatically generate new certificates based on additional certificate questions that will appear. Ensure that the filestore folder is not browseable in your web server configuration
  7. If you have your IdP metadata in XML format you can paste it in here. If you already have the IdP metadata in your configuration then you can just paste in the relevant IdP entity ID

For advanced users

The standard SimpleSAMLphp definitions map to ResourceSpace configuration as below

  • The $config variable (from lib/config/config.php becomes $simplesamlconfig["config"]
  • The $config variable (from lib/config/authsources.php becomes $simplesamlconfig["authsources"]
  • The $metadata variable (from e.g. lib/metadata/saml20-idp-remote.php becomes $simplesamlconfig["metadata"]

Testing the SP

Once the SAML SP configuration has been added to the ResourceSpace config file you can test the connection to the IdP by clicking on the 'Visit SimpleSAMLphp test site' link from the plugin setup page. You will need to log in with the admin password you set for the SP.

This takes you to the SP test site where you can test the connection to the IdP.

  1. Click on 'Test configure authentication sources' and select 'resourcespace-sp'
  2. If configured correctly you will be directed to the IdP login page
  3. Sign in to your IDP. You will see a page listing all the attributes provided by your IDP
  4. You can use these attribute names to populate the username, fullname and email mappings in the main plugin setup page

Instructions for version 9.6 and earlier

You may choose to move the entire plugins/simplesaml/lib folder to another directory away from the plugins directory e.g. for shared ResourceSpace environments or to keep all configuration files under filestore/system. If so please ensure that you change the relevant files after copying them and and not those specified below or they are liable to be overwritten after an upgrade.

  1. Copy the sample configuration files from
        plugins/simplesaml/lib/config-templates/
    to
        plugins/simplesaml/lib/config/
  2. Copy the sample metadata files from
        plugins/simplesaml/lib/metadata-templates/
    to
        plugins/simplesaml/lib/metadata/
  3. Ensure the password, email contact and secret salt are changed in plugins/simplesaml/lib/config/config.php as below
  4.     /**
            * This password must be kept secret, and modified from the default value 123.
            * This password will give access to the installation page of simpleSAMLphp with
            * metadata listing and diagnostics pages.
            * You can also put a hash here; run "bin/pwgen.php" to generate one.
            */
            'auth.adminpassword'		=> '123',
            'admin.protectindexpage'	=> false,
            'admin.protectmetadata'		=> false,
    
            /**
            * This is a secret salt used by simpleSAMLphp when it needs to generate a secure hash
            * of a value. It must be changed from its default value to a secret value. The value of
            * 'secretsalt' can be any valid string of any length.
            *
            * A possible way to generate a random salt is by running the following command from a unix shell:
            * tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' /dev/null;echo
            */
            'secretsalt' => 'defaultsecretsalt',
            
            /*
            * Some information about the technical persons running this installation.
            * The email address will be used as the recipient address for error reports, and
            * also as the technical contact in generated metadata.
            */
            'technicalcontact_name'     => 'Administrator',
            'technicalcontact_email'    => 'na@example.org',
        
  5. Unzip the plugins/simplesaml/lib/www.zip directory. This is useful for decoding external XML metadata for use in config files and retrieving metadata that can be used by the IdP.
  6. Edit the file plugins/simplesaml/lib/config/config.php
  7. Select the technology you want to use by setting values to true or false as below.
    IMPORTANT: if setting up ADFS, leave enable.saml20-idp = true
        * Enable
        *
        * Which functionality in simpleSAMLphp do you want to enable. Normally you would enable only
        * one of the functionalities below, but in some cases you could run multiple functionalities.
        * In example when you are setting up a federation bridge.
        */
        'enable.saml20-idp' => true,
        'enable.shib13-idp' => false,
        'enable.adfs-idp' => false,
        'enable.wsfed-sp' => false,
        'enable.authmemcookie' => false,
        
  8. Change this if necessary

    * A directory where simpleSAMLphp can save temporary files.

    *

    * SimpleSAMLphp will attempt to create this directory if it doesn't exist.

    */

    'tempdir' => 'resourcespace/filestore/tmp/simplesaml',

1. Configuring the Service Provider (SP)

The SP is configured by an entry in config/authsources.php. See https://simplesamlphp.org/docs/1.5/simplesamlphp-sp for more detail

The following is an minimal authsources.php file

    <&?php
    $config = array(
    /* This is the name of this authentication source, and will be used to access it later. */
    'default-sp' => array(
        'saml:SP',
    ),
    );

If you want muliple Service Providers in the same site and installation, you can add more entries in the authsources.php configuration. If so remember to set the EntityID explicitly. Here is an example:

                        
    'sp1' => array(
        'saml:SP',
        'entityID' => 'https://sp1.example.org/',
    ),
    'sp2' => array(
        'saml:SP',
        'entityID' => 'https://sp2.example.org/',
    ),
                    

2. Enabling a certificate for your Service Provider (recommended)

Some Identity Providers / Federations may require that your Service Providers holds a certificate. If you enable a certificate for your Service Provider, it may be able to sign requests and response sent to the Identity Provider, as well as receiving encrypted responses.

Create a self-signed certificate in the cert/ directory.

    cd cert
    openssl req -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem

Then edit your authsources.php entry, and add references to your certificate:

    'default-sp' => array(
    'saml:SP',
    'privatekey' => 'saml.pem',
    'certificate' => 'saml.crt',
    ),

3. Adding IdPs to the SP

The service provider you are configuring needs to know about the identity providers you are going to connect to it.

This is configured by metadata stored in metadata/saml20-idp-remote.php and metadata/shib13-idp-remote.php.

The following is a minimal example of a metadata/saml20-idp-remote.php metadata file:

    <&?
    $metadata['https://openidp.feide.no'] = array(
    'SingleSignOnService'  => 'https://openidp.feide.no/simplesaml/saml2/idp/SSOService.php',

    'SingleLogoutService'  => 'https://openidp.feide.no/simplesaml/saml2/idp/SingleLogoutService.php',
    'certFingerprint'  => 'c9ed4dfb07caf13fc21e0fec1572047eb8a7a4cb',
    );

                            

For more information about available options in the idp-remote metadata files, see the IdP remote reference

If you have the metadata of the remote IdP as an XML file, you can use the built-in XML to simpleSAMLphp metadata converter, which by default is available as /admin/metadata-converter.php in your simpleSAMLphp installation.

Note that the idp-remote file lists all IdPs you trust. You should remove all IdPs that you don't use.

4. Setting the default IdP

An option in the authentication source allows you to configure which IdP should be used. This is the idp option.

    <&?
    $config = array(

    'default-sp' => array(
    'saml:SP',

    /*
    * The entity ID of the IdP this should SP should contact.
    * Can be NULL/unset, in which case the user will be shown a list of available IdPs.
    */
    'idp' => 'https://openidp.feide.no',
    ),
    );

5. Exchange metadata with the IdP

If you do not have setup an IdP yourself, you could use the Feide OpenIdP to verify your Service Provider setup. The metadata for Feide OpenIdP is already included in the metadata distributed with simpleSAMLphp, so you can copy the metadata from metadata-templates where Feide OpenIdP is included.

But, in order to complete the connection between your SP and Feide OpenIdP, it is not sufficient that you have configured metadata for Feide OpenIdP. Feide OpenIdP also needs to add metadata for your SP.

Copy the SAML 2.0 XML Metadata document automatically generated by simpleSAMLphp (as described below), and go to the OpenIdP Metadata Self-Service Registry:

You need to login with an OpenIdP account to authenticate (you can create a new account if you do not have one already). Next, click the link 'Add from SAML 2.0 XML metadata', and paste in your SAML 2.0 XML Metadata, give it a proper name and description and click 'save'. Now you can test the SAML 2.0 Example on your SP, and try to login with Feide OpenIdP.

Before you can run the test examples, you need the people running the IdP to load the metadata for your SP. This metadata can be generated automatically. Links to the generated metadata can be found under the Metadata-tab on the front page.

Azure Active Directory

When configuring Azure AD, you will have to set the Identifier and Reply URL. If you go to the admin area of SimpleSAML (ie. the www location in lib) - click on the Federation tab and then under SAML 2.0 SP Metadata click on Show Metadata (or use the URL above: https://your-domain.com/path/to/lib/www/module.php/saml/sp/metadata.php/resourcespace-sp). Using this information, set:

  • Identifier: https://your-domain.com/path/to/lib/www/module.php/saml/sp/metadata.php/resourcespace-sp
  • Reply URL: https://your-domain.com/path/to/lib/www/module.php/saml/sp/saml2-acs.php/resourcespace-sp

6. Test the SP

After the metadata is configured on the IdP, you should be able to test the configuration. The installation page of simpleSAMLphp has a link to test authentication sources. When you click the link, you should receive a list of authentication sources, including the one you have created for the SP.

After you click the link for that authentication source, you will be redirected to the IdP. After entering your credentials, you should be redirected back to the test page. The test page should contain a list of your attributes. These can then be used to configure the plugin within ResourceSpace

Configuring the main plugin setup page

The plugin options page requires the following information to be provided:-

Use standard ResourceSpace configuration files to set SP configuration and metadata (9.7+) If this set to false then manual editing of files is required. If set to true, make sure when configuring $simplesamlconfig['authsources'] that you name it resourcespace-sp
SAML Lib path Please enter the full server path to the SimpleSAML lib folder (only required if using the legacy config)
Use SAML to block access to site completely, if set to true then no one can access site, even anonymously, without authenticating If set to TRUE, this means that no user can access the site without signing in to the IdP
Use SAML credentials to login to ResourceSpace? (This is only relevant if above option is enabled) If above is TRUE and this is FALSE you can then configure anonymous access which will be only available to your SSO users
If blocking site, allow public shares to bypass SAML authentication? Allow external shares to bypass the requirement for SAML SSO access
Name of local service provider (SP) As configured in step (3)
List of additional allowed paths that can bypass SAML requirement Pages listed here will not require SAML login
Allow users to log in with standard accounts as well as using SAML SSO? If set to FALSE users will not be able to log in with standard ResourceSpace accounts
Prefer standard login (redirect to login page by default) If set to TRUE users will be taken to login page which has a 'Sign on using SSO' link.
If FALSE then users will be signed in automatically or redirected to the IDP. If above option is enabled and users want to log in using standard accounts they will need to navigate directly to login.php
Update user group at each logon. If not using SSO group attribute to determine access then set this to false so that users can be manually moved between groups Self explanatory

Duplicate account management

Email-match: Before creating new users, check if the SAML user email matches an existing RS account email. If a match is found the SAML user will 'adopt' that account This helps when implementing SSO for an existing installation provided the email addresses match the SSO account
Allow new accounts to be created if there are existing ResourceSpace accounts with the same email address? (this is overridden if email-match is set above and one match is found) If this is false and a SAML account has the same email address and is not 'adopted' as above then no new account will be created and the login will be blocked
Email address to notify if an email conflict is found If the above is set to false then an email will be sent to this address when the matching SAML user tries to log in

IdP configuration

Attribute(s) to use for username. If this is a concatenation of two attributes please separate with a comma Which SAML attribute will be used for the username. Two attributes can be combined e.g. initials and surname
If joining fields for username use this character as a separator This will be used as the separator if multiple attributes are used for the username
Attribute(s) to use for full name. If this is a concatenation of two attributes please separate with a comma Which SAML attribute will be used for the full name. Two attributes can be combined e.g. first name and surname
If joining fields for full name use this character as a separator This will be used as the separator if multiple attributes are used for the full name
Attribute to use for email address This will be stored in the ResourceSpace email field and used for system emails
Attribute to use to determine group membership This will be used if SAML - ResourceSpace Group Mappings are configured
Default user group that will be used for newly created users New SAML users will be added to this group if no match is found with a configured group mapping
Custom attributes to record against the user record Any attributes listed here will be stored against the ResourceSpace user record and can be seen on the user edit page

Authorisation rule

Attribute (assertion/ claim) name The attribute received from IdP and on which ResourceSpace will decide if user is allowed to log in or not.
Attribute (assertion/ claim) value The value of the authorisation attribute on which ResourceSpace will decide if user is allowed to log in or not.
SAML-ResourceSpace Group Mapping Each SAML group can be manually mapped to a RS group and assigned a priority. If the groups are known these can be input in advance.
Each group mapping can be assigned a priority to deal with the usual situation that a user is a member of multiple groups. For example if it is required that membership of a media team group take precedence over the general staff group mapping, the media team mapping should be assigned a higher number.

Migrating the SP to use ResourceSpace configuration (version 9.7 +)

The most complicated part of this is to ensure that the IdP continues to communicate with the SP correctly. The switch to using ResourceSpace configuration means that the URL of the SAML SP changes, so to keep things working you will need to either:-

  1. Add web server configuration to create an alias or redirect to the new URL
  2. Update the IdP with the new URL.

Other then the web server changes all that is really being done here is taking the settings from the SimpleSAMLphp configuration and storing them as ResourceSpace variables

You will first need to identify the location of your SimpleSAML 'lib' folder. By default this will be located in the ResourceSpace web folder (plugins/simplesaml/lib). You can check whether your lib folder is located outside of the plugins directory by checking the path defined on the simplesaml plugin setup page.

Migrating the metadata

  1. On the plugin options page, ensure that 'Use standard ResourceSpace configuration files...' is set to TRUE. Before you do this, make sure to remove the current lib path and SP name.
  2. Copy the config.php settings
    1. Open /config/config.php and copy the whole '$config' array definition
    2. Add this to your ResourceSpace configuration file as $simplesamlconfig["config"]
    3. e.g.
      $config = [
      
      /*******************************
       | BASIC CONFIGURATION OPTIONS |
       *******************************/
      
      /*
       * Setup the following parameters to match your installation.
       * See the user manual for more details.
       */
      
      /*
       * baseurlpath is a *URL path* (not a filesystem path).
       * A valid format for 'baseurlpath' is:
       * [(http|https)://(hostname|fqdn)[:port]]/[path/to/simplesaml/]
       *
       * The full url format is useful if your SimpleSAMLphp setup is hosted behind
       * a reverse proxy. In that case you can specify the external url here.
       *
       * Please note that SimpleSAMLphp will then redirect all queries to the
       * external url, no matter where you come from (direct access or via the
       * reverse proxy).
       */
      'baseurlpath' => '/filestore/system/saml/www/',
      
      /*
          ...
                    
      becomes
      $simplesamlconfig["config"] = [
      
      /*******************************
       | BASIC CONFIGURATION OPTIONS |
       *******************************/
      
      /*
       * Setup the following parameters to match your installation.
       * See the user manual for more details.
       */
      
      /*
       * baseurlpath is a *URL path* (not a filesystem path).
       * A valid format for 'baseurlpath' is:
       * [(http|https)://(hostname|fqdn)[:port]]/[path/to/simplesaml/]
       *
       * The full url format is useful if your SimpleSAMLphp setup is hosted behind
       * a reverse proxy. In that case you can specify the external url here.
       *
       * Please note that SimpleSAMLphp will then redirect all queries to the
       * external url, no matter where you come from (direct access or via the
       * reverse proxy).
       */
      'baseurlpath' => '/filestore/system/saml/www/',
      
      /*
          ...
    4. Replace any setting for 'logging.level' with the integer equivalent as defined in plugins/simplesaml/lib/lib/SimpleSAML/Logger.php
    5. Ensure that the 'baseurlpath' setting remains as it was before if you cannot alter the IdP settings

    Note that you can safely remove any default settings, but it is advisable to do this later after you have verified that the new ResourceSpace configuration works as expected

  3. Copy the authsources.php settings
    1. Open /config/authsources.php and copy the whole '$config' array definition
    2. Add this to your ResourceSpace configuration file as $simplesamlconfig["authsources"]
    3. e.g.
      $config = [
      
      // This is a authentication source which handles admin authentication.
      'admin' => [
          // The default is to use core:AdminPassword, but it can be replaced with
          // any authentication source.
      
          'core:AdminPassword',
      ],
      
      // An authentication source which can authenticate against both SAML 2.0
      // and Shibboleth 1.3 IdPs.
      'resourcespace-sp' => array(
          'saml:SP',
          ...
                    
      becomes
      $simplesamlconfig["authsources"] = [
      
      // This is a authentication source which handles admin authentication.
      'admin' => [
          // The default is to use core:AdminPassword, but it can be replaced with
          // any authentication source.
      
          'core:AdminPassword',
      ],
      
      // An authentication source which can authenticate against both SAML 2.0
      // and Shibboleth 1.3 IdPs.
      'resourcespace-sp' => array(
          'saml:SP',
      ...

      Please note that the authsource used live will always be named resourcespace-sp

  4. Copy the metadata settings
    1. Copy any '$metadata' elements from the files under /metadata
    2. Add these to your ResourceSpace configuration file as $simplesamlconfig["metadata"] elements.
      e.g.
      $metadata['https://accounts.google.com/o/saml2?idpid=C579sf7c83'] = array (
          'entityid' => 'https://accounts.google.com/o/saml2?idpid=C579sf7c83',
          'contacts' => 
          array (
          ),
          'metadata-set' => 'saml20-idp-remote',
          'expire' => 1660397726,
          ...
                    
      becomes
      $simplesamlconfig["metadata"]['https://accounts.google.com/o/saml2?idpid=C579sf7c83']  = array (
          'entityid' => 'https://accounts.google.com/o/saml2?idpid=C579sf7c83',
          'contacts' => 
          array (
          ),
          'metadata-set' => 'saml20-idp-remote',
          'expire' => 1660397726,
          ...

Adding a web server alias

Please note that these instructions are only provided as examples. Please check your web server documentation and organisational processes before making any changes since any misconfiguration is likely to result in loss of access to ResourceSpace

Adding a redirect in Apache

  1. Ensure mod_alias is enabled
    a2enmod alias
  2. Add the following line in the VirtualHost config
    # For SAML support after moving lib to RS config
    Alias [relative path to current SAML lib/www/folder] /plugins/simplesaml/lib
    e.g.
    # For SAML support after moving lib to RS config
    Alias /filestore/system/saml /plugins/simplesaml/lib
  3. Reload apache configuration
    systemctl reload apache2

Adding a redirect in Windows/IIS

  1. Open the IIS administration console
  2. Expand the folders until you reach the existing SAML lib path e.g. navigate to filestore/folder
    iis_saml_folder
  3. Right click on the saml lib folder (one level above the SAML www folder) and click 'Add virtual directory'
    iis_new_virtual
  4. Enter www as the alias. For the physical path browse to the /plugins/simplesaml/lib/www folder
    iis_alias_saml

You should now be able to log in to the test site from the plugin options page to test the configuration