Overview

This is the developer reference guide to Boclips LTI implementation.

At the moment we support LTI 1.1 only.

Boclips LTI Features

Our current LTI implementation delivers read only views of resources:

  • videos,

  • collections of videos,

  • lists of video collections.

LTI is used here to authenticate external users within Boclips application. They don’t need to create accounts or log in, an LTI handshake does it on their behalf, making the experience seamless.

LTI protocol assumes that one web application will be opened from or within another web application. The aforementioned resources are thus plain web pages that display content to users. Whether that page is opened in a separate window or embedded within an iframe element is a matter of design preference.

LTI 1.1

In LTI 1.1 world, the two parties interacting with each other are:

  • tool provider — a service that has resources than can be accessed (consumed) using LTI. This is e.g. Boclips,

  • tool consumer — yourself, or any other party that wants to access Boclips content using LTI.

There is plenty of detailed documentation available on LTI (some of it linked below), but in a nutshell the simplest LTI workflow that we support looks like this:

  1. tool consumer executes an LTI launch request against the tool provider. It’s a HTTP POST request with some specific parameters,

  2. tool provider verifies the launch request (this is discussed further in following sections),

  3. if the launch request is valid, tool provider automatically provisions or retrieves a user account, establishes a HTTP session, sets a cookie and responds with a HTTP redirect to requested resource,

  4. tool consumer follows the redirect, passing previously received session cookie along,

  5. content is displayed to the end user.

Authentication

Launch requests are verified based on a pre-shared set of credentials, consumer key and consumer secret. These are created by Boclips and exchanged with you before any integration can take place — they can be thought of as an equivalent of API keys.

An LTI 1.1 handshake works as follows:

  1. tool consumer collects all parameters required to execute a Launch Request,

  2. then it uses the secret to compute an OAuth 1.0 signature for that request. All POST parameters, HTTP method itself and request URL are included in signature generation,

  3. the signature is then attached as another POST parameter and the request is executed,

  4. upon receiving the request, tool provider removes the signature parameter, recomputes the signature and verifies the request,

  5. if the signature matches and all mandatory parameters are present, the request is deemed valid.

The key is passed as a part of a launch request and allows to identify different consumers. The secret should be stored in a secure manner and not be exposed to 3rd parties.

Anatomy of a Launch Request

All parameters mentioned below are transmitted as standard HTTP POST parameters.

LTI Parameters

A minimal subset of LTI launch request parameters required to access Boclips resources is presented in the table below.

Please note that LTI specification permits more parameters in order to pass contextual information along. Some parameters are treated as recommended, others are optional. Many recommended parameters include user information — this helps with automatic account provisioning.

More info on supported parameters can be found in official specification.

Parameter Type Optional Description

lti_message_type

String

false

The type of LTI message as defined in LTI spec. For our case it’s a basic launch request and should be set to basic-lti-launch-request

lti_version

String

false

The LTI version. Per spec it should be set to LTI-1p0 for LTI 1.1

resource_link_id

String

false

Generated by the consumer, uniquely identifies the launch link that initiated an LTI launch within the consumer application

OAuth 1.0 Parameters

LTI 1.1 security model is based on OAuth 1.0 message signing. A well formed LTI launch request must contain all parameters listed below.

Ideally you won’t need to handle all of those yourself — there are open source LTI and/or OAuth 1.0 libraries available, for example we use an official IMS one for our JVM apps.

Parameter Type Optional Description

oauth_consumer_key

String

false

The LTI consumer key. We create it and give it to you as a part of credentials exchange

oauth_version

String

false

OAuth version, should always be set to 1.0

oauth_signature_method

String

false

Signature method, should be set to HMAC-SHA1

oauth_signature

String

false

The signature generated from request parameters and LTI consumer secret

oauth_timestamp

Number

false

Request timestamp, expressed in the number of seconds since January 1, 1970 00:00:00 GMT. More details here

oauth_nonce

String

false

A random value to help with uniquely identifying each request. More details here

Boclips Custom Parameters

We support additional parameters that allow customizing the LTI experience. They can be passed along all the other launch request parameters.

Parameter Type Optional Description

custom_logo

URL

true

A URL to an image file that will be displayed at the top of LTI pages

user_id

String

true

A user ID which identifies the specific Boclips user interacting with LTI. This enables per-user analytics for backend clients.

Sample Launch Request

Below is an example of a valid LTI launch request issued using. Please note that the values below are just sample placeholders, not real parameters that can be used to execute a launch:

POST /v1p1/videos/5c542abf5438cdbcb56df0bf HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1
Host: lti.boclips.com

custom_logo=https%3A%2F%2Fstorage.googleapis.com%2Fboclips-public-static-files%2Fboclips%2Flogo.png&lti_version=LTI-1p0&oauth_nonce=51090440264510&oauth_signature=KFZ6t75lwWXh0k1Dhx2oLThsFzU%3D&lti_message_type=basic-lti-launch-request&user_id=some_user_id&oauth_consumer_key=your-consumer-key&resource_link_id=41B464BA-F406-485C-ACDF-C1E5EB474156&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1637950365&oauth_version=1.0

The server responds with a redirect to the resource and sets a session cookie:

HTTP/1.1 303 See Other
Location: /videos/5c542abf5438cdbcb56df0bf
X-XSS-Protection: 1; mode=block
Set-Cookie: SESSION=N2IwOWJjMWQtODM3Mi00ZGM4LWFiMmItNGRlMmJmNWUzYTJh; Path=/; Secure; HttpOnly; SameSite=None
Via: 1.1 google
Alt-Svc: clear
Given our current LTI implementation, the launch requests will look nearly the same for other resource types. Only the resource URL will change.

Resource Endpoints

Single Video

Displays a single video playable using our interactive player.

/v1p1/videos/{videoId}

Collection of Videos

Displays a collection of videos with thumbnails and descriptions. Clicking on any of them will take the user to a video page.

/v1p1/collections/{collectionId}

List of Collections

Displays a list of available collections with a subset of video thumbnails for each of them. Selecting one of them will take the user to a video collection page.

/v1p1/collections
Note that the assumption is that IDs of resources are known in advance and as a consumer you embed LTI links them as you choose. Alternatively, users can explore the full content library from the collections list page (last resource).

External Resources

Below are a mix of official LTI docs from IMS and articles written by developers that can prove useful when implementing LTI capabilities.