Page tree
Skip to end of metadata
Go to start of metadata

Please start here if you want to connect your service to the SURFconext platform

Creating a simple SP from scratch

In this tutorial, we will set up a simple Service Provider, written in PHP, and connect it to the SURFconext infrastructure, using the SimpleSAMLphp product.

The tutorial assumes you are using a Linux environment; however, there is no reason to assume that this approach won't work on different operating systems that support PHP.

SURFconext Metadata

Take note that the metadata and the metadata locations used for the test and production environments of SURFconext differ. Use them accordingly:

Set up the SP

We start with a Hello World php app:

<?php

# do nothing for now...
print "Hello world";

For this guide, we will assume that the SP will be available from https://mfsp.example.org/mfsp/test.php .

In the examples below, you need to replace this with your own location.

Enable federated login

The goal of this tutorial is to enable federated logins via SURFconext for this simple php test file.

SimpleSAMLphp

We are going to use SimpleSAMLphp for this. SimpleSAMLphp is a very powerful product, which can be used in a number of roles in an identity federation (e.g., as IdP, SP, etc).

To set up SimpleSAMLphp to allow SURFconext users to log in, we need to set up SimpleSAMLphp as a Service Provider.
On the SimpleSAMLphp homepage, the configuration process is very well documented.

Below, we will go through the process step by step.

First download and set up SimpleSAMLphp as described on this page.  In particular, you need to 

  • Download and unpack SimpleSAMLphp into /var/simplesamlphp (step 4)
  • Configure Apache (step 6)
  • Configure SimpleSAMLphp (step 7)

Install Apache and PHP as follows:

  • sudo apt update
  • sudo apt install apache2
  • sudo apt install php libapache2-mod-php php-mysql php-curl php-xml

Restart your server after changing stuff:

  • sudo systemctl restart apache2

Find more information how to setup Apache in Linux here.



In addition, copy the file /var/simplesamlphp/modules/sanitycheck/config-templates/config-sanitycheck.php to /var/simplesamlphp/config/.
Edit it to disable the cron check, if desired.

Once you've set up SimpleSAMLphp, check that it works by visiting https://mfsp.example.org/simplesaml. You should get a site that looks like this:

As a simple first check to see if everything is configured correctly so far, click on configuration-->sanity check. This should tell you that everything was fine:

Next, we need to configure SimpleSAMLphp as a Service Provider for SURFconext

Setting up an SP

The procedure to set up SimpleSAMLphp as a Service Provider is explained in the SimpleSAMLphp documentation.

We will follow the procedure as laid out there:

  • Edit config/authsources.php in the in the SimpleSAMLphp root (/var/simplesamlphp).
  • The default config file has a lot of example code, for authentication against Google, Facebook, etc. We just want to have a username/password based admin login, and a SAML authentication source (which will be connected to SURFconext).
  • All SAML requests to and from SURFconext will be signed using SSL. The SSL certificated used for this does not need to be signed by a CA. A key and certificate can be generated using the following OpenSSL command:
openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -text -out saml.crt -keyout saml.key
  • The resulting private key (saml.key) and certificate (saml.crt) need to be placed in the cert/ subdirectory in the SimpleSAMLphp root (/var/simplesamlphp).

The  configuration file  thus becomes:

<?php
$config = [
    // This is a authentication source which handles SimpleSAMLphp admin authentication.
    'admin' => [
        'core:AdminPassword',
    ],

    // An authentication source which can authenticate against SURFconext
    'default-sp' => [
        'saml:SP',
        'privatekey'  => 'saml.key',
        'certificate' => 'saml.crt',
        'idp' => 'https://engine.test.surfconext.nl/authentication/idp/metadata',

        // The entries below are all OPTIONAL but RECOMMENDED to tell SURFconext
        // some details about your service.
        'name' => [
                'en' => 'Name of the Service',
                'nl' => 'Naam van de Dienst',
        ],
 
        'description' => [
                'en' => 'Description of the Service',
                'nl' => 'Omschrijving van de dienst',
        ],

    ],
];

Be aware of the environment your IdP lives in. In the example above the test environment of SURFconext is used. A common mistake is to try to connect to the test environment of SURFconext, and make use of the production environments link. You can find the right entityID inside the metadata for each environment:


Next, we need to configure SURFconext as an Identity Provider for your service.  To configure this, replace the file metadata/saml20-idp-remote.php, which identifies the Identity Providers that your service can use, with the following (for SURFconest TEST):

<?php
$metadata['https://engine.test.surfconext.nl/authentication/idp/metadata'] = [
    'name' => [
        'en' => 'SURFconext test',
        'nl' => 'SURFconext test',
    ],
    'SingleSignOnService' => 'https://engine.test.surfconext.nl/authentication/idp/single-sign-on/key:20190208',
    'certificate' => 'engineblock.test.surfconext.nl.20190208.pem',

    // convert OID formatted attributes from SAML assertion to 'name' similar to LDAP
    // so they will be available as 'mail' and 'displayName'
    'authproc' => [
      50 => [
        'class' => 'core:AttributeMap', 'oid2name',
      ],
    ],
];

Where the .pem file is a file placed under the cert/ directory containing the SAML signing certificate you can find this file at https://metadata.test.surfconext.nl/ under "Assertion signing certificate".

Testing connection

Now we can test our side of the setup: in the SimpleSAMLphp interface of your SP, go to Authentication, Test configured authentication sources, and choose default SP.
You should then be redirected to SURFconext. If everything is configured correctly, you should get the following error message:

The error occurs because SURFconext does not know your SP yet, and therefore will not allow its users to log onto your SP.  However, the fact that you are redirected to SURFconext signifies that the configuration of the SP is correct.

Configuring SURFconext

Next, we need to add the SP to SURFconext. SURFnet doesn't allow just anyone to connect directly to its production platform.  To register, put the metadata URL (https://mfsp.example.org/simplesaml/module.php/saml/sp/metadata.php/default-sp) in the SP Dashboard form, fill it out and publish the entity to TEST.

If not using the SP dahsboard, send an email to support@surfconext.nl. 

Include at least the following information:

  • location of your metadata (see above)
  • description of your service
  • name, email address, and phone number of a technical and an administrative contact at your organization
  • contact information for you end user support
  • a list of identity providers that need access to your service.  For testing purposes, it is common to request access for the SURFconext DIY IdP only.

The SURFconext administrators will get back to you quickly.

After your SP has been connected, visiting the authentication test (like above), you should get the WAYF (Where Are You From) screen:



After logging in at your IdP, and giving consent for SURFconext to hand your personal information to SURFconext, you will be redirected back to your local SimpleSAMLphp installation, and you should get a page like this, displaying your identity information:
Congratulations, you are now connected to SURFconext!

Protecting your PHP application

To protect a PHP application, we simply need to add a call to SimpleSAMLphp in the code. Change the test.php which we installed before to the following:

<?php
  require_once('/var/simplesamlphp/lib/_autoload.php');

  $as = new SimpleSAML_Auth_Simple('default-sp');
  $as->requireAuth();
  $attributes = $as->getAttributes();
?>
<html>
<head><title>My First Service Provider in PHP</title></head>
<body>
<h1>My First SP</h1>
<p>Hello world!</p>

<h2>Your attributes:</h2>
<pre><?php print_r($attributes); ?></pre>

</body></html>

When visiting this script, you will now be required to log on via SURFconext.

Further configuration

We recommend you consider Securing your simpleSAMLphp setup.

That's all folks!

Please direct any questions or comments about this document to support@surfconext.nl.