...
| 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 | ||
|---|---|---|---|
| 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 | ||
| 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.
| ||
| A secret key, preferably something random, that is shared by both parties. | ||
| In most cases this should be the same as |
SSO login link
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] |
Parameter | Explanation | Comment |
|---|
YourSite
A LearningBuilder™ sub-domain, usually the client’s acronym.
Custom URLs are acceptable.
UID
| The LearningBuilder Unique Identifier of the visitor attempting to sign on to |
LearningBuilder through the external system. | See Secure Tokens. |
| A time stamp generated to establish the authentication token. | See Secure Tokens. |
| The |
signed token. |
See Secure Tokens. | |
|
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 list of supported Success URLs is |
found on the Redirecting after SSO page. | Optional. If |
omitted, user is sent to their default landing page. If this is not part of LearningBuilder, the provided URL must be fully qualified |
and start with HTTP:// |
or HTTPS://. | ||
| 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. |
| Set to "true" |
to bypass the Demographic Synchronization Service |
. | Optional. |
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