Incoming Absorb Single Sign-On

Follow

Applies to: Pro, Plus, & Enterprise Plans

Introduction

The main purpose of establishing a Single Sign On (SSO) process with Absorb is to allow your users a single point of entry into your system while providing them access to multiple other independent systems. With this process a user logs in with a single ID to gain access to a multitude of other systems without being prompted for different usernames and passwords.
 
This article discusses Incoming Absorb SSO for System Administrators, meaning your users will login to some external application or site and then access Absorb without entering a second set of credentials. The Absorb SSO is our proprietary method of achieving SSO - you may also be interested in reviewing our support for SAML 2.0 SSO however.
 
Please note that SSO is an additional feature that usually involves an additional fee and technical resources on the client side to develop and/or configure the solution.
 

Contents:

 

Requirements

At a minimum you will need a web server capable of:
  1. Redirecting users to Absorb with GET or POST variables
  2. Storing session (token) information about the user between requests. Absorb stores the token in the Session, so the web server must be capable of maintaining the Session between requests.
  3. Performing cryptographic operations (specifically PBKDF2)

Setup

The following variables will need to be determined and configured as part of your SSO implementation. 

Variables Description Requirement
Portal URL This is the URL where your Absorb LMS is hosted - please contact us if you do not know this. This URL usually configured as part of your initial LMS onboarding.
e.g. https://companyname.myabsorb.com OR https://some.custom.url
Mandatory
SSO Key This key is used as part of the authentication process and is configurable in Portal Settings. The SSO key can be chosen by the client (usually randomly generated). Mandatory
Id Property (Unique Identifier) A field chosen in Absorb LMS used to uniquely identify the user. Absorb can be configured to use the following as the Id Property:
  • UserId (Absorb)
  • Username
  • Email Address
  • External Id
  • Employee Number
Mandatory
Login URL This URL is used during the authentication process (see Step 2 in the Process section below). 

This is also the URL Absorb LMS redirects to when the user lands directly on the Portal URL and is not authenticated, if Automatically Redirect (see below) is turned on.
Mandatory
Logout URL This is the URL Absorb redirects users to when a user logs out of the Absorb system. Optional
Automatically Redirect This optional function, when turned on forces all users who directly land on the Portal URL to be redirected to the Login URL (This request does not send a token parameter). If not turned on users will land on the default Portal URL.
Optional
token A random URL Encoded string. Mandatory
id The unique identifier of the user being authenticated (see Id Property above). Mandatory
key Generated key unique to this request and user. More information in the Parameters section below. Mandatory
Assigned Routes This field allows you to search for, and select, any existing routes to assign. Optional

 

With the exception of Portal URL, token, id, and key (all used during the actual authentication process), all of the above variables can be configured by logging into the Absorb admin portal as a System Admin and navigating to Portal Settings. From Portal Settings, there is a button in the right-side context menu labelled Manage SSO Settings. If you can't see this button, please contact your Absorb Client Success Manager to discuss enabling the feature.

Capture2.PNG

Once you have clicked the button, you will be brought to the Manage Single Sign-On Settings page. Any existing configurations will appear here, as well as the option to Add a new one. 

 Capture3.PNG
 

Each route (Portal URL, e.g. company.myabsorb.com) can have its own set of SSO configuration. Please see this article for more information on route-based SSO. The remainder of this article assumes we're talking about a single SSO configuration.

How it Works

View larger version
  1. Redirect the user to URL/Account/ExternalLogin
  2. The user will be redirected to Login URL with the (GET) query string parameter token along with any other query string parameters that were sent in the original redirect.
  3. Redirect the user to URL/Account/ExternalLoginCallback with id and key parameters.
  4. If successful, the user will be logged in. Otherwise the user is redirected back to Login URL with a new token.
 

Methods

UrlTokenEncode(byte[] token)

Absorb LMS uses the System.Web.HttpServerUtility.UrlTokenEncode method 

(http://msdn.microsoft.com/en-us/library/system.web.httpserverutility.urltokenencode(v=vs.110).aspx)

UrlTokenDecode(string token)

Absorb LMS uses System.Web.HttpServerUtility.UrlTokenDecode method

(http://msdn.microsoft.com/en-us/library/system.web.httpserverutility.urltokendecode(v=vs.110).aspx)

PBKDF2(string key, byte[] salt)

Absorb LMS uses the Rfc2898DeriveBytes class to implement this method. The method looks like this:

Rfc2898DeriveBytes pbkdf2 = new Rfc2898DeriveBytes(key, salt); pbkdf2.IterationCount = 1000;
return pbkdf2.GetBytes(24);

Important values to note are the Iteration Count (set to 1000) and the number of bytes to use (24).


Parameters

token
The token parameter is created randomly by Absorb LMS. The token is converted to a string using the UrlTokenEncode method to transmit the token.
 
id
The id parameter should be the unique identifier of the user. For example, if the Id Property is set to Email, then the id parameter must be an email address that matches a user’s email address in Absorb LMS. If no user is found, the authentication fails. If multiple users are found within the same client portal (and are not deleted), authentication will also fail.
 
key
The key parameter should be created from the following method:
UrlTokenEncode(PBKDF2(id + SSOKey, UrlTokenDecode(token)))

 

Example

The following variables are used in this example:

id=bob@company.com

SSO Key=7MpszrQpO95p7H

token=MqsXexqpYRUNAHR_lHkPRic1g1BYhH6bFNVPagEkuaL8Mf80l_tOirhThQYIbfWYErgu4b Dwl-7brVhXTWnJNQ2

    1. Redirect the user to
      https://<company.myabsorb.com>/account/externallogin

    2. User is redirected to
      https://<company.com>/authenticate?token= MqsXexqpYRUNAHR_lHkPRic1g1BYhH6bFNVPagEkuaL8Mf80l_tOirhThQYIbfWYErgu4bDwl- 7brVhXTWnJNQ2

    3. Generate key using:
string idAndKey = "bob@company.com" + "7MpszrQpO95p7H";
byte[] salt = UrlTokenDecode("MqsXexqpYRUNAHR_lHkPRic1g1BYhH6bFNVPagEkuaL8Mf80l_tOirhThQYIbfWYErgu4bDwl
-7brVhXTWnJNQ2");
string key = UrlTokenEncode(PBKDF2(idAndKey, salt));
// key = “aE1k9-djZ66WbUATqdHbWyJzskMI5ABS0”;

 

  1. Redirect user to 
    https://<company.myabsorb.com>/account/externallogincallback?id=bob@company.com&key= aE1k9- djZ66WbUATqdHbWyJzskMI5ABS0
 

Deep Linking and RelayState

Deep linking in terms of the Absorb LMS is the ability to redirect a user to a particular user content page on the Absorb LMS. This is usually done through a hyperlink that the user would click on. 

Absorb supports deep linking through Absorb SSO using one of the protocol’s implementation parameters, the RelayState. The RelayState parameter should be included as part of the final redirect to Absorb at the end of the URL.

The following example illustrates how to structure the RelayState parameter:

Courses: (Online Course) 

https://company.myabsorb.com/account/externallogincallback?id=bob@company.com&key=aE1k9-djZ66WbUATqdHbWyJzskMI5ABS&relaystate=https://company.myabsorb.com/#/courses/course/91db68a0-581f-467c-84fa-e67430d1c661 

(Where the blue text portion is the deep link)

More information and examples of each type of Deep Link can be found on our Support Site, by searching “deep link”. As of the time of this article’s writing, the relevant article can be found here.

Not all Absorb deep links are supported when used in conjunction with Absorb SSO. Absorb supports deep linking into the following LMS content with Absorb SSO: 

  1. Online Course Page
  2. ILC Page
  3. Curriculum Page
  4. Enrolled Courses List
  5. Courses List (Categories)
  6. Catalog
  7. Catalog by Category
  8. Resources
  9. Calendar
  10. Transcript
  11. News
  12. Polls
  13. Contests
  14. Purchase Page
  15. Purchase by Category
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Article is closed for comments.