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
- User authentication
- Identity Provider
- Service Providers
- Resulting Deliverables
- Other languages and libraries
Follow the steps on the simplesamlphp site to install the application.
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
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.
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
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
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
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.