1EdTech Final Release

1EdTech Learning Tools Interoperability™ (LTI) Messaging Framework

Version 2.0 Final Specification

Date Issued: 6 January 2014
Latest version: http://www.imsglobal.org/lti/

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/license.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44

The 1EdTech Logo and Learning Tools Interoperability (LTI) are trademarks of the 1EdTech
Learning Consortium, Inc. in the United States and/or other countries.
Document Name: 1EdTech Learning Tools Interoperability Messaging Framework v2.0 Final
Revision: 6 January 2014

1 Introduction

This document is an implementation guide that explains how messages are sent from the Tool Consumer to message handlers within the Tool Provider. It defines a behavioral model for the transport and receipt of those messages, and it describes procedures for binding a message as an HTTP request.

1.1 Conceptual Overview

Move to top

Messages originate within the Tool Consumer and are sent to a Message Handler within the Tool Provider, as shown in Figure 1.1. In practice, messages might not come directly from the Tool Consumer. For example, in the case of a Tool Launch Request, the message may come from the user's browser. However, even in this case, the message is constructed in the Tool Consumer and passed to the browser. The browser merely forwards the message to the Message Handler. Thus, in all cases, the message does indeed originate from within the Tool Consumer.

Figure 1.1 Messaging from Tool Consumer to Tool Provider.

In the LTI standard, each type of message is modeled as a different class. It is important to keep in mind that we represent these entities as classes purely for expository convenience. Implementers do not need to realize these classes in some programming language like Java or C# (though they may do so). In fact, as discussed in Section 4, the only message bindings required by the LTI Standard are encodings based on the HTTP request protocol. Other bindings and other wire protocols may be introduced in later versions of the standard, but in the current version LTI Messages are just HTTP requests. The LTI standard does not define any bindings for the Message Handlers. They may be implemented using any available technology for handling HTTP requests, such as Java Servlets, Active Server Pages, PHP, etc.

1.2 Nomenclature

Move to top

A list of and definitions for commonly used terms in the LTI specification are contained in the LTI Implementation Guide document [LTI, 14 IMG].

1.3 Structure of this Document

Move to top

The structure of this document is:

2 Key Concepts	Description of the key concepts related to LTI security
3. Behavioral Model	Description of the LTI security behavioral model and use cases
4. Bindings and Implementation Guidelines	Description of the binding of security messages and guidelines for implementation

1.4 References

Move to top

[LTI, 14 IMG] G. McFall, L. Neumann, S.Vickers, 1EdTech Learning Tools Interoperability Implementation Guide v2.0 Final, 1EdTech Consortium, January 2014. http://www.imsglobal.org/lti/

[LTI, 14 SEC] G. McFall, L. Neumann, S.Vickers, 1EdTech Learning Tools Interoperability Security v2.0 Final, 1EdTech Consortium, January 2014. http://www.imsglobal.org/lti/

[LTI, 14 TMT] G. McFall, L. Neumann, S.Vickers, 1EdTech Learning Tools Interoperability Tool Management v2.0 Final, 1EdTech Consortium, January 2014. http://www.imsglobal.org/lti/index.html

2 Key Concepts

2.1 Message Types

Move to top

LTI 2.0 defines two different types of messages:

Basic LTI Launch Request
Tool Proxy Registration Request

Each message type has a symbolic name that appears in the Tool Profile where the Tool Provider declares the types of message handlers that it supports (see Section 2.5). The symbolic names also appear in the Tool Consumer Profile, where the Tool Consumer declares the types of messages that it can emit. The symbolic names for the three supported message types, are respectively (1) basic-lti-launch-request, and (2) ToolProxyRegistrationRequest.

These messages are examples of a Tool Launch Request, an HTTP Request posted from the user’s browser. This submission occurs when the user follows a link or clicks a button in the Tool Consumer system and navigates into the Tool Provider system.

2.2 Tool Launch Service

Move to top

The Tool Consumer implements a Tool Launch Service which is responsible for generating Tool Launch Requests. Requests to launch an external tool are submitted to the Tool Launch Service within the Tool Consumer. The launch service generates an HTML form that encapsulates the Tool Launch Request, and it sends this form to the user’s browser in the HTTP response. The browser automatically posts the form contents to the appropriate message handler within the Tool Provider. This sequence is described in Use Case LTIv1-25. See also Section 4.1 for a discussion about the HTML form binding for messages.

2.3 Transport Method

Move to top

The LTI standard dictates that all LTI messages must be delivered as HTTP(S) requests. Messages are sent via HTTP(S) POST or GET (as defined for each message type) using the "application/x-www-form-urlencoded" encoding.

2.4 Message Parameters

Move to top

Each concrete message type is defined formally by a class that inherits attributes from a collection of base classes known as mixins, as shown in Figure 2.1. The concrete class and its mixins define the standard set of parameters associated with the given message type. Section 4 explains how the attributes from the class model map to parameters in the HTML Form encoding for messages.

Figure 2.1 A fictitious concrete message type illustrating multiple inheritance

Any given mixin associated with a message type may be required or optional. The arc from the concrete type to a required mixin is solid. The arc to an optional mixin is dashed.

2.4.1 Custom Parameters

In addition to the standard parameters specified in the class model, each message may also contain a collection of custom parameters. These custom parameters are modeled as a set of Property objects in the CoreMessageMixin (see Figure 2.1). Note that each Property is just an arbitrary name/value pair.

The values that appear as custom parameters come from two different sources:

Parameter definitions within the Tool Profile, and
Parameters added by the creator of a link.

Parameter definitions within the Tool Profile are discussed in Section 2.5.

The LTI standard does not specify a particular user interface for authoring links. Each Tool Consumer may implement its own user interface, but it must be possible for the link creator to add arbitrary name/value pairs to any link.

When a custom parameter is mapped to a POST parameter in an HTTP Request (see Section 4.1), the name of the parameter is rendered with “custom_” as a prefix. This practice ensures that there are no collisions with standard parameter names defined in the class model. For example, if the creator of a link adds a custom parameter named “learning_objective”, the POST parameter would be named “custom_learning_objective”.

2.5 Message Handler Declarations

Move to top

Each Tool registers with the Tool Consumer the types of messages that it can handle. These message handler definitions appear in the Tool Profile. As shown in Figure 2.2, a message handler definition includes the symbolic name for the message type and the end point URI for the message handler within the Tool Provider system. The endpoint definition is a path relative to a base URL declared in the “tool info” section of the Tool Profile.

"message" : [

{

"message_type" : "basic-lti-launch-request" ,

"path" : "resource/homework" ,

"parameter" : [

{ "name" : "discipline" ,

"fixed" : "chemistry"

{ "name" : "lis_person_name_given" ,

"variable" : "$Person.name.given"

{ "name" : "textbook_isbn" },

{ "name" : "chapter" }

]

}

]

Figure 2.2 Message Handler definition in Tool Profile.

The Tool Consumer discovers these message handlers during the deployment of a Tool Proxy[1].

When defining custom parameters, the Tool Provider may choose to assign a fixed value or a variable value to the parameter, as illustrated in Figure 2.2

In this example, when the Tool Consumer posts a message of type basic-lti-launch-request to the Tool Provider at the specified path, it will pass four custom parameters with the following names[2]:

custom_discipline
custom_lis_person_name_given
custom_textbook_isbn
custom_chapter

The value for the custom_discipline parameter will always be “chemistry” because this parameter was declared with a fixed value.

The value for the custom_lis_person_name_given parameter will depend on the particular user who clicks the link because this parameter is declared with a variable value. For more information about variables, see [LTI, 14 IMG].

The Tool Profile does not specify values for the textbook_isbn and chapter parameters. The link creator must supply these values explicitly through a user interface exposed by the Tool Consumer.

2.6 Messaging Capabilities

Move to top

A given Tool Consumer system may be able to emit certain types of messages but not others. The Tool Consumer must declare the specific types of messages that it supports in the “capabilities” section of the Tool Consumer Profile. For example, a Tool Consumer that can emit the basic-lti-launch-request would declare this capability as shown in Figure 2.3. In addition, the Tool Consumer must also declare capabilities for the variables that it supports.

Figure 2.3 Capabilities declared in Tool Consumer Profile

3 Behavioral Model

3.1 Overview of the Behavioral Model

Move to top

Figure 3.1 Diagram depicting the Messaging Framework behavioral model.

The behavioral model of the Messaging Framework is straight-forward. The Tool Consumer Runtime is responsible for constructing and sending messages. The Message Handler within the Tool Provider receives messages and sends responses

Section explains how the Tool Consumer Runtime constructs messages. Messages are sent using the standard HTTP protocol, as defined by the World Wide Web Consortium (http://www.w3.org/Protocols).

Message Handlers may receive messages using any available technology for handling HTTP requests.

3.2 Use Cases

Move to top

This section describes the use cases for transmitting messages from the Tool Consumer to the Tool Provider. In LTI 2.0, there is only one messaging use case. Future versions of LTI may introduce additional use cases cases where the Tool Consumer Runtime invokes the HTTP Message Handlers in the Tool Provider:

3.2.1 Serving Content to the User from the Tool Provider

Figure 3.2 Sequence diagram illustrating content being served to the user from the Tool Provider.

Use Case Title:	Serving Content to the User from the Tool Provider
Use Case Local ID:	LTIv1-25
Brief Description:	In this use case, the user initially navigates within the Tool Consumer User interface and is transferred to the Tool Provider User Interface. The sequence includes a single-sign-on protocol so that the Tool Provider can authenticate the user based on credentials signed by the Tool Consumer. The launch request from Tool Consumer to Tool Provider includes enough information about the learning context to ensure a consistent user experience.
Level:	Summary
Actors:	Tool Consumer Runtime, Tool Provider Message Handler, User
Preconditions:	The Tool Proxy has been deployed and enabled within the Tool Consumer. The User has logged into the Tool Consumer.
Basic Flow of Events:	1. Activate LTI Link. The user clicks a link rendered in their browser by the Tool Consumer and the HTTP request is sent to the Tool Launch Service within the Tool Consumer. 2. Send HTML page containing Launch Request. The Tool Launch Service generates an HTML page containing a form whose ‘method’ attribute is ‘POST’. The form fields correspond to a serialization of the LTI Launch Request message. 3. Auto-submit: The HTML page includes JavaScript code to automatically submit the form. The target for the form should be the URL for the appropriate Message Handler in the Tool Provider system as defined in the Tool Profile (where the URL is constructed by combining the base URL and message “path”). 4. Post the Launch Request. The user’s browser posts the form containing the Launch Request to the Tool Provider server. 5. Render Tool Provider Content. The Tool Provider validates the launch request in accordance with the security profile negotiated during the tool deployment process. Among other things, the launch request includes a “return URL” parameter. The Tool Provider saves this URL (possibly as a cookie), so that it will be able to redirect the user’s browser back to the Tool Consumer system when the user is done interacting with the Tool. (See Step 7.) Finally, the Tool Provider responds to the launch request by sending the requested content to the user’s browser. 6. End Tool Activity. The user interacts with the Tool, and eventually performs some action to “close” the Tool. 7. Send Redirect. When the Tool Provider receives a request to close the Tool, it redirects the User’s browser to the “return URL” that it received when the Tool was launched at Step 4. The HTTP 301 redirect message should be sent to the same window or frame in which the Tool was launched. 8. Handle Redirect. The Tool Consumer receives the redirected request. 9. Render Tool Consumer page. The Tool Consumer resumes control of the user experience.
Alternate Paths:	A. Open New Window or IFRAME The Basic Flow treats the case where the Tool is opened in the same window that held the original LTI link. However, the link may also be configured to open in a new window or an IFRAME. B. JavaScript is disabled. The HTML Form delivered at Step 2 should contain a submit button nested within a <noscript> tag. Thus, if JavaScript is disabled, the user will be able to submit the request by manually clicking the submit button instead of relying on the auto-submit behavior at Step 3. C. Basic LTI. For Basic LTI links, there is a slight variation to the Basic Flow. · End-point URL is associated with the Basic LTI link directly. With Full LTI, a Tool Proxy is associated with a Tool Profile that declares message handlers (see Step 3 of the Basic Flow). However, Basic LTI links do not have an associated Tool Profile. Instead each Basic LTI link is associated with a message handler URL directly at the time the link is created. · The security profile is non-negotiable. Basic LTI links always use the lti_oauth_hash_message_security profile. See [LTI, 14 SEC] for details. D. Send Cookies When the Tool Provider responds to the launch request at Step 5, it may also send cookies. For example, the Tool Provider may choose to send a session cookie to the user’s browser. E. Exchanging the User Profile Most tool launch requests contain a parameter that uniquely identifies the user. The Tool Provider will not know anything about this user the first time he or she attempts to access the tool. Consequently, upon receiving the first request from a given user, the Tool Provider might need to read the user’s profile from the Tool Consumer. This exchange can be accomplished by invoking the LIS Person Manager web service offered by the Tool Consumer server. The Tool Provider discovers the endpoint URL for this web service by inspecting the Tool Consumer Profile which it received during the tool deployment process. Alternatively, the Tool Provider might arrange for user properties to be embedded directly in the launch request as variable parameters. For a list of the variable parameters associated with the Person entity, see [LTI, 14 IMG]. F. Exchanging Course Section Details If the tool was launched from a particular course section within the Tool Consumer system, the launch request will contain an identifier for the section as the context_id parameter. In the same way that the Tool Provider might read a user’s profile from the LIS Person Manager, so too the Tool Provider can read Course Section details by invoking the LIS Course Section Manager. Alternatively, the Tool Provider might arrange for course section properties to be embedded directly in the launch request as variable parameters. For a list of the variable parameters associated with the Course Section entity, see [LTI, 14 IMG]. G. Direct Return to Tool Consumer Instead of sending an HTTP 301 redirect at Step 7, the Tool Provider user interface may contain a normal HTML link whose href points directly at the return URL within the Tool Consumer system. Thus, when the user clicks such a link, the browser will navigate directly to the Tool Consumer system. H. Tool Consumer Closes Window If the tool was opened in a new window, it is the responsibility of the Tool Consumer to close the window after handling the redirect at Step 8. The Tool Consumer may choose to display a message in the window and provide a control which allows the user to close the window manually. Or the Tool Consumer may automatically close the new window and shift focus to the “opener” window. I. Abrupt closing of Window If the tool was opened in a new window, it is possible for the user to close that window abruptly without officially ending the current activity within the Tool. That is to say, the user might forcibly close the browser window prior to Step 6 in the Basic Flow. In this case, the Tool Consumer will not receive a redirect at the “return URL”. J. Session Management When the user leaves the Tool Provider system at Step 7, the Tool Provider may choose to keep the user’s session alive in anticipation that the user might return. If the user does not return, the Tool Provider should eventually terminate the session due to a suitable time-out constraint. LTI version 2.0 does not define a single-sign-out protocol. Alternatively, the Tool Provider may choose to terminate the user’s session each time he or she leaves the Tool Provider system. In this case, the user will acquire a new session with each launch request.

4 Bindings and Implementation Guidelines

4.1 HTML Form Binding for Messages

Move to top

Tool Provider Message Handlers receive messages as HTTP requests which result from the submission of an HTML form with the following characteristics:

The ‘enctype’ attribute has the value “application/x-www-form-urlencoded”.
The ‘action’ attribute of the form is the target URL for the LTI Message. This URL is either defined in the Tool Profile as the combination of the base URL and the ‘path’ attribute of the appropriate ‘message’ element.
The method (GET or POST) adheres to the convention as specified by the given message type. See the documentation for each message type to determine the appropriate HTTP method.
The form fields correspond to attributes in the LTI Information Model. Whereas the HTML form contains a flat sequence of input fields, the information model tends to be more structured. The set of fields that appear in the HTML form are specified explicitly for each message type as part of the documentation for that message type. The field names as defined in the documentation set are derived from the information model in accordance with the following rules:

1. For each simple type that appears as an attribute of the message class or one of its mixins, add a hidden input field with the same name.

2. For each complex type, add its attributes as hidden fields where the name for each hidden field is formed by concatenating the name of the complex attribute with the name of the attribute within the complex type, delimited by an underscore. For example, the ContextMixin class contains an entity attribute named “context” and the Context entity in turn contains a simple attribute named “id”. Thus, the field name in the HTML form is “context_id”.

3. For each applicable tool setting and each applicable parameter declared in the Tool Profile, add a field whose name matches the given property name with “custom_” as a prefix.

4. Add fields as dictated by the Security Contract for the message type.

4.1.1 Guidelines for generating the HTML page

This section provides guidelines for the Tool Consumer when generating the HTML page containing a launch request that is returned to the User’s browser.

The HTML page should include JavaScript code to submit the form automatically.

The form should include a control, such as a button, so that users may submit the form manually if JavaScript is disabled.

Figure 4.1 illustrates these guidelines.

<form

action="URL_FOR_MESSAGE_HANDLER_AS_DEFINED_IN_TOOL_PROFILE"

name="ltiLaunchForm"

method="post"

enctype="application/x-www-form-urlencoded">

<!—security parameters -->

<!—lti message parameters -->

…

</noscript>

</form>

document.ltiLaunchForm.submit();

</script>

Figure 4.1 Sample HTML showing the structure of an HTML Form Binding for an LTI message

Notice that the form contains a collection of message parameters and a collection of security parameters. The security profile agreed upon by Tool Consumer and Tool Provider during the tool deployment process dictates the specific set of security parameters that must be present. In the example shown here, the security parameters are dictated by the oauth security profile.

Most security profiles include a digital signature or message authentication code (MAC). The digital signature is a hash of the string formed by concatenating all of the POST parameters[3]. For the oauth security profile, the signature is provided by the oauth_signature parameter as shown at Line 8.

4.1.2 Benefits of auto-submitting an HTML form via POST

Using an auto-submitted HTML form via the HTTP POST method has the following benefits over an HTTP redirect:

· The amount of data that can be included in an HTTP POST is unlimited, whereas the amount of data in an HTTP redirect is constrained by browser-specific limitations on the length of a URL.

· Sending the LTI Message in the POST body of the HTTP request rather than URL encoded query string limits the exposure of the LTI Message attributes. For example, personally identifiable information that might be transmitted as message attributes will not be visible in a POST that uses the HTTPS protocol.

4.1.3 Non ASCII characters

Non ASCII characters in parameter names or values should be escaped as described in: http://www.w3.org/TR/html40/appendix/notes.html#non-ascii-chars

About This Document

Title: 1EdTech Learning Tools Interoperability Messaging Framework

Co-chairs: Greg McFall (Pearson), Lance Neumann (Blackboard)

Editor: Greg McFall (Pearson), Lance Neumann (Blackboard), Stephen Vickers (1EdTech)

Version: 2.0

Version Date: 6 January 2014

Status: Final Release

Summary: This document describes how messages are sent from the Tool Consumer to message handlers within the Tool Provider and provides a behavioral model for the transport and receipt of those messages.

Purpose: This document is made available for adoption by the public community at large.

Document Location: Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44

4.2 List of Contributors

Move to top

The following individuals contributed to the authoring of this document:

Craig Dunk	Desire2learn	Colin Smythe	1EdTech
Greg McFall	Pearson	Matt Stoelting	Cengage
Mark McKell	1EdTech	John Tibbetts	VitalSource
Lance Neumann	Blackboard	Stephen Vickers	1EdTech
Charles Severance	University of Michigan

Revision History

Version No.	Release Date	Comments
v2.0 Public Draft	1 November 2012	First release of the Messaging Framework specification for LTI 2.
v2.0 Final	6 January 2014	Remove ReRegistration message-type (to be included in a later release).

1EdTech Consortium, Inc. (“1EdTech”) is publishing the information contained in this 1EdTech Learning Tools Interoperability Messaging Framework (“Specification”) for purposes of scientific, experimental, and scholarly collaboration only.

1EdTech makes no warranty or representation regarding the accuracy or completeness of the Specification. This material is provided on an “As Is” and “As Available” basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

1EdTech would appreciate receiving your comments and suggestions.

Please contact 1EdTech through our website at http://www.imsglobal.org

Please refer to Document Name: 1EdTech Learning Tools Interoperability Messaging Framework v2.0 Final
Revision: 6 January 2014

[1] See Use Case LTIv1-01 in the Tool Management Specification [LTI, 14 TMT]

[2] The link creator may define additional parameters besides the ones declared in the Tool Profile.

[3] For details about the hash algorithm, see [LTI, 14 SEC].

1EdTech Learning Tools Interoperability™ (LTI) v2.0 Messaging Framework

1 Introduction

1.1 Conceptual Overview

1.2 Nomenclature

1.3 Structure of this Document

1.4 References

2 Key Concepts

2.1 Message Types

2.2 Tool Launch Service

2.3 Transport Method

2.4 Message Parameters

2.4.1 Custom Parameters

2.5 Message Handler Declarations

2.6 Messaging Capabilities

3 Behavioral Model

3.1 Overview of the Behavioral Model

3.2 Use Cases

3.2.1 Serving Content to the User from the Tool Provider

4 Bindings and Implementation Guidelines

4.1 HTML Form Binding for Messages

4.1.1 Guidelines for generating the HTML page

4.1.2 Benefits of auto-submitting an HTML form via POST

4.1.3 Non ASCII characters

About This Document

4.2 List of Contributors

Revision History