1EdTech Learning Tools Interoperability™ (LTI) Security
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.
Copyright © 2014 1EdTech Consortium. All Rights Reserved.
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
© 2014 1EdTech Consortium, Inc.
All Rights Reserved.
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 Security v2.0
Final – Revision: 6 January 2014
1 Overview
LTI defines a number of interactions between the Tool Consumer, Tool Provider, and End User. Each of these interactions requires some form of security, but LTI only documents a few of the paths. The ones not covered are the responsibility of the Tool Consumer or Provider as noted below. For an overview of the entire LTI specification and a complete list of related documents, see the LTI Implementation Guide [LTI, 14 IMG] document.
The various interactions are summarized in the following table:
Interaction |
Coverage |
Tool Consumer ←→ End User |
Responsibility of the Tool Consumer |
Tool Provider ←→ End User |
Responsibility of the Tool Provider |
Tool Provider → Tool Consumer Web Services |
LTI Web Service Security Section |
Tool Consumer → Tool Provider direct POST |
LTI Message Security (For Future use – not in LTI 2.0) |
Tool Consumer → Tool Provider POST through End User browser |
LTI Message Security |
Tool Consumer → Tool Provider Web Services |
NOT covered – LTI does not document or require any Tool Provider provided Web Services, but since we have put a placeholder in the Tool Profile to declare services it is important to note the absence of predetermined security |
As there are a number of potential options for each of these interactions, each system will define their supported security profiles via their respective profiles (See security_profile element in each of Tool Profile and Tool Consumer Profile.
During the deployment process, the Tool Provider will determine the best matching set of security options and include these in the POST to the ToolProxy service. (See LTI Security Contract in [LTI, 14 IMG] Section 5.5.)
1.1 Structure of this Document
The structure of this document is:
2 Message Security |
Description of LTI messages and how they are secured |
3. Web Services Security |
Description of the LTI web services and how security services are specified |
1.2 References
[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 MSF] G.McFall, L.Neumann, S.Vickers, 1EdTech Learning Tools Interoperability Messaging Framework v2.0 Final, 1EdTech Consortium, January 2014. http://www.imsglobal.org/lti/
[OAuth, 10] The OAuth 1.0 Protocol, E. Hammer-Lahav. Retrieved 6 January 2014 from http://tools.ietf.org/html/rfc5849
2 Message Security
LTI Message security defines how we secure the POST data between the Tool Consumer and the Tool Provider. This applies both to messages sent directly between the systems as well as to messages sent via the end user’s browser. (In LTI 2.0 there are no message types that are directly sent between systems, thought such messages may be introduced in future releases.)
Refer to the LTI Messaging Framework [LTI, 14 MSF] for the details of the POST itself. This document talks about the security related components applied to that post, specifically the definition and use of the LTISecurityProfile object referenced in that document.
The following table lists the known messaging security profiles.
Table 2.1 Known messaging security profiles.
Profile Name |
lti_oauth_hash_message_security |
This profile depends on a secret that is shared between the Tool Consumer and Tool Provider. For a registered tool (one which has POSTed to the ToolProxy service), this shared secret is set as a system-wide secret which establishes a broad trust relationship between the TP and TC. For non-registered tools (i.e. those supporting just the basic_lti_link), there may be a system-wide secret or a secret that is applied to each individual basic_lti_link being launched. This section does not describe which secret goes with which message.
2.1 lti_oauth_hash_message_security Profile
The OAuth security is a security mechanism designed to protect POST and GET requests. This section only applies to protecting launch and other messages that are being serialized and sent using POST.
The OAuth website [OAuth, 10] contains the specification for OAuth 1.0 and sample source code for implementing OAuth security. OAuth 1.0 specifes how to construct a base message string and then sign that string using the secret. The signature is then sent as part of the POST request and is validated by the Producer using OAuth.
Per the OAuth specification, the signing process produces a number of values that are to be added to the launch request including the oauth_consumer_key:
oauth_consumer_key=b289378-f88d-2929-ctools.umich.edu oauth_signature_method=HMAC-SHA1 oauth_timestamp=1244834250 oauth_nonce=1244834250435893000 oauth_version=1.0 oauth_signature=Xddn2A%2BjzwjgBIVYkvigaKxCdcc%3D oauth_callback=about:blank
|
Figure 2.1 Launch request with oauth_consumer_key.
The important values for signing a message using OAuth are the oauth_consumer_key and oauth_consumer_secret. The oauth_consumer_key is passed in the message as plain text and identifies which consumer (i.e. LMS) is sending the message allowing the producer (i.e. tool provider) to look up the appropriate secret for validation. The oauth_consumer_secret is used to sign the message.
The oauth_callback is really not used in a signing-only scenario (OAuth 1.0 documentation section 6.2.3) so if your OAuth library demands it, you can set it to any value such as "about:blank". Also note that launch_presentation_return_url serve a very different purpose as oauth_callback.
Since we are using OAuth in a signing-only scenario (i.e. we are not using OAuth to transfer third-party identity), there is no need for an oauth_token.
Tool providers must support at a minimum the HMAC-SHA1 signing method with OAuth data passed as POST data.
In order to support as many OAuth client libraries and approaches as possible, tool providers are encouraged to support as many OAuth signature types as possible as well as support receiving OAuth data in headers, in URLas query parameters, or in POST parameters.
Upon receipt of the POST, the Tool Provider will perform the OAuth validation utilizing the shared secret it must have stored locally for the relationship with the Tool Consumer associated with the oauth_consumer_key. The timestamp should also be validated to be within a specific time interval. This time interval can be Tool Provider defined, but should be small (on the order of a few minutes if you do not record nonces or a few hours if you do). It does rely on the time on the Tool Consumer and the Tool Provider being in sync though.
The Tool Provider should keep a record of nonces received and only allow the use of any nonce a single time. Combined with the timestamp, this means that they only have to keep track of nonces for a period of time equal to their acceptable time interval. Recommended practice would be to have a time interval of 90 minutes so that you keep a record of nonces for 90 minutes.
2.1.1 Constructing the oauth_consumer_secret for LTI Launches
Since LTI supports two different and distinct secrets (LMS-wide and resource level) the oauth_consumer_key selected for each launch must be appropriate depending on the scope of the oauth_consumer_secret. When the LMS wide secret is used then the oauth_consumer_key must match the system-wide key set for this tool. When a basic_lti_link has a resource-level oauth_consumer_secret then the resource-level oauth_consumer_key must be used.
3 Web Services Security
LTI defines a set web services that are provided by the Tool Consumer and consumed by the Tool Provider as well as a set provided by the TP and consumed by the TC. Web Services need to be protected from unauthorized access. This section will specify the security aspects related to accessing these Web Services.
The following table lists the known web service security profiles
Table 3.1 Known web service security profiles.
Profile Name |
lti_oauth_body_hash_ws_security |
3.1 lti_oauth_body_hash_ws_security Web Services Security Profile
This profile applies to both the LTI 1.1 “Plain Old XML” (POX) services as well as the LTI 2.0 and newer JSON-LD (REST) services.
For both POX and REST, the messages are signed using OAuth body signing to ensure message integrity and establish the identity of the calling system (ie. the TP). The use of https is recommended for all web service connections because the response data is not signed and therefore the only way to avoid a man-in-the-middle attack is through the use of ssl.
The body of the message is either XML or JSON that follows the schema for the particular requested service operation requested and the message is signed using the oauth_consumer_key and oauth_consumer_secret that was used to do the launch of tool for the particular user/course/resource. In the case of the initial POST to the ToolProxy endpoint, the oauth_consumer_secret used is the temporary one passed from the TC to the TP in the Tool Registration Request.
The procedure for signing a body using OAuth is described on this website:
http://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html
LTI further defines how the OAuth parameters will be used as follows:
· ‘oauth_consumer_key’ : The ‘proxyToolGuid’ obtained by the Tool Provider during the Tool Deployment.
· ‘oauth_signature_method’ : the value of this parameter should be ‘HMAC-SHA1’. It is important that all messages using these services must not use a content type of x-www-form-encoded. The services will legitimately reject any request with this content type as per the OAuth body signing specification which specifically prohibits the combination of oauth_body_hash and x-www-form-encoded data in any request.
Also these services will insist that all of the OAuth parameters are sent as part of the Authorization header. In particular, OAuth parameters from the request URL and POST body will not be processed.
The oauth_body_hash is computed using a SHA-1 hash of the body contents and added to the Authorization header. All of the OAuth parameters, HTTP method, and URL are signed like any other OAuth signed request. Other than in constructing the body hash value, the actual POST data is not involved in the computation of the oauth_signature.
Most OAuth libraries can produce and verify the signatures for these messages as most libraries already support sending OAuth parameters in the Authorization header.
A sample signed request is shown below. The line-breaks in the Authorization header are there to make it easier to read the values. The oauth_signature is not valid for the data below - it is just an example signature.
POST http://www.example.com/ims/lis/Result/sourceidGUID HTTP/1.0 Host: 127.0.0.1 Content-Length: 119 Authorization: OAuth realm="", oauth_version="1.0", oauth_nonce="29f90c047a44b2ece73d00a09364d49b", oauth_timestamp="1313350943", oauth_consumer_key="lmsng.school.edu", oauth_body_hash="v%2BxFnmDSHV%2Fj29qhxLwkFILrtPo%3D", oauth_signature_method="HMAC-SHA1", oauth_signature="8auRpRdPY2KRXUrOyz3HKCs92y8%3D" Content-type: application/vnd.ims.lis.v2.result+json
{ "@context" : "http://purl.imsglobal.org/ctx/lis/v2/Result", "@type" : "Result", "resultScore" : 0.83 }
|
Figure 3.1 A sample signed request.
NOTE that this security profile requires the TC and TP to have synchronized clocks. The use of a configurable time interval can adjust for slightly-off clocks, but setting the interval too large is discouraged.
About This Document
Title: 1EdTech Learning Tools Interoperability Security
Co-chairs: Greg McFall (Pearson), Lance Neumann (Blackboard)
Editor: Greg McFall (Pearson), Lance Neumann (Blackboard), Stephen Vickers (1EdTech)
Version: v2.0
Version Date: 6 January 2014
Status: Final Specification
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
3.2 List of Contributors
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 Security specification for LTI 2. |
v2.0 Final |
6 January 2014 |
Final release of this document as part of the LTI v2 Final specification. |
1EdTech Consortium, Inc. (“1EdTech”) is publishing the information contained in this 1EdTech Learning Tools Interoperability Security (“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 Security v2.0 Final
Revision: 6 January 2014