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.
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:
For this guide, we will assume that the SP will be available from.
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.
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
- 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
Edit it to disable the cron check, if desired.
Once you've set up SimpleSAMLphp, check that it works by visiting
. 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:
config/authsources.phpin the in the SimpleSAMLphp root (
- 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:
- The resulting private key (
saml.key) and certificate (
saml.crt) need to be placed in the
cert/subdirectory in the SimpleSAMLphp root (
The configuration file thus becomes:
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):
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".
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.
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 (
) in the SP Dashboard form, fill it out and publish the entity to TEST.
If not using the SP dahsboard, send an email to firstname.lastname@example.org.
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:
When visiting this script, you will now be required to log on via SURFconext.
We recommend you consider Securing your simpleSAMLphp setup.
That's all folks!
Please direct any questions or comments about this document to email@example.com.