Tuakiri Documentation

Installing a SimpleSAMLphp SP

Note
This manual is written for CentOS 7.  Adjust accordingly for other OS distributions.

SimpleSAMLphp is an alternative SP implementation that can be used in place of Shibboleth SP - and can be particularly suitable on hosted servers without root access or the ability to install full software packages. This page documents the basic install of SimpleSAMLphp Service Provider and the configuration steps necessary to integrate the SP into Tuakiri.

Full SimpleSAMLphp documentation is available at http://simplesamlphp.org/

Note that while this page uses Apache as the web server SimpleSAMLphp is deployed into, SimpleSAMLphp could be used with a number of other web servers - and it’s advantage over Shibboleth SP would be the independence of Apache. Please adjust the Apache specific steps to what would work with your web server.

  1. Prerequisites
  2. Basic steps
  3. Configuring SP
    1. Loading the federation metadata
    2. Configure the SP to use the Tuakiri Discovery Service
    3. Configure Additional Tuakiri Attributes
    4. Configuring Persistent NameID
    5. Configure signing of logout messages
  4. Clean up SP configuration
  5. Register into Federation Registry
  6. Testing
  7. References

Prerequisites

  • A web server (Apache installed) with PHP (5.2.0+)
    • To meet the PHP version requirement, the OS has to be CentOS/RHEL 6 (CentOS 5 has only PHP 5.1.x)
  • The following PHP modules:
    • XML DOM (php-xml)
    • MCrypt (php-mcrypt)
    • Multi-byte string support (php-mbstring)
    • Basic PDO database support (php-pdo) for storing sessions (at least SQLite3).

    • Optionally, also MySQL support (php-mysql)

      yum install httpd mod_ssl php php-mcrypt php-xml php-pdo php-mbstring

  • Configure SELinux: if your system has SELinux enabled, allow Apache to send email (otherwise, invocation of sendmail(postfix) from PHP breaks):

    setsebool -P httpd_can_sendmail on

    • And if using SELinux, also install the policycoreutils-python package to get the semanagecommand which we will need later:

      yum install policycoreutils-python

Basic steps

  • Download simpleSAMLphp from https://simplesamlphp.org/download (1.16.3 as of August 2020)

    Note
    As SimpleSAMLphp 1.17.0 and above requires PHP 5.5+, but CentOS 7 only comes with PHP 5.4, the latest version that can be used on CentOS 7 is 1.16.3.

    For other OS distributions, check PHP version available and the requirements of the target SimpleSAMLphp version.

    • Install into /opt and not /var as instructed in the SimpleSAMLphp manual.

    • In the web server space, SimpleSAMLphp will be accesible as /simplesaml

      cd /opt
tar xzf ~/inst/simplesamlphp-1.14.4.tar.gz
mv simplesamlphp-1.14.4 simplesamlphp

  • Alias this directory as /simplesaml - create /etc/httpd/conf.d/simplesaml.conf with:

    Alias /simplesaml /opt/simplesamlphp/www

    • And on systems with Apache 2.4 (like CentOS or RHEL 7), explicitly grant permission to the directory - otherwise, Apache would reject to server the SimpleSAMLphp code - default access in Apache 2.4 is Require all denied: add this to the /etc/httpd/conf.d/simplesaml.conf file created above:

      <Directory /opt/simplesamlphp/www>
  AllowOverride none
  Require all granted
</Directory>
  • Do some basic changes to /opt/simplesamlphp/config/config.php:
    • Set auth.adminpassword to a new password.

    • Set secretsalt to a new random string - can also generate with:

      openssl rand -base64 24
    • Set technical contact name and email address.
    • Optionally, set timezone to 'Pacific/Auckland' - or leave as NULL to rely on OS
  • Configure a SQL session store to store sessions in a local database (even if just a sqlite3 file) instead of PHPsessions in order to support SLO via backchannel (SOAP).

  • Edit config.php and set the following:

            'store.type' => 'sql',
        'store.sql.dsn' => 'sqlite:/opt/simplesamlphp/data/sqlitedatabase.sq3',

  • And give Apache write access to the “data” directory (this also means setting the SELinux context if SELinux is enabled on your system):

    mkdir /opt/simplesamlphp/data
chown apache:apache /opt/simplesamlphp/data
# Set SELinux context to give Apache RW access - if SELinux is enabled on your system
chcon -t httpd_sys_rw_content_t /opt/simplesamlphp/data//
# And record the context setting in the SELinux policy database so that it goes not get lost in a SELinux relabel
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/simplesamlphp/data(/.*)?'

Configuring SP

Note
We will be using sp.example.org to refer to the hostname of your Service Provider - please substitute that with the actual hostname of your SP.

  • Create a certificate (self-signed for 20 years)

    cd /opt/simplesamlphp/cert
openssl req -newkey rsa:3072 -new -x509 -days 7304 -nodes -out saml.crt -keyout saml.pem
    • … and enter all information requested (“.” to skip) - the crucial part is your hostname.

  • Make the private key readable only to the user SimpleSAMLphp runs as (apache)

    chown apache:apache /opt/simplesamlphp/cert/saml.{crt,pem}
chmod 600 /opt/simplesamlphp/cert/saml.pem

  • Edit /opt/simplesamlphp/config/authsources.php and add references to the certificate to the default-sp definition:

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

  • Make SSP issue secure cookies: in config/config.php , change session.cookie.secure value to true : 

        'session.cookie.secure' => true,

Loading the federation metadata

  • Enable and configure the metarefresh and cron modules:

    cd /opt/simplesamlphp
touch modules/metarefresh/enable
cp modules/metarefresh/config-templates/*.php config/
touch modules/cron/enable
cp modules/cron/config-templates/*.php config/

  • Create a directory to cache the downloaded federation metadata (writeable by Apache - this also means setting the SELinux context if SELinux is enabled on your system):

    mkdir /opt/simplesamlphp/metadata/metarefresh-tuakiri
chown apache:apache /opt/simplesamlphp/metadata/metarefresh-tuakiri
# Set SELinux context to give Apache RW access - if SELinux is enabled on your system
chcon -t httpd_sys_rw_content_t /opt/simplesamlphp/metadata/metarefresh-tuakiri/
# And record the context setting in the SELinux policy database so that it goes not get lost in a SELinux relabel
semanage fcontext -a -t httpd_sys_rw_content_t '/opt/simplesamlphp/metadata/metarefresh-tuakiri(/.*)?'
  • Download the metadata signing certificate for the federation metadata into /opt/simplesamlphp/cert:

    • For Tuakiri, run:

      wget https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-cert.pem -O /opt/simplesamlphp/cert/tuakiri-metadata-cert.pem

    • or for Tuakiri-TEST, run:

      wget https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-cert.pem -O /opt/simplesamlphp/cert/tuakiri-test-metadata-cert.pem
  • Edit config/config-metarefresh.php:
    • Replace 'kalmar' with the federation name ('tuakiri')

    • Set the download URL - either for Tuakiri Production:

         'src' => 'https://directory.tuakiri.ac.nz/metadata/tuakiri-metadata-signed.xml',

    • Or Tuakiri-TEST:

         'src' => 'https://directory.test.tuakiri.ac.nz/metadata/tuakiri-test-metadata-signed.xml',

    • Set output directory and format (use 'serialize'format):

                              'outputDir'     => 'metadata/metarefresh-tuakiri/',
                        'outputFormat' => 'serialize',

    • Set expiry date to 7 days to match Tuakiri

                              'expireAfter'           => 60*60*24*7, // Maximum 7 days cache time.

    • Change the list of accepted certificates to the metadata signing certificate downloaded above (use tuakiri-test-metadata-cert.pem for Tuakiri-TEST:

                                              'certificates' => array(
                                                'tuakiri-metadata-cert.pem',
                                        ),

    • Remove/comment-out the validateFingerprint entry (see note below for explanation)

      Note
      Older versions of SimpleSAMLphp did not support directly referring to a certificate and instead required embedding the certificate fingerprint in the configuration.

      For historical and archival purposes, the instructions are included here - but can be ignored in favour of using the above certificates setting.

      Click here to expand...
      • Set the ‘validateFingerprint’ to the fingerprint value of the metadata issuing certificate
        • Tuakiri-PROD: 06:85:C5:89:2F:38:83:98:77:1B:A4:5D:58:A4:06:3A:A4:C1:CE:45
        • Tuakiri-TEST: 5E:90:2D:F9:D9:5A:5A:95:BF:58:4D:02:AD:29:35:64:CC:BF:76:45
      • To calculate the fignerprint yourself:
        • Download the metadata signing certificate (for Tuakiri-PROD and Tuakiri-TEST, they are linked from the instructions on registering an SP into Tuakiri)

        • and get the fingerprint value with:

                openssl x509 -fingerprint -noout -in metadata-cert.pem

  • Edit config/config.php and in metadata.sources, replace the existing 'type'=>'flatfile' entry with:

       array('type' => 'serialize', 'directory' => 'metadata/metarefresh-tuakiri'),
  • Now go with your browser to your SimpleSAMLphp page: https://sp.example.org/simplesaml/
    • and go to the Configuration page (log in with the Administrator password).
    • and from there to “Cron module information page”

  • Edit config/module_cron.php and change the secret 'key' from the default of 'secret'to a different password (to prevent potential abuse of the cron URL):

            'key' => 'top-secret',

  • Paste the hourly cron job entry (invoking curl to localhost) into root’s crontab:

    01 * * * * curl --silent "https://sp.example.org/simplesaml/module.php/cron/cron.php?key=secret&tag=hourly" > /dev/null 2>&1

    • (run “crontab -e” and paste the line into the editor)

      Note
      Note - invoking curl

      1. If you have changed the cron password as instructed above, the line would be different than shown here.
      2. If your web server is running with a self-signed HTTPS certificate, you would need to tell curl to either trust the local host certificate, or switch off certificate checking altogether.
        • Otherwise, with the --silent option, curl would just silently fail)

        • So use either

          01 * * * * curl --cacert /etc/pki/tls/certs/localhost.crt --silent "https://sp.example.org/simplesaml/module.php/cron/cron.php?key=secret&tag=hourly" > /dev/null 2>&1

        • or

          01 * * * * curl --insecure --silent "https://sp.example.org/simplesaml/module.php/cron/cron.php?key=secret&tag=hourly" > /dev/null 2>&1
        • And wait for a confirmation email to be sent to the technical contact email address after the cronjob runs at HH:01.
    • You can force the job to run immediately by clicking on one of the hourly link at the bottom of the page (or pasting the cron-job URL into your browser - but the GUI link gives more output).
    • To see the output from the metadata refresh itself, go to https://sp.example.org/simplesaml/module.php/metarefresh/fetch.php
  • After confirming the cron job works (wait for up to an hour to receive a confirmation email to the SimpleSAMLphp technical contact email address), edit config/module_cron.php and to avoid getting a confirmation email each time the cron-job runs, set
    • either 'debug_message' => FALSE, (to suppress the confirmation debug message)
    • or 'sendemail' => FALSE, (to suppress all email messages from the cron module)
    • However, they will have the same effect - as any error messages from metarefresh do not propagate to the cron module and are only visible in Apache error logs (/var/log/httpd/ssl_error_log)

Configure the SP to use the Tuakiri Discovery Service

  • Edit config/authsources.php and set 'discoURL'to either:
    • Tuakiri-Production: 'https://directory.tuakiri.ac.nz/ds/DS'
    • or Tuakiri-TEST: 'https://directory.test.tuakiri.ac.nz/ds/DS'

I.e., either

                'discoURL' => 'https://directory.tuakiri.ac.nz/ds/DS',

or

                'discoURL' => 'https://directory.test.tuakiri.ac.nz/ds/DS',

Configure Additional Tuakiri Attributes

From the list of attributes used within Tuakiri and the list of Attributes supported by SimpleSAMLphp in the default configuration, the following need to be explicitly added:

  • auEduPersonSharedToken
  • homeOrganizationType

  • eduPersonAssurance

  • Create attributemap/tuakiri-attrs.php with the following contents (adding on to what already exists in attributemap/oid2name.php )

    <?php   
$attributemap = array(
        'urn:oid:1.3.6.1.4.1.27856.1.2.5' => 'auEduPersonSharedToken',
);
?>

  • Edit config/config-metarefresh.php and add a reference to this file in the template for IdPs downloaded via metarefresh:

                                            'template' => array(
                                                'tags'  => array('tuakiri'),
                                                'authproc' => array(
                                                        51 => array('class' => 'core:AttributeMap', 'oid2name', 'tuakiri-attrs'),
                                                ),
                                        ),
  • To also configure friendly attribute names, add the following after the first line of dictionaries/attributes.definition.json
        "attribute_schachomeorganizationtype": {
                "en": "Home organization type"
        },
        "attribute_auedupersonsharedtoken": {
                "en": "Shared token"
        },

Configuring Persistent NameID

SimpleSAMLphp includes a NameIDPolicy in the SSO request sent to the IdP - and if not set, the requested format is urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

To request the urn:oasis:names:tc:SAML:2.0:nameid-format:persistent NameIDFormat (used in place of the eduPersonTargetedID attribute), add the following line into the default-sp parameters in config/authsources.php :

        'NameIDPolicy' => 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',

Configure signing of logout messages

As IdPs typically expect logout messages to be signed, configure SimpleSAMLphp to sign logout messages.

Add the following line into the default-sp parameters in config/authsources.php :

        'sign.logout' => true,

Clean up SP configuration

Remove (comment-out) pre-configured IdPs and SPs

  • Edit metadata/saml20-idp-remote.php - remove pre-configured openidp.feide.no
  • Edit metadata/saml20-sp-remote.php - remove pre-configured saml2sp.example.org and google.com
  • Edit metadata/shib13-sp-remote.php - remove pre-configured sp.shiblab.feide.no

Register into Federation Registry

The Tuakiri Federation Registry (FR) has in the initial setup only pre-configured support for Shibboleth SP implementation, not SimpleSAMLphp. Without the pre-configured support, it is necessary to enter all endpoints URLs manually. There is an ongoing project to add support to FR to support SimpleSAMLphp, until then, please use the Advanced Registration form as described in this section.

As a reference point, the metadata for your SP can be accessed at https://sp.example.org/simplesaml/module.php/saml/sp/metadata.php/default-sp?output=xhtml

For reference, please also see the attached image mapping SimpleSAMLphp metadata to Federation Registry form (credits: Bevan Rudge, University of Auckland).

Access the Federation Registry at the correct URL for the respective federation:

Testing

Test authentication by going to https://sp.example.org/simplesaml/module.php/core/authenticate.php?as=default-sp

Or, to test integration with a simple application, create a PHP file with the following contents within your document space:

<!DOCTYPE html>
<HTML>
<PRE>
<?php

// load the SimpleSAMLphp classes
require_once('/opt/simplesamlphp/lib/_autoload.php');

// select the default authentication source
$as = new SimpleSAML_Auth_Simple('default-sp');

// require authentication
$as->requireAuth();

// get the attributes
$attributes = $as->getAttributes();

// print the attributes and the NameID
print_r($attributes);
print_r($as->getAuthData('saml:sp:NameID'));

// print out eduPersonTargetedID (which is a DOM XML NameID node as of SimpleSAMLphp 1.14)
if (isset($attributes['eduPersonTargetedID'])) {
  $eptid = $attributes['eduPersonTargetedID'][0]->item(0);
  $nameID = new SAML2_XML_saml_NameID($eptid);
  print_r($nameID);
};

?>
</PRE>
</HTML>

References

Documentation