The OpenLearning API provides a shortcut for performing LTI Single Sign On. Many learning platforms already implement LTI tool provider launch functionality, so this shortcut API is instead designed for developers building their own systems who wish to implement SSO functionality without implementing the full LTI standard.

The API endpoint used is: POST /institutions/{institution_id}/managed-users/{user_id}/sign-on/

An overview of how this is used is as follows:

• A server makes a request to the above endpoint with the required parameters, every time a user wishes to sign on to OpenLearning from the external system,
• This endpoint responds with form parameters which the server then sends to the user's client. These parameters are used to populate a form,
• The user posts the form to OpenLearning with these parameters, initiating a sign-on launch.

Functionality:

This endpoint is to be used by a server-sent request each and every time an external user requires a SSO launch into OpenLearning. It provides:

• Signed parameters to be used for generating a launch link, which the external user follows from the external system in order to launch OpenLearning
• Single-sign-on functionality, where the external user does not need to enter OpenLearning account credentials
• The ability to sign on both managed user accounts, as well as existing OpenLearning users who have been invited into your institution portal
• The ability for the user following the launch link to be automatically enrolled in a given class
• The ability for an external system to provision courses, or class deliveries (of courses), which can be further configured by an OpenLearning user upon launch (if given the appropriate administrative access permissions).

Prerequisites:

Before this endpoint can be requested, one of the following prerequisites must be met for the user in question. Either:

• The user account was provisioned (created) as a managed user account under this institution portal, and given an institution "external ID", or
• The user account was added as a member of this institution portal, and given an institution "external ID".

The provided "external ID" is the field OpenLearning uses to identify the external user in another software platform, and may be an institution ID (e.g. student ID), primary email address, or any other value which uniquely identifies the user.

Using the API:

The API takes the following parameters:

• user_id: the OpenLearning user identifier for the user which is to be signed in to the OpenLearning platform. This value can be queried using other API requests.

• institution_id: this is the OpenLearning ID used to refer to your institution portal.

• class_id (optional): this is the OpenLearning ID used to refer to a class delivery of a course. If this is provided, users following this launch link will be enrolled into this class automatically.

• context_id (optional): this is any unique identifier provided by the external system to refer to a class delivery which may (or may not yet) be running on OpenLearning. If this value is provided, the class_id is ignored. If the provided context_id is not yet associated with a class delivery on OpenLearning, the launch link will prompt the user who follows this link to create, or set up the associated class delivery (provided that user already has sufficient administrative privileges on OpenLearning). Learners (without such privileges) who follow a launch link which has not yet been set up will be met with an error, until the class has been successfully provisioned.

• email (optional): the user's email address. If provided this is used to determine whether the user has an existing account on OpenLearning, and will direct them to the appropriate account linking screen upon sign on. Otherwise, this field will be used to pre-populate the email address field on sign-up.

• full_name (optional): the user's name. If provided this is used to pre-populate sign-up fields for new users.

Generating a Launch Link:

This API is used to generate a launch link, which can be created as follows:

1. The external server makes a POST request to the API endpoint to generate a (single use) launch link for a user who wishes to sign on to OpenLearning
2. The server responds with a JSON document which has the following structure:

   {
      "url": "https://www.openlearning.com/...",
      "method": "POST",
      "params": {
         ... form parameters
      }
   }
   

3. The server uses this JSON document to build a form, which is sent to the user's client (see: Basic LTI Sample Launch for more details):

   <form method="POST" action="{url}">
   
     <input type="hidden" name="{params.key}" value="{params.value}">
     ... for each key/value pair in params
   
     <input type="submit" name="Launch OpenLearning"/>
   </form>
   

4. The external service can link to this generated form, which automatically submits itself (e.g. via JavaScript), or the external service can embed this form within the website to provide a launch button.