Overview

This is the developer reference guide to Boclips LTI implementation.

LTI is used to authenticate external users within the 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.

The high-level flow is:

  • The LMS authenticates itself and the user against the Tool (eg. Boclips)

  • If successful, the Tool will:

    • set up a session for the user,

    • and redirect them to the requested resource

We support both LTI 1.1 and LTI 1.3. Depending on which version is used, the authentication flow and how the supported features can be accessed is different and explained in more detail in this document.

LTI Features supported

Displaying a single video

The user is able to display a single video playable using our interactive player.

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.

Searching and embedding videos

This feature allows users to browse our full video library and select the resources (videos) they want to embed in their lesson. This is a more flexible way of integrating with Boclips as users are not constrained by the pre-selected resources.

The feature can be used like:

  1. User accesses the Boclips search view inside their LMS

  2. User is able to search videos by text and filter by metadata (eg. video duration, educational level, subject)

  3. When an appropriate video is found, the user can select it and initiate the embed flow

  4. The selected resource is sent back to the LMS

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.

More info can be found in the official specification.

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.

Accessing a single video

Resource endpoint to be used is:

/v1p1/videos/{videoId}

The request has to set lti_message_type as basic-lti-launch-request.

Search and embed

Resource endpoint to be used is:

/v1p1/search-and-embed

The request has to set lti_message_type as ContentItemSelectionRequest.

External Resources for LTI 1.1

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

LTI 1.3

LTI version 1.3 improves upon version by moving away from the use of OAuth 1.0a-style signing for authentication and towards a new security model, using OpenID Connect, signed JWTs, and OAuth2.0 workflows for authentication.

When using LTI 1.3 the parties interacting with each other are:

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

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

Configuring the integration

Before the integration can take place, both parties need to exchange configuration entries with each other.

Boclips URLs

Information to be shared with Boclips

  • Issuer (iss)

  • Authentication endpoint URL

  • JWKS URL

  • Client ID

Authentication

An LTI 1.3 handshake works as follows:

  1. platform initiates a login request against tool

  2. tool executes an OAuth 2 Implicit Flow against platform's IdP

  3. end user is redirected to the IdP

  4. if the user authenticated successfully, the platform has to assemble an ID Token with the related LTI claims added to it

  5. tool validates the ID Token with LTI claims and redirects the user to the LTI resource requested originally

More detail can be found in the official Authentication Workflow specification.

Mandatory LTI claims

Details about the mandatory LTI claims can be found in the official documentation.

Accessing a single video

The below claims has to be set as:

  • https://purl.imsglobal.org/spec/lti/claim/message_type to be LtiResourceLinkRequest

  • https://purl.imsglobal.org/spec/lti/claim/target_link_uri to be https://lti.boclips.com/videos/{videoId}

Search and embed

The below claims has to be set as:

  • https://purl.imsglobal.org/spec/lti/claim/message_type to be LtiDeepLinkingRequest

  • https://purl.imsglobal.org/spec/lti/claim/target_link_uri to be https://lti.boclips.com/search-and-embed

External Resources