Versions Compared

Old Version 2

changes.mady.by.user Steve Ross

Saved on

compared with

New Version Current

changes.mady.by.user Seth Petry-Johnson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Note

As of 11.0.14 / 11.6.0, LearningBuilder supports SSO via SAML. That is the preferred approach (when possible) because it does not require any custom integration programming in either LearningBuilder or the 3rd party system.

See SAML Identity Management and SAML SSO vs legacy Demographic Sync (DRAFT)

Overview

The Single Sign-On (SSO) API allows individuals to log in to other systems and use those credentials to access LearningBuilder™. Single sign-on seamlessly transition into LearningBuilder from a 3rd party “identity provider”, such as an association management system, where that user is currently authenticated.

SSO is usually implemented in circumstances in which a customer has an existing member management system and wishes most interactions to take place within that system. The mechanism ensures individuals are able to access LearningBuilder™ LearningBuilder directly from their membership profile without logging on to a separate system.

Single Sign-On Implementation

Implementing requires the following components:

...

A visual protocol within the AMS/CRM to navigate to LearningBuilder™ (e.g., a link or button that directs visitors to LearningBuilder™);

...

A mechanism to generate an authentication token (see section 4);

...

A mechanism to send token and user identity to LearningBuilder™ through a query string;

...

A URL to redirect users to when sign-on succeeds (optional);

...

A URL to redirect users to when sign-on fails (optional); and

...

SSO is often used in conjunction with Demographic Synchronization, which updates demographic data in LearningBuilder, upon user sign-in, to match data in the identity provider. (For example, pushing updated contact information into LearningBuilder)

Implementation summary

To implement SSO you will need:

  • A shared secret key between LearningBuilder and the 3rd party system;

  • An ability to add a link into the 3rd party system (e.g. AMS/CRM) that redirects users to LearningBuilder, including an authentication token based on the secret key;

To implement Demographic Synchronization you will need:

  • An API endpoint (hosted by the identity provider) that LearningBuilder can call to obtain updated demographic data.

Visual Representation

The following diagram represents common scenarios for constructing the visual integration for single sign-on.

...

(TODO: diagram got corrupted at some point; should be recreated)

Figure 5.1. Illustrates the single sign-on path from a typical member profile.

...

The data flow for single sign-on authentication and navigation.

...

 (TODO: diagram got corrupted at some point; should be recreated)

Technical Specifications

Preliminary LearningBuilder configuration

The following technical specifications define the means by which to log on to LearningBuilder™ from an external system.

Logging in from the external system

If the sign-in succeeds, LearningBuilder™ will execute a demographic synchronization if a Demographic URL is provided (see section 6) and then redirect the user to their LearningBuilder™ landing page. If the sign-in or demographic synchronization fails, LearningBuilder™ will redirect the user to a landing page on the external system.

To connect via single-sign on, the external system will need to construct a querystring with the following contents:

https://[YourSite]parameters must be configured (by a Sys Admin) in LearningBuilder’s App Config system:

App Config setting

Purpose

CustomLoginUrl

Users are redirected to this URL if they access a page in LearningBuilder without an active user session.

As part of SSO, this should normally be configured to redirect unauthenticated users back into the identity provider.

If not specified, the default value is /account/login

LogOffURL

Users are redirected to this URL when they log out of LearningBuilder.

As part of SSO, this should normally be configured to redirect back to the identity provider.

Note

Logging out of LearningBuilder will not log users out of the identity provider at the same time.

TokenSecretKey

A secret key, preferably something random, that is shared by both parties.

OutgoingTokenSecretKey

In most cases this should be the same as TokenSecretKey. It can vary in the event that the identity provider and the demographic data provider are different.

SSO is initiated from the 3rd party identity provider, where the user must already be logged in.

A link on that site points to LearningBuilder, passing the following parameters:

Code Block
https://<ClientId>.LearningBuilder.com/account/sso
  ?UniqueId=[

...

UniqueId]
  &t=[TimeStamp]
  &token=[Token]
  &SuccessURL=[SuccessURL]
  &FailureURL=[FailureURL]
  &bypassDemographics=[bypass]
Component
The identifier

Parameter

Explanation 

Comment 

YourSite

A LearningBuilder™ sub-domain, usually the client’s acronym. 

Custom URLs are acceptable. 

UID 

UniqueId

The LearningBuilder Unique Identifier of the visitor attempting to sign on to

LearningBuilder™

LearningBuilder through the external system. 

See Secure Tokens

for SSO and Demographic Sync

. 

TimeStamp 

TimeStamp

A time stamp generated to establish the authentication token. 

See Secure Tokens

for SSO and Demographic Sync

. 

Token 

Token

The

encrypted

signed token.

 

See Secure Tokens

for SSO and Demographic Sync

. 

SuccessURL

The landing page when sign-on is successful.  

Where to redirect after a successful login. This is useful if you want the user to land on a page other than their default landing page.

 A

 

A list of supported Success URLs is

found here

found on the Redirecting after SSO page. 

Optional.  If

the URL to redirect to is for a page outside of LearningBuilder™, then

omitted, user is sent to their default landing page.

If this is not part of LearningBuilder, the provided URL must be fully qualified

, i.e. begin with 'HTTP

and start with HTTP:// or HTTPS://

'

.

 If not provided, the user will be taken to their default landing page. 

FailureURL 

The landing page of the external system when sign-in is not successful. 

Optional.  If not provided, the user will be taken to the default error page. 

bypassDemographics

Set to "true"

if you are not using

to bypass the Demographic Synchronization Service

, or are testing and want to bypass it

.

Optional.

If true, the demographics synchronization will be skipped.

Logging off from LearningBuilder™

When the user logs off of LearningBuilder™, they are redirected to the LogOffURL. This URL is specified through configuration of LearningBuilder™ and must be provided to the technical team during system configurations.  

In addition, a CustomLoginUrl (new in LearningBuilder 7.22.0) can be defined which Users will be redirected to upon login when they do not have an active session. When not specified, it defaults to /account/login/. -->

...

Defaults to false.

Demographic Synchronization

If the sign-in succeeds and a Demographic URL is provided, LearningBuilder will perform a demographic synchronization during the login process.

As part of this process LearningBuilder will call back out to the identity provider (passing the same sort of token used on the inbound link), requesting information about the newly logged-in user. The identity provider must return an XML document containing the relevant information that should be saved in LearningBuilder.

For more details see Demographic Synchronization Service