The LearningStudio Proprietary SSO is a highly flexible system that can send a wide variety of data points from a LearningStudio course or the Personal Student Home (PSH or Dashboard) to a third party system. While we recommend and prefer LTI for third party integrations, this approach can work better when an integration requires some additional data points not available to LTI, or when a launch from the PSH is absolutely necessary.
To request a new Proprietary SSO integration, fill out this form. You'll need to provide a variety of details as described on this page.
Principally, we'll need to know the target URL or endpoint, that is, where we should send the user when the SSO is launched. Secondly, you'll need to choose a security method (see next section) and the data points you would like to send. There are a variety of customizable features, but for most integrations these are the three most important pieces of information to decide.
Proprietary SSO configurations can be sent as GET or POST, though usually they are sent as GET. The parameters are sent in standard <code≥key=value format, either in the query string (GETs) or as a the body of a POST request. Both security methods (next section) apply to both approaches.
Security & Authentication
Proprietary SSO has two approaches to securely transmitting student information over the SSO.
- Parameters may be transmitted unencrypted as query string or POSTed parameters, along with a hashed signature token which you can use to verify the source of the SSO launch. This option is only available when your system has an HTTPS (SSL/TLS) endpoint.
- Parameters may be encrypted for transmission; you would then decrypt the information using the shared encryption keys. This option allows for non-HTTPS endpoints.
Note: While option two allows for non-HTTPS endpoints, it is strongly recommended that only HTTPS connections be used.
Hashed Signature Token (HTTPS only)
When setting up a signature approach, all the requested data points will be sent as plain query string parameters or in the request body of POSTed requests. There is no encryption with this approach; instead we require HTTPS connections to your endpoint and will include a hashed signature token.
To build that signature, all the parameters that are sent are concatenated into a comma-separated string, and an HMAC hash is created using a shared secret. So for example, we use a GET request to launch your endpoint, the redirect would be sent here:
Then the calculate the signature, the base string is:
A few notes on this method:
* You can choose either SHA1 algorithm for the HMAC (recommended), or the MD5 algorithm. This is determined and configured duing set-up.
* The shared secret is provided once the integration is set up. You should protect this. It will not be sent with the SSO launch.
* The values are not URL-encoded (unless you request them to be).
* The delimiters can be different from an equal sign (=) and comma (,) in the base string, but we recommend not customizing them if possible.
* The parameter name for the token can be anything you choose.
token are the most common choices.
* Note that the signature token is Base64-encoded
With the Encrypted launch approach, the parameters requested are encrypted into a single key/value pair. You would then need to decrypt the values in order to use them. While this approach may be used with non-HTTPS endpoints, but HTTPS is strongly recommended regardless.
For the encryption, we use the Advanced Encryption Standard (AES). When the integration is set up, we'll provide you an encryption key and initialization vector. Then the parameter string is encrypted and sent as a single parameter. There is no signature token with this method. For example, if were to send you this set of parameters:
That string would be encrypted using AES and we would launch the SSO to your site like so:
- You can provide an encryption key and initialization vector of your choice, but they must be 16 characters long and not contain commas, white space, or control characters.
- The parameter name for the encrypted value (
argsin the example above) can be anything you choose.
- Note that the encrypted value is base64-encoded prior to sending. You should decode it before decrypting it.
- The values in the decrypted string are not URL-encoded, unless you want them to be.
While the system is very flexible and we can set up customer-specific SSO endpoints, it's recommended that you use the data points to customize the user experience. Creating distinct SSO integrations for each customer can be error-prone and maintenance or updates is difficult. We can send you a customer identifier in the launch that would allow you to load customer-specific data an runtime.
The user experience depends primarily on how the link is authored in the course. See Integrating Links for more detail. In either approach, the Proprietary SSO can show a "Please Wait" message with an animated graphic while it assembles the session and launches your solution. You can choose to have this disabled as a standard part of your integration.
If you experience or detect an error, you can return the user to LearningStudio's Proprietary SSO error page to show a custom error code and message. Simply redirect the user back to this URL:
And use query string parameter named
errorMessage to customize the error message that is shown to users. For example:
Proprietary SSO Launch URLs
To launch your integration using the our proprietary SSO you or the customer will create an integration launch link within a LearningStudio course using a launch URL. The format for the URL will be:
thirdPartyLaunchName are configured by Developer Services and provided with the URL. Additional custom parameters can be added to the launch by adding query string parameters (i.e.,
&property1=value&property2=value). These are simply passed through to your system as if we were linking directly to you.
Here's an example proprietary SSO launch link that would be used in a LearningStudio course:
episode_id=12345 is some additional parameter appended when the link is put into a course).
For more details on how to add launch links to a LearningStudio course, just substitute the LTI launch URL with your Proprietary URL in the directions here.