SAML SSO Using Simplesamlphp

This guide is intended as a supplemental document to the SAML SSO guide found here. Many people use simplesamlphp as a starting point for their SAML SSO implementation. It is a great open source application that supports a ton of authentication protocols. The following steps are oversimplified and only meant as a guide for organizations integrating with Watershed, please see simplesamlphp for a full guide.

The following guide is composed of 6 main steps.

Install simplesamlphp

Follow the steps on the simplesamlphp site to install the application.

  • Download the latest version here.
  • Follow the instructions here.

Please note: you can install and run simplesamlphp locally but keep in mind that until there is a publicly accessible SSO login URL for Watershed to hit, you won’t be able to test the full SSO handshake

User authentication

Once installed, the simplesamlphp modules directory contains a lot of the common authentication options. A good starting point is the example basic auth. You can enable the example auth module by running touch modules/exampleauth/enable . This will enable two default users outlined in the authpage.php inside the same module. You will need to follow similar steps to enable any other auth protocol depending on what you use to authenticate your users.

Identity Provider

Next you need to set up simplesamlphp to work as an Identity Provider (IdP).

To enable change this line in config/config.php

'enable.saml20-idp' => true, 

You will need a certificate and a private key.

Create a cert folder inside the simplesamlphp directory

mkdir cert 

To create a key you can run

openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes -out 
example.org.crt -keyout example.org.pem 

These will be example.org.crt and example.org.pem respectively so you should rename them and place them inside the cert directory you just created.

This is an extremely condensed section and is only meant as an abreviated guide, for a full walkthrough please see https://simplesamlphp.org/docs/stable/simplesamlphp-idp

Service Providers

Now you need to tell simplesamlphp about Watershed along with any other Service Providers (SP)

The metadata-templates directory has great examples, we will place any we need in the metadata directory.

We want to start out with saml20-sp-remote.php this already has a couple of examples and we will imitate one of them to tell simplesamlphp about Watershed.

We want to add a section of metadata for Watershed by adding the following code

$metadata['sandbox.watershedlrs.com'] = array(
    'AssertionConsumerService' => 'https://sandbox.watershedlrs.com/api/organizations/<your org id>/saml/acs',
    'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
    'simplesaml.nameidattribute' => 'uid'
);

$metadata['watershedlrs.com'] = array(
    'AssertionConsumerService' => 'https://watershedlrs.com/api/organizations/<your org id>/saml/acs',
    'NameIDFormat' => 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
    'simplesaml.nameidattribute' => 'uid'
);

The name ID format can also be of type “urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" or "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified".

The code above covers both sandbox and production configurations for Watershed, to save time for when you move to production

Resulting Deliverables

If you followed all the steps and got simplesamlphp installed and running, you have already created the deliverables we asked for in the SAML SSO guide.

  • The SSO Service URL will look something like http://<your_site>/simplesaml/saml2/idp/SSOService.php
  • The x509 certificate is the server.crt you created earlier
  • The logout url will look something like http://<your_site>/simplesaml/saml2/idp/SingleLogoutService.php

Other languages and libraries

There are lots of great libraries for SAML in pretty much any language.

Keep in mind that all of the steps previously covered are analogous. We will need the same things from you and you will need the same things from us.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

If you can't find what you need or you want to ask a real person a question, please contact customer support.