1.1 Terminology

JWT

JSON Web Token is a JSON-based [RFC7159] security token encoding that enables identity and security information to be shared across security domains. A security token is generally issued by an Identity Provider and consumed by a Relying Party that relies on its content to identify the token's subject for security-related purposes.

LIS

Learning Information Services® (LIS®) is an IMS standard that defines how systems manage the exchange of information that describes people, groups, memberships, courses and outcomes [LIS-20]

LTI

Learning Tools Interoperability (LTI) is an IMS standard for integration of rich learning applications within educational environments.

URI

The Uniform Resource Identifier (URI) utilizes the US-ASCII character set to identify a resource. Per [RFC2396], a URI "can be further classified as a locator, a name or both." Both the Uniform Resource Locator (URL) and the Uniform Resource Name (URN) are considered subspaces of the more general URI space.

URL

A Uniform Resource Locator (URL) is a type of URI that provides a reference to resource that specifies both its location and a means of retrieving a representation of it. An HTTP URI is a URL.

URN

A Uniform Resource Name (URN) is a type of URI that provides a persistent identifier for a resource that is bound to a defined namespace. Unlike a URL, a URN is location-independent and provides no means of accessing a representation of the named resource.

UUID

a 128-bit identifier that does not require a registration authority to assure uniqueness. However, absolute uniqueness is not guaranteed although the collision probability is considered extremely low. LTI recommends use of randomly or pseudo-randomly generated version 4 UUIDs [RFC4122].

1.2 Conformance Statements

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [RFC2119].

An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

The Conformance and Certification Guide for this specification may introduce greater normative constraints than those defined here for specific service or implementation categories.

1.3 Document Set

2.1 Redirection from platform to tool

The platform handles this redirection to the tool just as with the core LTI resource link launch request. It creates an HTML form that the browser can auto-submit via JavaScript to an endpoint hosted by the tool using an HTTP POST.

The platform sends the same message parameters in the deep linking request message as it would in the resource link launch request message with the exception of the resource link claim, along with some additional parameters.

The lti_message_type of this new message has a value of LtiDeepLinkingRequest.

The platform creates and signs the message in the same way it does with the core LTI resource link launch request (see the LTI 1.3 [LTI-13] and IMS Security Framework [SEC-10] specifications for details). Given the intended workflow implied by this message type, the platform may intend the tool's user experience to open within an iframe or pop-up window, to let the current UI context in the platform remain visible and available when the user returns from the tool's workflow; however, this is not a requirement, and other workflows using the same deep linking request message type may re-use the same page as the platform.

2.2 Tool user experience for deep linking

The tool entirely controls the user experience for discovering and selecting content items within its body of available resources.

The tool SHOULD verify the deep linking request message in the same way it would for a resource link launch request. The parameters the tool receives in the message SHOULD, by best practice, contain sufficient data to allow the tool to identify the context from which the user is being passed, who the user is, and what the user's role in the context is.

Where appropriate the tool can use this data to provide an appropriate collection of items from which the user can select, or allow the user to create a new item (and retrieve a reference to the new item).

The tool MUST recognize that the platform makes no guarantee that it will actually create a resource link to the selected (or created) item(s) upon returning the user to the platform (for example, the user may have the option to cancel the workflow before creating a resource link in the platform).

2.3 Redirection back to the platform

When forming the deep linking request message, the platform includes a deep_link_return_url in the https://purl.imsglobal.org/spec/lti-dl/claim/deep_linking_settings claim. The tool MUST redirect the workflow to that URL once the user has completed the selection or creation portion of the overall flow.

By best practice, a tool SHOULD always ensure to redirect the user's browser back to this endpoint, even if the user selects or creates no items. This allows the platform to close any frames or windows it opened during the initial redirection step.

The tool passes back to the platform details of any selected or created items in a JSON array (this array could be empty, if no item was selected or created).

After encoding the deep linking return message as a JWT, the tool MUST always perform this redirection using an auto-submitted form as an HTTP POST request using the JWT parameter (see the IMS Security Framework [SEC-10]) for more details about the use of JWT), redirecting the user's browser to the platforms's deep_link_return_url.

The lti_message_type of this new message has a value of LtiDeepLinkingResponse.

3.1 Link

A link is a fully qualified URL to a resource hosted on the internet. The item may include different rendering options (window, iframe, embed). As a best practice, the tool SHOULD return all the ones that apply, allowing the platform to use the best option based on the actual rendering context when the item is displayed.

A link may contain different rendering instructions that the platform may use to properly display the link; if none of those attributes are present, the default behavior is to open the resource in a new browser window/tab.

Properties of a link are:

3.2 LTI Resource Link

A link to an LTI resource, usually delivered by the same tool to which the deep linking request was made to. A platform may support links associated to other tools. How this association may happen is not specified.

Properties of an LTI link are:

3.3 File

A file is a resource transferred from the tool to stored and/or processed by the platform. The URL to the resource should be considered short lived and the platform must process the file within a short time frame (within minutes).

Properties of a file item are

3.4 HTML fragment

An HTML fragment to be embedded in html document. If the HTML fragment renders a a single resource which is also addressable directly, the tool SHOULD use the link type with an embed code.

Properties of an HTML fragment are:

3.5 Image

Image is a URL pointing to an image resource that SHOULD be rendered directly in the browser agent using the HTML img tag.

Properties of image are:

3.6 Extending a type

Type definitions may be enriched with additional properties. The key for custom properties SHOULD be a fully qualified URL. This requirement does not apply to nested properties of the added property.

For example:

{
  "type": "image",
  "url": "https://www.example.com/image.png",
  "https://www.example.com/resourceMetadata": {
    "license": "CCBY4.0"
  }
}

3.7 Defining new types

The Deep linking specification defines a flow to transfer item(s) from the tool to the platform. In the future, it is expected to be leveraged to transfer of other types of items.

When a new type is added, it must to the minimum contain a type property and a value that uniquely identifies the new type. To avoid collisions, the value must be a fully qualified URL unless specified otherwise by IMS Global.

4.1 JSON Web Token

As with the core resource link launch request, the senders of the deep linking messages MUST wrap the payload in a JSON Web Token (JWT) [RFC7519]. This allows the receiver of a deep linking message to trust the authenticity and origin of the message even though the messages travel through the user's browser. For details on the process by which message senders encode messages into JWTs, see the IMS Security Framework specification [SEC-10].

4.2 Message claims

Both deep linking message types consist of a set of claims that supplement the ones mandated by the IMS Security Framework [SEC-10] specification. Additionally, both message types include many of the claims defined in the core LTI resource link launch request message, defined in LTI 1.3 [LTI-13]. This document lists the claims here, but see the above referenced specifications for their full definitions.

4.3 Message type and schemas

Each deep linking message's https://purl.imsglobal.org/spec/lti/claim/message_type claim value declares the appropriate message type. Both deep linking message types have associated JSON schemas that formally define all their claims, which claims are required, and which are optional.

4.4 Deep linking request message

The LTI Deep Linking request message is a signed JWT that the platform passes to the tool with the same message parameters in the deep linking request message as it would in the resource link launch request message with the exception of the resource link claim, along with some additional parameters.

An LtiDeepLinkingRequest JWT contains the following claims:

{
  "https://purl.imsglobal.org/spec/lti-dl/claim/deep_linking_settings": {
    "accept_types": ["link", "file", "html", "ltiResourceLink", "image"],
    "accept_media_types": "image/:::asterisk:::,text/html",
    "accept_presentation_document_targets": ["iframe", "window", "embed"],
    "accept_multiple": true,
    "auto_create": true,
    "title": "This is the default title",
    "text": "This is the default text",
    "data": "Some random opaque data that MUST be sent back",
    "deep_link_return_url": "https://platform.example/deep_links"
  }
}

4.5 Deep linking response message

The LTI Deep Linking response message is a Tool-Originating Message as defined in the Tool-Originating messages section of the Security Framework specification [SEC-10].

The response message covers the last part of the overall deep linking workflow: a user has finished selecting or creating one or multiple resources in the external tool, and the user needs to be redirected back to the platform with information about the resources to be added; the User Agent redirection is done using a form POST with the form parameter JWT being the response message.

The message contains a JSON array of the items to be added. This array could be empty, if no item were selected or created.

An LtiDeepLinkingResponse JWT contains the following claims in addition to the ones required by the Security Framework specification [SEC-10]: