Knowledge Base

Setting up the SAML SP

The SimpleSAMLphp plugin can 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

Common issues during testing

PROBLEM: when testing the SP, after logging in on the IdP side and being redirected back to ResourceSpace (simplesamlphp) you see an "UNHANDLEDEXCEPTION" error caused by "Requester/InvalidNameIDPolicy".

If the IdP metadata has specific NameID format requirements such as:

    'NameIDFormats' => array (
        0 => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
        1 => 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
        2 => 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient',
    ),
    

To fix this, add a NameIDPolicy to the $simplesamlconfig['authsources'] configuration. Example:

    $simplesamlconfig['authsources'] = [
        'admin' => ['core:AdminPassword'],
        'sp.name.example' => [
            'saml:SP',
            'privatekey' => 'path/to/sp_saml.pem',
            'certificate' => 'path/to/sp_saml.crt',
            'entityID' => null,
            'idp' => 'idp.example',
            'discoURL' => null,
            'NameIDPolicy' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
        ],
    ];
    

For ADFS, using "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" seems to work most of the times.

Configuring the main plugin setup page

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

Migrating the SP to use ResourceSpace configuration

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"]
   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/',
   
   /*
       ...

   1. Replace any setting for 'logging.level' with the integer equivalent as defined in plugins/simplesaml/lib/lib/SimpleSAML/Logger.php
   2. 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"]
   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
   
3. Right click on the saml lib folder (one level above the SAML www folder) and click 'Add virtual directory'
   
4. Enter www as the alias. For the physical path browse to the /plugins/simplesaml/lib/www folder
   

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