Português do Brasil

Articles in this section

See more

Set up SQSSO for your portal

Elizabeth
  • Updated

Use Signed Query SSO to manage logins to LearnUpon

Signed Query Single Sign-On (SQSSO) is a lightweight single sign-on mechanism that you can use to "silently" log your users in to LearnUpon.

Availability: all customers

Lightweight is not less secure. In this context, it means it is easier to implement than some SSO modules such as OAuth or SAML.

The basic premise behind SQSSO is that both LearnUpon and a third party share a secret key. Using this secret key, the calling party (the customer's system) "signs" a URL request: a request to log a user in to LearnUpon. Once LearnUpon validates this request, the user is logged into their portal on LearnUpon "silently" - without the need to re-authenticate.

If you require SQSSO access on your portal, contact the Support team.

SQSSO General Settings

These settings control the default path when users log in.

Once the Support team enables SQSSO on your portal:

  1. From main navigation go to Settings > Integrations > Signed QueryString SSO.
  2. Select General Settings.
  3. Select Enabled? to turn on the SQSSO feature.
  4. From Landing Pages, review default settings or enter
    • Landing Page: for successful logins
    • Unauthorized URL: landing page for unauthorized or error logins
    • Sign out URL: the page users see when they log out
  5. Optionally: to create a different login path select Disable portal login page? and enter a alternative Sign In URL.
  6. From URL Parameters enter any custom SQSSO URL parameters, and change any of the default parameter names as needed. 

screenshot_sample_URL_parameter_names_for_SQSSO.png

  1. From URL Signature, review the default settings or enter:
    • your SQSSO secret key
    • signed token format
    • username parameter name (if usernames are enabled)
  2. Save to finish.

Note: Find more details on how the secret key is used in the SSOToken section.

SQSSO User Settings

In User Settings you have the option to create new users. Turning on this option lets you specify parameters for:

  • learner’s first and last name
  • an optional language preference - so learners can log in to a portal in their preferred language
  • membership type, if in use

This option also updates existing user details to keep your user data in sync.

The language codes LearnUpon uses are available from the API guide.

  1. From main navigation go to Settings > Integrations > Signed QueryString SSO.
  2. Select User Settings.
  3. Select Create users if they do not exist?
  4. Enter the parameters you use.
  5. Optionally: select Auto-enroll users on published courses? to add new users automatically to your courses.

The following screenshot shows the User Settings options.

sqsso_user_settings_including_lang_param.png

  1. If your organization uses editable custom user data fields, specify the parameter name for each custom data field, so LearnUpon can update this data and keep it in sync.
  2. Save to finish.

Note: SQSSO can only update editable custom user data fields. See Custom user data: set up custom fields.

The following screenshot shows parameters for sample Custom User Data Settings.

screenshot_SQSSO_user_settings_custom_user_data_fields.png

Sample SSO Call

Read an example of how your SSO URL request looks, then review the settings discussed to see how they fit into the call.

A known user john.doe@somewhere.com ... logs into your site www.somewhere.com and you want to allow them access LearnUpon without requiring an additional login: access to your site gives them access to LearnUpon. You want a seamless login, where one login fits all.

You create a new button, or link on www.somewhere.com which only appears for logged-in users: for this example, use a link reading Access my Learning.

When the user selects Access my Learning, this event causes your application to:

  • generate an SQSSO link for accessing LearnUpon
  • redirect the user to the location of that SQSSO link

This SQSSO link looks something like this:

https://yourportal.learnupon.com/sqsso?Email=john.doe@somewhere.com&SSOUserName=john.doe&SSOToken=4e9f552e86b8ad7f37a64eba6e867043&TS=1366383106 

Each component of the URL builds part of the request.

URL Components

Component Description
https All access to SQSSO is directed over SSL (Secure Sockets Layer), a protocol to provide secure transmission.
yourportal.learnupon.com Use the subdomain/URL for accessing your portal on LearnUpon.
/sqsso? Required for accessing LearnUpon's SQSSO service.
Email=john.doe@somewhere.com

Here you are specifying which user is logging in to LearnUpon. By default, LearnUpon uses email as the unique identifier for the user.

You can enable username instead of email address as the unique identifier on your portal. In that case, SSOUserName acts as the identifier in the URL.

Contact LearnUpon Support for more information if your business requires usernames.

Note: if the user does not exist already in LearnUpon, then you can auto-create them as part of the process. For now, assume the user exists in LearnUpon, and this email identifies the user.

If the user is not found in LearnUpon, then the application rejects the single sign-on attempt.

SSOUserName=john.doe

This is a unique value/username for the user on the application issuing the SSO request. We do not store this value in LearnUpon unless you implement usernames.

If you implement usernames on your portal, then LearnUpon uses this value as the user lookup when authenticating the user.

If you do not implement usernames, LearnUpon recommends you use a unique value that is internal to your own system, that not everyone might know: for example, a unique id for a user column/row in the database.

Consider generating a secure/random string for every SQSSO URL that you generate.

Whatever you use must be unique per user.

Lang=nn

Lang=nn_nn

The language component is optional.

If your portal uses additional languages and specify a language choice for the user in the SSO request, the user can access their portal in their preferred language.

MembershipType

Note: applies to Associations feature only.

You can specify users' membership type (like Member or Non-member). If specified membership types do not exist on your portal, the user gets default membership type of Member. You can change the default membership type, in Settings.

TS=

This is the time recorded in Unix UTC Format, which is a standard format across all programming languages. The request needs a timestamp because LearnUpon will reject any requests that more than 30 seconds old.

Timestamp in Ruby:

Time.now.getutc.to_i

Timestamp in PHP:

$date = new DateTime(); $utc_timestamp = $date->getTimestamp();

SSOToken=

The SSOToken is the signed query action of the URL.

Example: take the following signed token format:

USER=john.doe&TS=1366383106&KEY=your_secret_key

your_secret_key is the known secret key shared between your application and LearnUpon.

Apply the hashing algorithm defined in your portal (Settings > Integrations > SQSSO > General Settings) to this string.

The hash generated is now added to your SQSSO URL with the SSOToken parameter.

 

Reminder of sample call

https://yourportal.learnupon.com/sqsso?Email=john.doe@somewhere.com&SSOUserName=john.doe&SSOToken=4e9f552e86b8ad7f37a64eba6e867043&TS=1366383106 

SQSSO settings in detail

Review the LearnUpon Settings > Integrations > SQSSO Integration page.

Setting Description
Enabled? Toggle control to enable or disable SSO for your portal.
Landing Page

LearnUpon Dashboard is the default landing page. When users successfully log in they land on the dashboard.

If you use eCommerce or the Internal Catalog on a portal, you can send users to these pages, after they log in.

Tip: you can customize this destination by specifying a redirect_uri in your SQSSO URL Call.

See Redirect URI, where you override this Landing Page setting and specify another destination.

Create users if they do not exist?

This option is effective, if the user logging in does not already exist on LearnUpon.

If you enable this setting, LearnUpon creates the users for you, using the email address (or usernames if you have them implemented) and generates a random password for them.

Note: the password is unknown to the end user, so you must take care about password management. In particular: if a user changes their password in LearnUpon, they might not know which login to use on each site.

Auto-enroll users on published courses?

When a user signs in to LearnUpon successfully, the application automatically enrolls them on all published courses in your portal. 

On subsequent logins via SSO, the application confirms they are enrolled on all courses, and enrolls them on any new courses.

{login_param} Login Parameter name <>

Tells LearnUpon the name of the login parameter, for the URL parameters.

The default is email or Email.

The email address is by default the unique identifier for a user. To set up username as an alternative, contact the Support team.

{time_stamp_param} TimeStamp Parameter name Tells LearnUpon the name of the TimeStamp URL parameter: the default is TS.
{username_param} Username Parameter name Tells LearnUpon the name of the Username parameter, on the URL parameters: the default is SSOUserName.

{lang} Default User Language Parameter name

 

 Tells LearnUpon the user’s default language, so the user sees their portal in their preferred language.

{membership_type_param} Membership Type Parameter name

 

Tells LearnUpon the name of the MembershipType parameter, on the URL parameters. The default is MembershipType.

This parameter only applies if you enable LearnUpon for Associations mode on your portal.

{secret_key} Your secret key The secret key shared between you and LearnUpon. You can change this at any time: if you do, you must update your third-party code and/or website with the same details.
Token Parameter name Tells LearnUpon the name of the URL Parameter containing your signed SSO token.
Signed Token Format

Use this setting to customize the format of the signed token. LearnUpon recommends using the default setting.

Use case example: if you did not have an SSOUserName at hand for the SSO process, then you can omit it by setting the token format to:

TS={time_stamp_param}&KEY={secret_key}

 

Unauthorized URL

 Allows you to specify a destination URL for users, if an SSO request is rejected and unauthorized. Default is /users/sign_in, the login page of LearnUpon.
Sign out URL Allows you to specify a destination URL for a user (who signed in via SSO) when they log out. Default is /users/sign_in, the login page of LearnUpon.

 

Redirect URI

As mentioned in SQSSO settings in detail: in your SQSSO settings, you can specify a landing page, for users who successfully log in to LearnUpon with SSO. Optionally: you can override that setting and specify your own custom URLs using a redirect_uri parameter.

Example

https://yourportal.learnupon.com/sqsso?Email=john.doe@somewhere.com&SSOUserName=john.doe&SSOToken=4e9f552e86b8ad7f37a64eba6e867043&TS=1366383106&redirect_uri=http://www.google.com

You can specify any URL here:

  • a URL to a course within your store: users can view the course description, and choose to enroll
  • a URL within LearnUpon: any URL you want to feature
  • launch a course for a user: enrolls the user and opens the course right away

Redirect the user to your store

https://yourportal.learnupon.com/sqsso?Email=john.doe@somewhere.com&SSOUserName=john.doe&SSOToken=4e9f552e86b8ad7f37a64eba6e867043&TS=1366383106&redirect_uri=/store

Redirect to a specific course on the store

This example requires the course_id you want the user to view. You can extract that information from our API, or you might have the IDs recorded on your own site.

Replace {course_id} with the course_id, as destination, once the user logs in to LearnUpon.

https://yourportal.learnupon.com/sqsso?Email=john.doe@somewhere.com&SSOUserName=john.doe&SSOToken=4e9f552e86b8ad7f37a64eba6e867043&TS=1366383106&redirect_uri=/store/{course_id}

Redirect the user to your catalog

https://yourportal.learnupon.com/sqsso?Email=john.doe@somewhere.com&SSOUserName=john.doe&SSOToken=4e9f552e86b8ad7f37a64eba6e867043&TS=1366383106&redirect_uri=/catalog

Redirect to a specific course on the catalog

This example requires the course_id you want the user to view. You can extract that information from our API, or you might have the IDs recorded on your own site.

Replace {course_id} with the course_id, as destination, once the user logs in to LearnUpon.

https://yourportal.learnupon.com/sqsso?Email=john.doe@somewhere.com&SSOUserName=john.doe&SSOToken=4e9f552e86b8ad7f37a64eba6e867043&TS=1366383106&redirect_uri=/catalog/{course_id}

Launch a specific course for a user

This example requires the enrollment_id of the course you want to launch. You can extract that user information from our API, or you might have enrolled a user before the SSO process, giving you an enrollment id.

https://yourportal.learnupon.com/sqsso?Email=john.doe@somewhere.com&SSOUserName=john.doe&SSOToken=4e9f552e86b8ad7f37a64eba6e867043&TS=1366383106&redirect_uri=/enrollments/{enrollment_id}

Tip: To launch the course description page when the enrollment starts, add %3Fvd%3D1 to the end of redirect_uri, which sends a redirect parameter of ?vd=1.

Disable login page

If you select Disable portal login page your users get redirected to the Sign in URL you provide.

You can still access the portal login page by adding users/sign_in?no_sso=true to the standard portal URL. For example: 

companyname.learnupon.com/users/sign_in?no_sso=true

Note: when you log in through SSO, you are authenticated for a single portal, rather than all your portals. The portal switcher in your top navigation bar shows only the portals where you are already logged in.

To retain access to all your portals through the portal switcher, log in through the LearnUpon sign-in page, by adding users/sign_in?no_sso=true suffix to your portal URL.

See:

Related articles