Connecting an SP
For simplicity the same OpenConext VM can be used to setup a first Service Provider (SP).
This example assumes an installation under a regular user account of the VM (not ‘root’). In all commands/command lines quoted below where ‘/username/’ is present, replace it with the appropriate account name in your VM.
Icon
The suggested options are meant for test purposes, you should be aware that running a simpleSAMLphp installation from the user’s home directory isn’t suitable for production environments.
We recommend for non-test installations to follow the Installation Guide on the simpleSAMLphp website.
Preparing apache
The CentOS used for the VM has SELinux enabled. With the regular installation, the Apache web server that we need cannot read content or execute scripts that are in users home directories. To change that issue the following command in a terminal:
sudo setsebool -P httpd_read_user_content on
Then create the following directories in the home directory, making sure they have the right permissions set:
cd chmod 711 /home/username mkdir www chmod 755 www cd www mkdir public chmod 777 public
Installing simpleSAMLphp
Download simpleSAMLphp from http://simplesamlphp.org/download, unpack the tar.gz file in /home/username/www and then rename it to “simplesamlphp”.
tar xvf simplesamlphp-1.11.0.tar.gz mv simplesamlphp-1.11.0 simplesamlphp
Now the Apache web server needs to be configured, since this is the same server that is also used for the OpenConext components, we will let Apache reuse the certificates of those components to keep it simple.
Configuring Apache
An existing configuration of the manage component can be reused:
cd /etc/httpd/conf.d sudo cp manage.conf spdemo.conf
Now change the content of spdemo.conf to read as follows (changing all paths containing ‘/home/username’ to your situation):
<Virtualhost *:443> DocumentRoot "/home/username/www/public" ServerName sp.demo.openconext.org Alias /simplesaml /home/username/www/simplesamlphp/www <Directory "/home/username/www/public/"> Options Indexes MultiViews FollowSymLinks AllowOverride All Order allow,deny Allow from all </Directory> SSLEngine on SSLProtocol -ALL +SSLv3 +TLSv1 SSLCipherSuite ALL:!aNULL:!ADH:!eNULL:!LOW:!EXP:!RC4-MD5:RC4+RSA:+HIGH:+MEDIUM SSLCertificateFile /etc/httpd/keys/openconext.pem SSLCertificateKeyFile /etc/httpd/keys/openconext.key SSLCACertificateFile /etc/httpd/keys/openconext_ca.pem </VirtualHost>
Then restart the apache service:
sudo apachectl restart
Add the new sp.demo.openconext.org hostname of the VM hosts file (and optionally to that of the machine hosting the VM).
If you now surf to https://sp.demo.openconext.org/ you should see the standard Apache starting page. https://sp.demo.openconext.org/simplesaml should serve the simpleSAMLphp welcome page.
The next step is to change the default passwords and make some other changes to the defaults in the configuration file. Implement these changes as described in the documentation of simpleSAMLphp http://simplesamlphp.org/docs/stable/simplesamlphp-install#section_7.
Configuring the SP
1. Configuring the SP in simpleSAMLphp
The longer description of configuring a simpleSAMLphp installation as an SP can be found in the documentation of simpleSAMLphp at http://simplesamlphp.org/docs/stable/simplesamlphp-sp.
Add the following to authsources.php in the config directory of simpleSAMLphp:
'demo-sp' => array( 'saml:SP', 'entityID' => 'https://sp.demo.openconext.org/', 'privatekey' => 'saml.pem', 'certificate' => 'saml.crt', ),
Generate the certificate and keys in the cert subdirectory of simpleSAMLphp with:
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.pem
The ‘demo-sp’ entry is now visible on the Federation tab of simpleSAMLphp.
2. Configuring the SP in OpenConext
The next step is to add an entry in OpenConext for this new demo SP.
New connections can be created manually, but to avoid errors it is better (and much easier) to create new connections from metadata.
To get the metadata of our test SP, open a new tab for https://sp.demo.openconext.org/simplesaml/, go to the Federation tab and select ‘Show metadata’ below the ‘demo-sp’ entry. Select the XML metadata and copy it to the clipboard.
Go to http://demo.openconext.org/ and click on the ServiceRegistry tool, logging in via the Mujina IdP (admin/secret). From the Connections tab, select ‘Create connection’, paste the XML in the ‘Create entity from XML’ text field and press the ‘Create’ button. The new connection ‘https://sp.demo.openconext.org/’ will appear in the list at the bottom of the page.
Click on the link of that new connection and on the following page change the ‘State’ from ‘Test’ to ‘Production’, then click ‘Save’ (bottom-right).
Click on the ‘Metadata’ tab and put a name in the ‘name:en’ and ‘name:nl’ fields (e.g. ‘Demo SP’), then press Save.
Go to the ‘Identity Provider (IdP)’ tab and make sure that the ‘Allow All’ box is checked, if needed check the box and then save it. This ensures that all Identity Providers that are currently configure in OpenConext can be used to login to our Demo SP. This tab can also be used to restrict the IdPs that can be used to login to (an) SP by only selecting the ones allowed.
3. Configuring OpenConext (as IdP) in the SP
Now that OpenConext knows the SP, we need to do the reverse as well: create an entry for OpenConext (as an IdP) at the demo SP.
First we need to determine the fingerprint of the signing certificate used by OpenConext, which is used by simpleSAMLphp to verify the responses it gets from OpenConext.
Download the signing certificate from https://engine.demo.openconext.org/authentication/idp/certificate.
Assuming the certificate is downloaded to /home/username/Download, issue the following command:
openssl x509 -noout -in /home/username/Downloads/engine.demo.openconext.org.pem -fingerprint
Which should echo a line similar to:
SHA1 Fingerprint=F3:8D:27:66:8C:19:AC:BF:51:D0:D9:47:7B:9E:FD:09:38:10:D4:BF
Add the following entry to the metadata/saml20-idp-remote.php file of demo-sp’s simpleSAMLphp installation, replacing the hext string after ‘certFingerprint’ with the resulting hex string of the command above:
$metadata['https://engine.demo.openconext.org/authentication/idp/metadata'] = array ( 'name' => array( 'en' => 'OpenConext', ), 'SingleSignOnService' => 'https://engine.demo.openconext.org/authentication/idp/single-sign-on', 'certFingerprint' => 'F3:8D:27:66:8C:19:AC:BF:51:D0:D9:47:7B:9E:FD:09:38:10:D4:BF' );
Then save the file.
4. Testing the setup
Go to the demo SP at https://sp.demo.openconext.org/simplesaml/, select the ‘Authentication’ tab, then click ‘Test configured authentication sources’.
At the next page click ‘demo-sp’, leading to a screen where you can choose between ‘Feide OpenIDP’ and ‘OpenConext’. Choose ‘OpenConext’ and press ‘Select’, ending up at the ‘Where Are You From’ (WAYF) of OpenConext.
Choose the OpenConext Mujina IdP and login with admin/secret.
Since this is the first time you login at the Demo SP, consent is asked by OpenConext to share your attributes with this SP.
After giving your consent you will be logged in at the Demo SP, which will show you all the attributes the Mujina IdP has shared (via OpenConext) with this SP.
My First SP
To get started quickly with a simple SP, create a new file called index.php in /home/username/www/public and add the following to it:
<?php require_once('../simplesamlphp/lib/_autoload.php');
/* We select our authentication source: */
$as = new SimpleSAML_Auth_Simple('demo-sp');
/* We then require authentication: */
$as->requireAuth();
echo "<h1>Hello, world!</h1>";
/* And print the attributes: */
$attributes = $as->getAttributes();
echo "<pre>";
print_r($attributes);
echo "</pre>";
?>
Save this file and then browse to https://sp.demo.openconext.org/, which should again simply display all the attributes passed on to the SP by the IdP.
Automated metadata retrieval
In this simple demo setup, it is fairly straightforward to setup the configuration manually, since it only involved one entry and the metadata does not change apart from a new time stamp every 48 hours (which is silently ignored since no expiration was configured in simpleSAMLphp).
There are cases however where metadata can and does change frequently and/or contains (many) more IdP entries, effectively making maintaining the configuration manually too cumbersome and time consuming. In those circumstances it can be useful to set up automatic metadata retrieval in simpleSAMLphp, although for metadata that contains more IdP entries but hardly ever changes, it is also possible to generate configuration entries for metadata/saml20-idp-remote.php file using the ‘XML to simpleSAMLphp metadata converter’ link from the ‘Federation’ tab of simpleSAMLphp (or directly via https://sp.demo.openconext.org/simplesaml/admin/metadata-converter.php)
The following steps needed to achieve automated metadata retrieval are taken from the full simpleSAMLphp guide at http://simplesamlphp.org/docs/stable/simplesamlphp-automated_metadata, with the appropriate URLs changed to this demo setup situation.
1. Preparation
cd /home/username/www/simplesamlphp touch modules/cron/enable cp modules/cron/config-templates/*.php config/ touch modules/metarefresh/enable cp modules/metarefresh/config-templates/*.php config/
2. Configuring the cron module
Edit config/module_cron php to read:
$config = array (
'key' => 'kb10fu2sao',
'allowed_tags' => array('daily', 'hourly', 'frequent'),
'debug_message' => TRUE,
'sendemail' => FALSE,
);
With your browser go to https://sp.demo.openconext.org/simplesaml/module.php/cron/croninfo.php and copy the ‘daily’ cron line to the clipboard:
02 0 * * * curl --silent "https://sp.demo.openconext.org/simplesaml/module.php/cron/cron.php?key=kb10fu2sao&tag=daily" > /dev/null 2>&1
Run crontab –e and add that line as a crontab entry.
3. Configuring the metarefresh module
Edit config/config-metarefresh.php to read as follows, where the hex string after ‘validateFingerprint’ is the same as the one used for ‘certFingerprint’ in the manual configuration (step 3 of section “Configuring the SP”):
$config = array(
'sets' => array(
'OpenConext' => array(
'cron' => array('hourly'),
'sources' => array(
array(
'src' => 'https://engine.demo.openconext.org/authentication/idp/metadata',
'validateFingerprint' => 'F3:8D:27:66:8C:19:AC:BF:51:D0:D9:47:7B:9E:FD:09:38:10:D4:BF',
'template' => array(
'name' => array(
'en' => 'OpenConext',
),
),
),
),
'expireAfter' => 60*60*24*4, // Maximum 4 days cache time.
'outputDir' => 'metadata/openconext/',
'outputFormat' => 'flatfile',
),
),
);
Create the directory where the metadata file will be placed and make sure that Apache can write there:
mkdir metadata/openconext chown apache:apache metadata/openconext
Then configure your simpleSAMLphp installation to use the generated metadata:
In config.php make sure the following entry is present:
'metadata.sources' => array(
array('type' => 'flatfile'),
array('type' => 'flatfile', 'directory' => 'metadata/openconext'),
),
Since the metadata will be read automatically by simpleSAMLphp, the section that was added to the main metadata/saml20-idp-remote.php in step 3 of section “Configuring the SP” can now be removed again.
4. Testing the setup
To test whether the generation of the metadata works, browse to https://sp.demo.openconext.org/simplesaml/module.php/cron/croninfo.php again and select the ‘Start cron [daily]’ link at the bottom of the page. This should result in a saml20-idp-remote.php file being generated in the metadata/openconext directory.
To check that the setup (still) works do the last tests of sections 3.4 and 3.5 again (browse to https://sp.demo.openconext.org/ and check you can still log in).
Further reading
This page provides a step-by-step description on how to setup a simple test environment for OpenConext and a simple SP.
More useful and advanced information for Service Providers and Identity Providers can be found at the Get Conexted! section of the SURFnet labs Wiki.
A subsection of that wiki provides technical information for Service Providers on e.g. how to setup SPs using different programming languages and environments, how to work with groups and OAuth and how to connect to the SURFconext service rather than this test instance.
A mailing list is available for questions regarding OpenConext at
openconext-users@surfnet.nl, subscribing to that mailing list can be done via https://list.surfnet.nl/mailman/listinfo/openconext-users
More examples and in-depth explanation of the many useful features of simpleSAMLphp can be found in the documentation at http://simplesamlphp.org/docs/stable/. The step-by-step instructions are excerpts of that documentation with the paths and names modified where appropriate for this situation. When developing a real SP using simpleSAMLphp it is recommended to follow the original documentation.