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.
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
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.
/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>
/opt/simplesamlphp/config/config.php:
auth.adminpassword to a new password.Set secretsalt to a new random string - can also generate with:
openssl rand -base64 24
'Pacific/Auckland' - or leave as NULL to rely on OSEdit 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(/.*)?'
Note
We will be usingsp.example.orgto 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
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,
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(/.*)?'
/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
config/config-metarefresh.php:
'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
certificatessetting.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'),
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
- If you have changed the cron password as instructed above, the line would be different than shown here.
- 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
--silentoption, 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>&1or
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.
hourly link at the bottom of the page (or pasting the cron-job URL into your browser - but the GUI link gives more output).config/module_cron.php and to avoid getting a confirmation email each time the cron-job runs, set
'debug_message' => FALSE, (to suppress the confirmation debug message)'sendemail' => FALSE, (to suppress all email messages from the cron module)/var/log/httpd/ssl_error_log)config/authsources.php and set 'discoURL'to either:
'https://directory.tuakiri.ac.nz/ds/DS''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',
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:
auEduPersonSharedTokenhomeOrganizationTypeeduPersonAssurance
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'),
),
),
dictionaries/attributes.definition.json "attribute_schachomeorganizationtype": {
"en": "Home organization type"
},
"attribute_auedupersonsharedtoken": {
"en": "Shared token"
},
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',
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,
Remove (comment-out) pre-configured IdPs and SPs
metadata/saml20-idp-remote.php - remove pre-configured openidp.feide.nometadata/saml20-sp-remote.php - remove pre-configured saml2sp.example.org and google.commetadata/shib13-sp-remote.php - remove pre-configured sp.shiblab.feide.noYou can register your SP into Tuakiri Using the Metadata Tool, starting the registration by uploading your SP metadata. The metadata for your SP can be accessed at https://sp.example.org/simplesaml/module.php/saml/sp/metadata.php/default-sp?output=xhtml
Note
In order to be able to submit a registration request for a Service Provider through the Metadata Tool, it is required that you are able to log in with a Tuakiri login, either with a user account at a Tuakiri member organisation or at the Tuakiri Virtual Home.The Tuakiri Service Desk can either provision you with an account on the Virtual Home, or perform the registration on your behalf.
Please contact Tuakiri Service Desk if you do not have a valid account with an IdP registered in the federation and/or the Tuakiri Virtual Home.
Start the registration by navigating to the Tuakiri federation management site https://registry.tuakiri.ac.nz/ (or, for Tuakiri-TEST federation, https://registry.test.tuakiri.ac.nz/).
Follow the instructions for Using the Metadata Tool.
A few special points to consider for an SP:
The Metadata Tool also collects information about registered services that is used to produce the Tuakiri Service Catalogue. Part of this information is a Service URL - URL that users can use to access your service. Please record this URL in the Metadata Tool (in the ServiceInfo section) to allow your service to be included in the Service Catalogue.
Requested Attributes: in the Metadata Tool, Requested Attributes are added in the AttributeConsumingService section. Please copy pre-defined attributes from the provided list.
Note
Persistent NameIDPlease note that with the IdPv3 upgrade, Tuakiri is moving from passing Persistent NameIDs in the eduPersonTargetedID attribute to passing them as a Persistent SAML2 NameID. When registering a new SP requesting a persistent NameID, please request both the eduPersonTargetedID attribute (for interoperability with IdPs that have not migrated to SAML2 NameID), as well as NameID of Persistent format. This can be done by including the SAML 2.0 Persistent NameIDFormat (
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) in your SP metadata. If not sure, please get in touch with the Tuakiri Service Desk.
Note
eduPersonEntitlement attributePlease note: if intending to request the eduPersonEntitlement attribute, the attribute request will have to be augmented with the specific values requested. Please get in touch with the Tuakiri Service Desk if requesting
eduPersonEntitlement.
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>