Single Sign On Integration Guide

Description

The Promote Learning Platform supports Single Sign On (SSO), a process by which users can authenticate themselves against an external Identity Provider (IdP), rather than obtaining and using a separate account handled by Promote.

Promote is compatible with any SAML 2.0 compliant service, such as Microsoft Azure AD, Microsoft Active Directory Federation Services 2.0, Shibboleth 2.0, and many others.

It is the aim of this document to guide the reader through the process of integrating Promote with a compatible IdP. Reading through the entire document prior to performing any of the steps herein is recommended.

Attribute mapping

Promote supports attribute mapping via claims in the SAML handshake. This allows user information in Promote to be automatically synchronized with the user information stored in the Identity Provider (IdP) each time a user signs in.

Fields available for user information mapping in Promote

• First Name
• Last Name
• E–mail
• Username
• Organization
• Info
• Phone
• Title
• Department
• Location

Please note that any claim can be mapped to any field. For example, if you want attributes such as Department or Country to be available in Promote, these can be mapped to the Info field.

Important to Consider

Ideally, SSO is enabled before users start using Promote for the first time, ensuring the sign in flow is easy to understand.

However, if there are already users in Promote who are used to signing in with email and password, they will first need to connect their Promote account to their IdP. This is done either by requesting an account access reset or by signing in to Promote with email and password, and then connecting the account while logged in. 

Learn more about Single Sign On via Company Signin, for both new and existing users, here >

Having pre-existing users also affects how the integration testing is performed. Read about our proposed workflow below.

Integration Steps

1. Configure the IdP using the metadata generated by the Promote authentication server, by navigating to your site specific URL below. Note: Your sitename can be found by looking at your Promote site URL’s subdomain - https://sitename.promotelogin.com

   https://sitename.promotelogin.com/users/auth/saml/metadata?id=1

   By default, the value of id should be 1. If a different value is to be used, your Promote contact person will inform you in advance.

   Learn more about how to configure your IdP for Single Sign On here >

2. Include any attributes you want to sync to the user information listed above, as claims.
3. Send the metadata generated by the IdP to your Promote contact person for this integration. Ideally, it would be sent in the form of a link, so that we always have access to the most recent version.
4. Clarify which attributes you want mapped to each user field in Promote
5. Inform your Promote contact person once your IdP configuration is ready.
6. We will confirm that the configuration is ready for testing, after ensuring that a user is correctly redirected to your IdP’s login portal.
7. We will invite a user of your choice to a Promote test program. You can then perform end-to-end testing, by verifying that the user is correctly redirected to your IdP’s login portal, successfully authenticated, and subsequently brought back to Promote. How you perform the testing, depends on whether you have pre-existing users or not, as follows:
   1. If there are no pre-existing users, simply follow the instructions in the Single Sign On via Company Signin article here >

   2. If there are pre-existing users, please follow the same instructions in option a above, but ensure that you do not click the My Company Sign In button as described in step 4 of those instructions. Instead, follow your site specific URL below. Note: Your sitename can be found by looking at your Promote site URL’s subdomain - https://sitename.promotelogin.com

      https://sitename.promotelogin.com/account/edit?test_saml=1

      Again, here like in step 1, the value of id should be 1. If a different value is to be used, your Promote contact person will inform you in advance.

Further Assistance

In case of any questions or need of further assistance, please don’t hesitate in reaching out to your appointed Promote contact person. We are here to help.