SAML SSO

This guide outlines how to integrate Watershed with your Single Sign On (SSO) infrastructure via SAML.

This guide consists of 4 main sections

Overview

Single Sign On (SSO) via SAML lets you securely share user identity across systems. This means that your users sign in only once through a single authentication system and they are able to access other systems in the organization without having to log in again. Specifically, your users will be able to log into Watershed without the need to create and use a separate user account for access. This means your users will not have to remember an additional username and password in order to log in to Watershed. Easing this friction means your users are more likely to use Watershed and get value from it.

SAML is a standard protocol that lets one central system, called the Identity Provider, securely assert and share user identities with other systems, called Service Providers. This means that a user only needs to authenticate once against this central system in order to access all the others. This is very common concept all over the internet. Everytime you go to a site and login using your Facebook or Google credentials, they are playing the role of Identity Provider, and the site you are using those credentials at is the Service Provider. The diagram below outlines the high level steps involved in providing this identity information to Watershed via SAML.

Watershed implements SAML according to the SAML v2.0 specification.

Things Watershed needs from you

There are a few things that Watershed (or any SAML Service Provider) will need in order to make SSO work.

This is what we need from you:

  • The SAML SSO Service URL for your Identity Provider
  • An x509 certificate containing an RSA/DSA public key used to encrypt SAML communication
  • Logout URL for the SSO service
  • An optional custom help URL that would direct users to your organization’s help documentation instead of Watershed’s

Things you need from Watershed

There are a few things you (or any Identity Provider) will need from Watershed. You can find all of these below. You will want to replace all instances of <your org name> and <your org id> with your organization’s name and id. The organization id can be found in the settings area of your Watershed account under the data tab; please ask us for your organization's name.  For help finding your organization’s ID, please see Introduction to Watershed's API.

This is what you need from us:

  • Your org name
  • Login URL
  • ACS URL
  • Response format

Your org name

Your SSO org name will normally be a lowercase short form of your organization's name. For example if your organization is called 'Watershed Systems Inc.' then your org name will be 'watershed'. Please ask us if you are unsure of your org name.

Login URL

Live: https://<your org name>.watershedlrs.com

Testing: https://sandbox.watershedlrs.com/app/outside.html?org=<your org name>#/signin

ACS URL

Live: https://watershedlrs.com/api/organizations/<your org id>/saml/acs

Testing: https://sandbox.watershedlrs.com/api/organizations/<your org id>/saml/acs

Response format

The SAML response must provide identity information using one of the following ID formats:

  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

You also have the option not to specify, in which case we will try to parse out an email and default the format to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

You may also specify the organizational role this user can play in the system by using the attribute named watershed:organization-role, which can take on the value ‘user’ or ‘admin’ and defaults to ‘user’

Additionally an email may be specified in the response. This can be included through the use of the name ID format specified above or as an additional attribute node named email.

Please note: this workflow is for Service Provider initiated SSO. For Identity Provider initiated SSO this process starts with the user logging in and the SAML response being sent to the acs url.

Integrating with Groups API

Watershed has several ways to identify users and associate them with the xAPI statements coming in from several different data sources. When you send a SAML response with a Name Id this will be used to create a Persona in Watershed that looks like this:

“account”: {
    “homePage”: “<org specific saml home page>”,
    “name”: “<name id>”
}

This means if you are planning on integrating with the Groups API or plan on connecting Watershed with other data sources this will need to be set accordingly so that users are connected with their learning data. For more information check out Groups API docs and Connecting your Product to Watershed

Please note: you can only assign permissions via the Permissions API to users that already exist in Watershed, for example if they have already logged in to Watershed, if there is existing statement data about the user, or if you have created the user via the Person API.

Common Pitfalls

The following is a short list of common pitfalls. Keep in mind this is not meant to cover all the problems you may encounter setting up SAML but it may help you uncover some common mistakes when trying to integrate with Watershed.

Running Locally

If you are running locally, there is no way to test against Watershed. You need to set up a public url for the login otherwise Watershed will not be able to send a response to your computer.

Running HTTP

For security reasons Watershed only supports SSO from systems using HTTPS.

Inconsistent User IDs

Keep in mind that the user IDs provided by your Identity Provider are saved in Watershed. Each separate ID will be considered a separate user to Watershed, and as such it’s recommended to avoid changing the values for the IDs provided, since the new user will not retain any of the settings of the old user, and may collide and be rejected if they both use the same email address.

Account Home Page

The accountHomePage is persisted as part of the user ID, so we recommend avoiding any change to it. If the URL that represents your organization changes, we can work together to migrate existing data that relies on this URL.

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.