IMS Final Release

IMS Global Learning Tools Interoperability™ Basic LTI Implementation Guide


Version 1.0 Final

 

Date Issued:            17 May 2010
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.

IMS 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 IMS’s procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf

Copyright © 2010 IMS Global Learning Consortium. All Rights Reserved.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS 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 IMS 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 Basic LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44

 

© 2010 IMS Global Learning Consortium, Inc.
All Rights Reserved.

The IMS Logo and Learning Tools Interoperability (LTI) are trademarks of the IMS Global Learning Consortium, Inc. in the United States and/or other countries.
Document Name: IMS Global Learning Tools Interoperability Basic LTI Implementation Guide Final v1.0
Revision: 17 May 2010


Table of Contents

1           Introduction.. 3

1.1       Structure of this Document .. 4

1.2       References . 4

2           Use Cases for Basic LTI. 6

3           Basic LTI Launch Data.. 9

4           Basic LTI Security Model.. 12

4.1       Basic LTI Credential Management .. 12

4.2       Basic LTI Message Signing .. 12

5           Representing Basic LTI Links in a Cartridge.. 14

6           Using Learning Information Services with Basic LTI. 16

Appendix A – LTI Standard Vocabularies. 17

A.1      ContextType Vocabularies . 17

A.1.1       LIS vocabulary for ContextType. 17

A.2      Role Vocabularies . 17

A.2.1       LIS vocabulary for System Role. 17

A.2.2       LIS vocabulary for Institution Role. 17

A.2.3       LIS vocabulary for Context Role. 18

Appendix B - Implementation Practice.. 20

B.1      Authoring Links with Link-Level Credentials . 20

B.2      Security Policy / SandBoxing Launch Requests . 22

B.3      Roles . 22

B.4      Non-Context LTI Launches . 22

B.5      Basic LTI Sample Launch .. 22

B.6       Conformance .. 23

About This Document.. 24

List of Contributors . 24

Revision History.. 25

 

1         Introduction

IMS is developing Learning Tools Interoperability™ (LTI) to allow remote tools and content to be integrated into a Learning Management System (LMS).  This document brings a subset of that specification forward for standardization.   This document precedes the full IMS LTI v1.0 specification set.

The IMS LTI specification defines two styles of integration:

This document also describes how Basic LTI destinations are described in an IMS Common Cartridge and how they are handled on the import and export of an IMS Common Cartridge.

Figure 1.1: Overview of Basic LTI.

Figure 1.1: Overview of Basic LTI.

Throughout this document, we use specific terminology to describe the two main pieces of software involved in LTI.   What we traditionally think of as the "Learning Management System" (LMS) is referred to as the "Tool Consumer" (TC) as it "consumes" the tool.  The external tool or content is called the "Tool Provider" (TP) as it "provides" the tool for use in the Tool Consumer.   Example Tool Providers might include an externally hosted testing system or a server that contains externally hosted premium content. 

Basic LTI uses the OAuth protocol (http://www.oauth.net) to secure its message interactions between the TC and TP.  OAuth requires a key and shared secret to sign messages.  The key is transmitted with each message, as well as an OAuth-generated signature based on the key.  The TP looks up the secret based on the provided key and re-computes the signature and compares the recomputed signature with the transmitted signature to verify the sender's credentials. 

As a best practice, the TP should isolate data based on the key. The TP must decide exactly how the key is used to isolate data. For example, the TP might maintain a table which maps multiple keys into a single data silo. Or, the TP might arrange to use the same key repeatedly in all cases where data are to belong to the same data silo.

The TC can make choices as to how it manages credentials (keys and secrets) within its system. Basic LTI has three patterns for the credentials: (1) the TC-wide credential for a particular TP domain which is set by the TC administrator and used for all launches to a particular TP domain, or (2) the TC-wide credential for a particular TP URL which is set by the TC administrator and used for all launches to a particular TP URL, or (3) each Basic LTI link is protected by its own credential.  The first and second patterns allow for a more seamless integration between a TC-instance and TP-instance from an instructor’s perspective. The third pattern allows instructors to "mash up" Basic LTI links.

Basic LTI has optional support for the TP to call IMS Learning Information Services (LIS) when those services can be made available to the TP.  Basic LTI does not require LIS services, but the TC can send LIS key information to the TP using values in the Basic LTI Launch Request.

This document uses the term "context" where you might expect to see "course".  A context is roughly equivalent to a course, project, or other collection of resources with a common set of users and roles.  The word "context" is used instead of "course" because a course is only one kind of context (another type of context would be "group").

 

1.1            Structure of this Document

The structure of this document is:

2      Use Cases for Basic LTI

A listing of the use cases describing the core usage scenarios of the Basic LTI specification;

3.     Basic LTI  Launch Data

A description of the data items that are passed as part of the POST data when a Basic LTI launch is performed;

4.     Basic LTI Security Model

The definition of the security environment for Basic LTI launches;

5.     Representing Basic LTI Links in a Cartridge

A description of the Basic LTI link for inclusion in an IMS Common Cartridge;

6.     Using Learning Information Services with Basic LTI

A description of how to use Basic LTI with IMS Learning Information Services;

Appendix A LTI Standard Vocabularies

A reference to the LTI specification’s standard vocabularies;

Appendix B Implementation Practice

A non-normative discussion and recommendations to help guide implementations.

 

1.2            References

As a subset of the LTI v1.0 specification, this document refers to other LTI documents that are not yet published publically, as they are in draft state at the time of the completion of the Basic LTI specification. These LTI documents are listed here but will not be available publically until they also reach completed status.

[CC, 08a]                      IMS Global Common Cartridge v1.0, IMS Global Learning Consortium, K.Riley, October 2008. http://www.imsglobal.org/cc/index.html.

[LIS, 10a]                      IMS Global Learning Information Services Overview v2.0 Public Draft, L.Feng, W.Lee and C.Smythe, IMS Global Learning Consortium, March 2010. http://www.imsglobal.org/lis/index.html.

[LTI, 10 CCI]               IMS Global Learning Tools Interoperability Common Cartridge Interaction v1.0, G.McFall, M.McKell, L.Neumann, IMS Global Learning Consortium, 2010. http://www.imsglobal.org/lti/index.html.

 [LTI, 10 MSS]             IMS Global Learning Tools Interoperability Messages v1.0, G.McFall, M.McKell, L.Neumann, IMS Global Learning Consortium, 2010. http://www.imsglobal.org/lti/index.html.

 [LTI, 10 TMT]            IMS Global Learning Tools Interoperability Tool Management v1.0, G.McFall, M.McKell, L.Neumann, IMS Global Learning Consortium, 2010. http://www.imsglobal.org/lti/index.html.

 

2         Use Cases for Basic LTI

This section is taken verbatim from the LTI Tool Management [LTI, 10, TMT] documentation.

 

Title:

Setting TP Domain Credentials (Basic LTI)

Use Case Local ID:

LTIv1-12

Description:

The TC administrator configures TP domain credentials for a particular TP.

Actors:

  • TC Administrator
  • TP Administrator

Preconditions:

None

Basic Flow of Events:

1.       The TP Administrator creates the key and secret combination for the TC (where the TC administrator may request a particular key, often the TC domain name).

2.       The TC Administrator obtains the key and secret from the TP administrator.

3.       The TC Administrator installs the key and secret and associates them with launches destined for the TP’s domain using a TC-provided dialog or configuration mechanism.

Alternate Path

A.      In step 3, the key and secret combination may be designated to apply to a particular TP URL instead of all URLs destined for the TP’s domain.

 

 

Title:

Setting Link Level Credentials (Basic LTI)

Use Case Local ID:

LTIv1-13

Description:

An instructor authors a Basic LTI link and sets the key/password for that link.

Actors:

  • Instructor
  • Tool Provider (TP)

Preconditions:

None

Basic Flow of Events:

1.       The Instructor contacts the TP and gains access to a provider tool or content.

2.       The TP provides the Instructor with (1) a Basic LTI launch URL or XML snippet for the content or tool, (2) a key used to access this content/tool, and (3) a secret associated with the key.

3.       The Instructor enters the three values (URL or XML snippet, Key, Secret) into a Basic LTI authoring dialog in the TC system.

 

 

Title:

Launching an Authored Basic LTI Link from a Context

Use Case Local ID:

LTIv1-14

Description:

A non-Instructor user selects a Basic LTI link from a context in the TC.

Actors:

  • TC User

Preconditions:

An Instructor has properly authored or imported a Basic LTI Link and there are appropriate credentials in place.

Basic Flow of Events:

  1. The TC User clicks on the link in the TC UI.
  2. The tool or content from the TP appears in the TC UI.  If JavaScript is turned off – the TC User will need to click on a "continue" button to send the POST data to the TP.

 

 

Title:

Launching Basic LTI Imported from a Cartridge (with secret)

Use Case Local ID:

LTIv1-15

Description:

An Instructor imports a Common Cartridge containing Basic LTI link descriptors into their context and users use the content.

Actors:

  • Cartridge Creator
  • Instructor
  • TC User

Preconditions:

The TC Administrator has received and installed the appropriate credentials for the particular TP(s) that are referenced in the cartridge.

Basic Flow of Events:

1.       The Cartridge Creator authors a cartridge and includes one or more Basic LTI link descriptors in the cartridge. The Basic LTI link descriptors in the cartridge contain a launch URL(s) and other data but do not contain keys or secrets.

2.       The Instructor obtains the Common Cartridge and imports it into their context in the TC system.

3.       When a TC User launches the Basic LTI link imported from the Common Cartridge, the TC uses the pre-configured credentials associated with the TP domain or URLs.

4.       In particular, as long as the TC-wide credentials are already installed, the Instructor does not need to take any further action to launch the content beyond importing a cartridge.

Alternate Path

A.      If the preconditions are not satisfied, it is also possible to set the credentials after the cartridge import has taken place. If a launch occurs before credentials have been defined, it is the responsibility of the TP to notify the user that credentials are required.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Title:

Launching Basic LTI Imported from a Cartridge (no secret)

Use Case Local ID:

LTIv1-16

Description:

An Instructor imports a Common Cartridge containing Basic LTI link descriptors into their context and users use the content.  Note that this scenario is optional – the TC and/or TP may decide that Basic LTI launches without secrets are treated as an error.

Actors:

  • Cartridge Creator
  • Instructor
  • TC User

Preconditions:

None.

Basic Flow of Events:

1.       The Cartridge Creator authors a cartridge and includes one or more Basic LTI link descriptors in the cartridge. The Basic LTI link descriptors in the cartridge contain a launch URL(s) and other data but do not contain keys or secrets.

2.       The Instructor obtains the Common Cartridge and imports it into their context in the TC system.

3.       When a TC User launches the Basic LTI link from the Common Cartridge, the TC launches the Basic LTI link with no authentication or signature information.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

3         Basic LTI Launch Data

This section describes the data items that are passed as part of the POST data when a Basic LTI launch is performed.  Very few of the fields are technically required as each Tool Provider may have different requirements.  Some TPs may see the fields in the launch as information to be gathered for tracking and others may need highly detailed and precise information to perform high-stakes activities and reliably and securely return high-stakes results from those activities.

TC systems should provide as much data as possible in each launch to maximize the chance that the TP will have the data it needs to function properly.   TC systems may have sandboxing features that limit the sending of certain Basic LTI data elements only to "approved" TPs.  It is outside the scope of the document to define the nature of the TC sandboxing of Basic LTI launches.  TPs should be prepared to work with partial information – either because the TC does not have the information or the TC has been configured not to share the information with the TP.

If a profile wants to extend these fields, they should prefix all fields not described herein with "ext_".

The normative text in this section was taken from the LTI Messages [LTI, 10 MSS]documentation.
 

lti_message_type=basic-lti-launch-request
This indicates that this is a Basic LTI Launch Message.  This allows a TP to accept a number of different LTI message types at the same launch URL.  This parameter is required.

lti_version=LTI-1p0
This indicates which version of the specification is being used for this particular message.  This parameter is required.

resource_link_id=88391-e1919-bb3456
This is an opaque unique identifier that the TC guarantees will be unique within the TC for every placement of the link.   If the tool / activity is placed multiple times in the same context, each of those placements will be distinct. This value will also change if the item is exported from one system or context and imported into another system or context.  This parameter is required.

resource_link_title=My Weekly Wiki
A title for the resource. This is the clickable text that appears in the link. This parameter is recommended.

resource_link_description=…
A plain text description of the link’s destination, suitable for display alongside the link. Typically no more than several lines long. This parameter is optional.

user_id=0ae836b9-7fc9-4060-006f-27b2066ac545
Uniquely identifies the user.  This should not contain any identifying information for the user.  Best practice is that this field should be a TC-generated long-term “primary key” to the user record – not the “logical key".  This parameter is recommended.

user_image=http://....
This attribute specifies the URI for an image of the user who launched this request.  This image is suitable for use as a "profile picture" or an avatar representing the user.  This parameter is optional.

 

roles=Instructor
A comma-separated list of URN values for roles.  If this list is non-empty, it should contain at least one role from the LIS System Role, LIS Institution Role, or LIS Context Role vocabularies (See Appendix A).  The assumed namespace of these URNs is the LIS vocabulary of LIS Context Roles so TCs can use the handles when the intent is to refer to an LIS context role.  If the TC wants to include a role from another namespace, a fully-qualified URN should be used.  Usage of roles from non-LIS vocabularies is discouraged as it may limit interoperability.   This parameter is recommended.

 

lis_person_name_given=Jane
lis_person_name_family=Public
lis_person_name_full=Jane Q. Public
lis_person_contact_email_primary=user@school.edu
These fields contain information about the user account that is performing this launch.  The names of these data items are taken from LIS.  The precise meaning of the content in these fields is defined by LIS. These parameters are recommended unless they are suppressed because of privacy settings.

 

context_id=8213060-006f-27b2066ac545
This is an opaque identifier that uniquely identifies the context that contains the link being launched. This parameter is recommended.

context_type=CourseSection
This string is a comma-separated list of URN values that identify the type of context.  At a minimum, the list MUST include a URN value drawn from the LIS vocabulary (see Appendix A). The assumed namespace of these URNs is the LIS vocabulary so TCs can use the handles when the intent is to refer to an LIS context type.  If the TC wants to include a context type from another namespace, a fully-qualified URN should be used. This parameter is optional.

context_title=Design of Personal Environments
A title of the context – it should be about the length of a line. This parameter is recommended.

context_label=SI182
A label for the context – intended to fit in a column. This parameter is recommended.

launch_presentation_locale=en-US
Language, country and variant as represented using the IETF Best Practices for Tags for Identifying Languages (BCP-47) available at http://www.rfc-editor.org/rfc/bcp/bcp47.txt

launch_presentation_document_target=iframe
The value should be either ‘frame’, ‘iframe’ or ‘window’.  This field communicates the kind of browser window/frame where the TC has launched the tool. This parameter is recommended.

 

launch_presentation_width=320
The width of the window or frame where the content from the tool will be displayed. This parameter is recommended.

 

launch_presentation_height=240
The height of the window or frame where the content from the tool will be displayed. This parameter is recommended.

 

launch_presentation_return_url=http://lmsng.school.edu/portal/123/page/988/
Fully qualified URL where the TP can redirect the user back to the TC interface.  This URL can be used once the TP is finished or if the TP cannot start or has some technical difficulty.  In the case of an error, the TP may add a parameter called lti_errormsg that includes some detail as to the nature of the error.  The lti_errormsg value should make sense if displayed to the user.  If the tool has displayed a message to the end user and only wants to give the TC a message to log, use the parameter lti_errorlog instead of lti_errormsg. If the tool is terminating normally, and wants a message displayed to the user it can include a text message as the lti_msg parameter to the return URL. If the tool is terminating normally and wants to give the TC a message to log, use the parameter lti_log. This data should be sent on the URL as a GET – so the TP should take care to keep the overall length of the parameters small enough to fit within the limitations of a GET request. This parameter is recommended.

tool_consumer_instance_guid=lmsng.school.edu
This is a unique identifier for the TC.  A common practice is to use the DNS of the organization or the DNS of the TC instance.  If the organization has multiple TC instances, then the best practice is to prefix the domain name with a locally unique identifier for the TC instance.  This parameter is recommended.

tool_consumer_instance_name=SchoolU
This is a user visible field – it should be about the length of a column. This parameter is recommended.

tool_consumer_instance_description=University of School (LMSng)
This is a user visible field – it should be about the length of a line. This parameter is optional.

tool_consumer_instance_url=http://lmsng.school.edu
This is the URL of the consumer instance.  This parameter is optional.

 

tool_consumer_instance_contact_email=System.Admin@school.edu
An email contact for the TC instance. This parameter is recommended.

 

custom_keyname=value
The creator of a Basic LTI link can add custom key/value parameters to a launch which are to be included with the launch of the Basic LTI link. The Common Cartridge section below describes how these parameters are represented when storing custom parameters in a Common Cartridge. 

When there are custom name / value parameters in the launch, a POST parameter is included for each custom parameter.  The parameter names are mapped to lower case and any character that is neither a number nor letter in a parameter name is replaced with an "underscore".  So if a custom entry was as follows:

Review:Chapter=1.2.56

Would map to:

      custom_review_chapter=1.2.56

Creators of Basic LTI links would be well served to limit their parameter names to lower case and to use no punctuation other than underscores.

If these custom parameters are included in the Basic LTI link, the TC must include them in the launch data or the TP may fail to function.

In addition to these data items for the Basic LTI launch, the next section describes additional security parameters which are to be included with the launch.

4         Basic LTI Security Model

4.1       Basic LTI Credential Management

This section is taken from the LTI Tool Management [LTI, 10 TMT] documentation.

The security environment for Basic LTI launches must be set up using out-of-band interactions between the TP administrator and either the TC administrator or an instructor who will be authoring a Basic LTI link.

There are three possible credentials (keys and secrets) associated with a particular Basic LTI launch, listed in precedence order where TP domain credentials have the highest precedence.

•              Credentials associated with a TP domain.  These credentials authorize access to all TP URLs from the TC. Once the TP domain credentials are established for a TP, all Basic LTI tool launches to the TP will use this same secret.  Using TP domain credentials gives TPs the option of trusting user information and context information across multiple contexts within a particular TC instance as being maintained properly by the TC.

In order to select which TP domain credentials are used for a particular LTI link, the TC examines the domain name in the launch URL for the LTI link. The TP domain credentials are looked up after scanning the domain name of the launch URL.  So for example, if the launch URL was:

http://launch.math.vendor.com/launch.php

The TC would prefer the following TP domain credentials in order from specific to general: launch.math.vendor.com , math.vendor.com, and then vendor.com.  So when TPs are generating link URLs and giving them to an instructor or embedding those links in a cartridge, it is important to use consistent domain names in those launch URLs so as to be able to match a TP domain credentials for a particular TP with the appropriate launches.

•              Credentials associated with a TP URL. These credentials authorize access to a particular TP URL from the TC. These are typically used when the administrator is enabling a remote tool within the TC with a preset configuration which can be added to a context by the instructor with little or no further configuration.

•              Credentials associated with a particular link.  These credentials authorize access to the resource at the URL specified by the link. These credentials are typically entered by the instructor at the moment that the link is created in the context.

Basic LTI launches can happen from the TC with any combination of credentials. When more than one is present, the TC uses the highest precedent credentials to sign the request.

If there are no credentials available for this launch and the TC wants to perform the launch, the TC should not sign the launch data using OAuth.  The TC can decide if it wants to send unsigned requests and the TP can decide if it wants to accept unsigned requests.  A TC may also choose to treat the lack of credentials as an error and refuse to perform the launch.

 

4.2       Basic LTI Message Signing

Note: This section is taken verbatim the LTI Messages documentation.

OAuth is a security mechanism designed to protect POST and GET requests.  This section only applies to protecting launch and other LTI messages that are being serialized and sent using POST.

The site http://www.oauth.net contains the specification for OAuth 1.0 and sample source code for implementing OAuth security.  OAuth 1.0 specifies 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 TP using OAuth.

Per the OAuth specification, the signing process produces a number of values that are to be added to the launch request:

oauth_consumer_key=b289378-f88d-2929-lmsng.school.edu

oauth_signature_method=HMAC-SHA1

oauth_timestamp=1244834250

oauth_nonce=1244834250435893000

oauth_version=1.0

oauth_signature=Xddn2A%2BjzwjgBIVYkvigaKxCdcc%3D

 

The important values for signing a message using OAuth are the oauth_consumer_key and oauth_consumer_secret. The value of the oauth_consumer_key depends on which credentials are being used. 

The oauth_consumer_key is passed in the message as plain text and identifies which TC is sending the message allowing the TP to look up the appropriate secret for validation.  The oauth_consumer_secret is used to sign the message.

TC and TP must support and use the HMAC-SHA1 signing method with OAuth fields coming from POST parameters.

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 as per OAuth 1.0 documentation section 6.2.3 Since most of the OAuth implementations in the marketplace have upgraded to OAuth 1.0A, Tool Consumers should include oauth_callback  and set it to a value such as "about:blank".  Note that Basic LTI's launch_presentation_return_url serves a very different purpose than OAuth's oauth_callback.

Upon receipt of the POST, the TP will perform the OAuth validation utilizing the shared secret it has stored for the oauth_consumer_key.  The timestamp should also be validated to be within a specific time interval.  This time interval can be TP 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).

The TP 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. 

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.

5         Representing Basic LTI Links in a Cartridge

Note: This section is taken from the LTI Common Cartridge Interaction [LTI, 10 CCI] documentation.

A Basic LTI link is a simplified and self-contained LTI link. The Basic LTI link is defined in the resource section of an IMS Common Cartridge as follows:

 

       <resource identifier="I_00010_R" type="imsbasiclti_xmlv1p0">

              <file href="I_00001_R/BasicLTI.xml"/>

       </resource>

The href in the resource entry refers to a file path in the cartridge that contains an XML description of the Basic LTI link.

 

<?xml version="1.0" encoding="UTF-8"?>

<cartridge_basiclti_link xmlns="http://www.imsglobal.org/xsd/imslticc_v1p0"

    xmlns:blti = "http://www.imsglobal.org/xsd/imsbasiclti_v1p0"

    xmlns:lticm ="http://www.imsglobal.org/xsd/imslticm_v1p0"

    xmlns:lticp ="http://www.imsglobal.org/xsd/imslticp_v1p0"

    xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation = "http://www.imsglobal.org/xsd/imslticc_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticc_v1p0.xsd

                          http://www.imsglobal.org/xsd/imsbasiclti_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imsbasiclti_v1p0.xsd

                          http://www.imsglobal.org/xsd/imslticm_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticm_v1p0.xsd

                          http://www.imsglobal.org/xsd/imslticp_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticp_v1p0.xsd">

    <blti:title>Grade Book</blti:title>

    <blti:description>Grade Book with many column types</blti:description>

    <blti:custom>

        <lticm:property name="keyname">value</lticm:property>

    </blti:custom>

    <blti:extensions platform="my.lms.com">

        <lticm:property name="keyname">value</lticm:property>

    </blti:extensions>

    <blti:launch_url>url to the basiclti launch URL</blti:launch_url>

    <blti:secure_launch_url>secure url to the basiclti launch URL</blti:secure_launch_url>

    <blti:icon>url to an icon for this tool (optional)</blti:icon>

    <blti:secure_icon>secure url to an icon for this tool (optional)></blti:secure_icon>

    <blti:vendor>

        <lticp:code>vendor.com</lticp:code>

        <lticp:name>vendor.name</lticp:name>

        <lticp:description>This is a vendor of learning tools.</lticp:description>

        <lticp:url>http://www.vendor.com/</lticp:url>

        <lticp:contact>

            <lticp:email>support@vendor.com</lticp:email>

        </lticp:contact>

    </blti:vendor>

    <cartridge_bundle identifierref="BLTI001_Bundle"/>

    <cartridge_icon identifierref="BLTI001_Icon"/>

</cartridge_basiclti_link>

 

The launch_url contains the URL to which the LTI Launch is to be sent.   The secure_launch_url is the URL to use if secure http is required.  One of either the launch_url or the secure_launch_url must be specified. It is acceptable to specify both and if both are specified, the TC decides which to use. Typically, the TC will use a secure_launch_url when embedding the Tool in a secure page and the launch_url when embedding the tool in a non-secure page. So, it’s important that the TP provides the same functionality whether the launch_url or secure_launch_url is used.

 

The icon and secure_icon are both optional and indicate a URL to be used for an icon to the tool.

Once the Basic LTI link is defined in the resources section of the cartridge manifest, it can be referenced in the organization section of the manifest as needed:

 

            <item identifier="BasicLTI1" identifierref="I_00010_R">

              <title>Homework Problems</title>

       </item>

 

The TC will generally display the title in the item entry in the user interface rather than title in the basic_lti_link entry.

The optional custom section can contain a set of key value pairs that were placed in the link in the system that originally authored the link.  For example if the link were a section in an eTextbook, there might be a setting like:

 

<parameter key="section">1.2.7</parameter>

These parameters are sent back to the external tool when the tool is launched.  If Basic LTI link is imported and then exported the custom should be maintained across the import/export process unless the intent is to re-author the link.

The extensions section allows the hosting TC to add its own key/value pairs to the link. The TC may use extensions to store information that the TC or authoring environment might use across an export-import cycle.  In order to allow multiple sets of extensions to be contained in the same Basic LTI descriptor, authoring environments should add the platform attribute and include an identifier that identifies the authoring environment.

It is possible to include the icon for the link in the cartridge instead of including it as a URL using the cartridge_icon entry in the descriptor.  The identifierref attribute points to a link that includes the icon image and a dependency is added to the resource section of the Basic LTI resource entry in the manifest as shown below.

 

       <resource identifier="I_00010_R" type="imsbasiclti_xmlv1p0">

              <file href="I_00001_R/BasicLTI.xml"/>

<dependency identifierref="BLTI001_Icon"/>

       </resource>

 

<resource identifier="BLTI001_Icon"

type="associatedcontent/imscc_xmlv1p0/learning-application-resource">

              <file href="BLTI001_Media/learning_icon.gif"/>

       </resource>

 

6         Using Learning Information Services with Basic LTI

Basic LTI does not provide support for Full LTI run-time services. However, if a Tool Consumer (TC) and Tool Provider (TP) have access to a common set of IMS Learning Information Services (LIS) [LIS, 10a], a Basic LTI launch can provide information to the TP that could be used by the TP to call LIS services.

 

Figure 6.1 The TP taking advantage of LIS services.

Figure 6.1 The TP taking advantage of LIS services.

 

The LIS services could be provided by a third system such as a Student Information System, or perhaps the TC system is the provider of the LIS services to be used by the TP.

Any and all arrangements between the TP and the LIS services surrounding the use of these identifiers passed in a Basic LTI launch request are defined by the IMS LIS specification.  Basic LTI simply communicates identifiers to be used when calling LIS services if those services and identifiers are available.  These additional parameters are optional.  The TC does not have to include these parameters and the TP can ignore these parameters if present.

 

lis_person_sourcedid=school.edu:user
This field contains the LIS identifier for the user account that is performing this launch.    The example syntax of "school:user" is not the required format – lis_person_sourcedid is simply a globally unique identifier (i.e., a normalized string). This field is optional and its content and meaning are defined by LIS.   

 

lis_course_offering_sourcedid=school.edu:SI182-F08

lis_course_section_sourcedid=school.edu:SI182-001-F08

These fields contain LIS course identifiers associated with the context of this launch.  These fields are optional and their content and meaning are defined by LIS.

 

lis_result_sourcedid=83873872987329873264783687634
This field contains an identifier that indicates the LIS Result Identifier (if any) associated with this launch. This field is optional and its content and meaning is defined by LIS.   

 

Basic LTI does not address any issues regarding provisioning, discovery, or security arrangements between the TP and the LIS services – these are all out of band arrangements.  The values provided by Basic LTI can be used when using LIS services after the arrangements have been made between the LIS and TP systems.

Appendix A – LTI Standard Vocabularies

This Appendix is taken verbatim from the LTI Messages [LTI, 10 MSS] documentation.

The LTI v1.0 specification uses URN values to identify certain entities. This section contains URN vocabularies for ContextType and Role values.

 

A.1    ContextType Vocabularies

A.1.1      LIS vocabulary for ContextType

Handle

Full URN

CourseTemplate

urn:lti:context-type:ims/lis/CourseTemplate

CourseOffering

urn:lti:context-type:ims/lis/CourseOffering

CourseSection

urn:lti:context-type:ims/lis/CourseSection

Group

urn:lti:context-type:ims/lis/Group

A.2    Role Vocabularies

A.2.1      LIS vocabulary for System Role

The following table lists URN values for system role as defined by the LIS standard.

Handle

Full URN

SysAdmin

urn:lti:sysrole:ims/lis/SysAdmin

SysSupport

urn:lti:sysrole:ims/lis/SysSupport

Creator

urn:lti:sysrole:ims/lis/Creator

AccountAdmin

urn:lti:sysrole:ims/lis/AccountAdmin

User

urn:lti:sysrole:ims/lis/User

Administrator

urn:lti:sysrole:ims/lis/Administrator

None

urn:lti:sysrole:ims/lis/None

 

A.2.2      LIS vocabulary for Institution Role

The following table lists URN values for institution roles as defined by the LIS standard

Handle

Full URN

Student

urn:lti:instrole:ims/lis/Student

Faculty

urn:lti:instrole:ims/lis/Faculty

Member

urn:lti:instrole:ims/lis/Member

Learner

urn:lti:instrole:ims/lis/Learner

Instructor

urn:lti:instrole:ims/lis/Instructor

Mentor

urn:lti:instrole:ims/lis/Mentor

Staff

urn:lti:instrole:ims/lis/Staff

Alumni

urn:lti:instrole:ims/lis/Alumni

ProspectiveStudent

urn:lti:instrole:ims/lis/ProspectiveStudent

Guest

urn:lti:instrole:ims/lis/Guest

Other

urn:lti:instrole:ims/lis/Other

Administrator

urn:lti:instrole:ims/lis/Administrator

Observer

urn:lti:instrole:ims/lis/Observer

None

urn:lti:instrole:ims/lis/None

 

A.2.3      LIS vocabulary for Context Role

Roles within the LIS standard [LIS, 10a] consist of a  RoleType and an optional SubRoleType.  The handle for the corresponding URN value contains both elements, separated by a slash. 

Handle

Full URN

Learner

urn:lti:role:ims/lis/Learner

Learner/Learner

urn:lti:role:ims/lis/Learner/Learner

Learner/NonCreditLearner

urn:lti:role:ims/lis/Learner/
NonCreditLearner

Learner/GuestLearner

urn:lti:role:ims/lis/Learner/
GuestLearner

Learner/ExternalLearner

urn:lti:role:ims/lis/Learner/
ExternalLearner

Learner/Instructor

urn:lti:role:ims/lis/Learner/Instructor

Instructor

urn:lti:role:ims/lis/Instructor

Instructor/PrimaryInstructor

urn:lti:role:ims/lis/Instructor/PrimaryInstructor

Instructor/Lecturer

urn:lti:role:ims/lis/Instructor/Lecturer

Instructor/GuestInstructor

urn:lti:role:ims/lis/Instructor/
GuestInstructor

Instructor/ExternalInstructor

urn:lti:role:ims/lis/Instructor/
ExternalInstructor

ContentDeveloper

urn:lti:role:ims/lis/ContentDeveloper

ContentDeveloper/ContentDeveloper

urn:lti:role:ims/lis/ContentDeveloper/
ContentDeveloper

ContentDeveloper/Librarian

urn:lti:role:ims/lis/ContentDeveloper/Librarian

ContentDeveloper/ContentExpert

urn:lti:role:ims/lis/ContentDeveloper/ContentExpert

ContentDeveloper/ExternalContentExpert

urn:lti:role:ims/lis/ContentDeveloper/
ExternalContentExpert

Member

urn:lti:role:ims/lis/Member

Member/Member

urn:lti:role:ims/lis/Member/Member

Manager

urn:lti:role:ims/lis/Manager

Manager/AreaManager

urn:lti:role:ims/lis/Manager/AreaManager

Manager/CourseCoordinator

urn:lti:role:ims/lis/Manager/CourseCoordinator

Manager/Observer

urn:lti:role:ims/lis/Manager/Observer

Manager/ExternalObserver

urn:lti:role:ims/lis/Manager/ExternalObserver

Mentor

urn:lti:role:ims/lis/Mentor

Mentor/Mentor

urn:lti:role:ims/lis/Mentor/Mentor

Mentor/Reviewer

urn:lti:role:ims/lis/Mentor/Reviewer

Mentor/Advisor

urn:lti:role:ims/lis/Mentor/Advisor

Mentor/Auditor

urn:lti:role:ims/lis/Mentor/Auditor

Mentor/Tutor

urn:lti:role:ims/lis/Mentor/Tutor

Mentor/LearningFacilitator

urn:lti:role:ims/lis/Mentor/LearningFacilitator

Mentor/ExternalMentor

urn:lti:role:ims/lis/Mentor/ExternalMentor

Mentor/ExternalReviewer

urn:lti:role:ims/lis/Mentor/ExternalReviewer

Mentor/ExternalAdvisor

urn:lti:role:ims/lis/Mentor/ExternalAdvisor

Mentor/ExternalAuditor

urn:lti:role:ims/lis/Mentor/ExternalAuditor

Mentor/ExternalTutor

urn:lti:role:ims/lis/Mentor/ExternalTutor

Mentor/ExternalLearningFacilitator

urn:lti:role:ims/lis/Mentor/
ExternalLearningFacilitator

Administrator

urn:lti:role:ims/lis/Administrator

Administrator/Administrator

urn:lti:role:ims/lis/Administrator/Administrator

Administrator/Support

urn:lti:role:ims/lis/Administrator/Support

Administrator/Developer

urn:lti:role:ims/lis/Administrator/ExternalDeveloper

Administrator/SystemAdministrator

urn:lti:role:ims/lis/Administrator/SystemAdministrator

Administrator/ExternalSystemAdministrator

urn:lti:role:ims/lis/Administrator/
ExternalSystemAdministrator

Administrator/ExternalDeveloper

urn:lti:role:ims/lis/Administrator/ExternalDeveloper

Administrator/ExternalSupport

urn:lti:role:ims/lis/Administrator/ExternalSupport

TeachingAssistant

urn:lti:role:ims/lis/TeachingAssistant

TeachingAssistant/TeachingAssistant

urn:lti:role:ims/lis/TeachingAssistant/
TeachingAssistant

TeachingAssistant/TeachingAssistantSection

urn:lti:role:ims/lis/TeachingAssistant/
TeachingAssistantSection

TeachingAssistant/
TeachingAssistantSectionAssociation

urn:lti:role:ims/lis/TeachingAssistant/
TeachingAssistantSectionAssociation

TeachingAssistant/
TeachingAssistantOffering

urn:lti:role:ims/lis/TeachingAssistant/
TeachingAssistantOffering

TeachingAssistant/
TeachingAssistantTemplate

urn:lti:role:ims/lis/TeachingAssistant/
TeachingAssistantTemplate

TeachingAssistant/TeachingAssistantGroup

urn:lti:role:ims/lis/TeachingAssistant/
TeachingAssistantGroup

TeachingAssistant/Grader

urn:lti:role:ims/lis/TeachingAssistant/Grader

Appendix B - Implementation Practice

This section includes non-normative discussion and recommendations to help guide implementations.

B.1    Authoring Links with Link-Level Credentials

If the TC chooses to support link-level credentials, they are supporting the ability for the Instructor to author Basic LTI links inside of the TC.  The minimal authoring screen is very simple. 

Figure B.2 Authoring screen for Basic LTI links inside of the TC. .

Figure B.2 Authoring screen for Basic LTI links inside of the TC.

 


Another possible authoring interface might be to allow the pasting of the XML basic_lti_link descriptor into an input field.


Text Box: <?xml version="1.0" encoding="UTF-8"?>
 <basic_lti_link xmlns="http://www.imsglobal.org/xsd/imsbasiclti_v1p0"
  xmlns:lticm ="http://www.imsglobal.org/xsd/imslticm_v1p0"
  xmlns:lticp ="http://www.imsglobal.org/xsd/imslticp_v1p0"
  xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation = "http://www.imsglobal.org/xsd/imsbasiclti_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imsbasiclti_v1p0.xsd 
  http://www.imsglobal.org/xsd/imslticm_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticm_v1p0.xsd 
  http://www.imsglobal.org/xsd/imslticp_v1p0 http://www.imsglobal.org/xsd/lti/ltiv1p0/imslticp_v1p0.xsd">
  <title>Grade Book</title>
  <description>Grade Book with many column types</description>
  <custom>
  <lticm:property name="keyname">value</lticm:property>
  </custom>
  <extensions platform="my.lms.com">
  <lticm:property name="keyname">value</lticm:property>
  </extensions>
  <launch_url>url to the basiclti launch URL</launch_url>
  <secure_launch_url>secure url to the basiclti launch URL</secure_launch_url>
  <icon>url to an icon for this tool (optional)</icon>
  <secure_icon>secure url to an icon for this tool (optional)></secure_icon> 
  <vendor>
  <lticp:code>vendor.com</lticp:code>
  <lticp:name>vendor.name</lticp:name>
  <lticp:description>This is a vendor of learning tools.</lticp:description>
  <lticp:url>http://www.vendor.com/</lticp:url>
  <lticp:contact>
  <lticp:email>support@vendor.com</lticp:email>
  </lticp:contact>
  </vendor>
 </basic_lti_link>

Figure B.3 Sample pasting of a Basic LTI link in XML.

 

As a best practice, TC systems should support both the URL/Key/Secret and XML/Key/Secret of authoring a Basic LTI link. The user interface for these options and how and where these options are shown to the user is up to the TC.

The TC might add other features like frame height, "open in new window" or add a title field to the link entry.

Figure B.4 Sample interface for including various options inside the TC.

Figure B.4 Sample interface for including various options inside the TC.

 

These screens will be available in the TC where the Instructor is creating the course organization and adding a new link.  A typical approach is to make creating a Basic LTI launch just one more type of TC link in the course structure.

B.2    Security Policy / SandBoxing Launch Requests

TC systems will likely implement a number of security policy related features that can be controlled by both the TC administrator and the Instructor.  These are some considerations:

It is out of the scope of this document to specify how the TC system controls which instructors can author Basic LTI links or which URLs can be launched using Basic LTI or which data is shared with particular TPs.

B.3    Roles

Some of the commonly used roles from LIS include Learner, Instructor, Administrator, TeachingAssistant, ContentDeveloper, and Mentor.  Multiple roles can be included, separated by commas.  TC systems should include as many roles as appropriate for the user (i.e., more roles are better).  TC systems should be aware that simple TPs will key off the presence or absence of the Instructor role and group users into those with the Instructor role (read-write-configure) and those without the Instructor role (read).

 

B.4    Non-Context LTI Launches

While the typical use of a Basic LTI link is in a context, it is also possible to use Basic LTI to launch a link that is not part of a context.  One example of a non-context launch might be a menu item that is part of the portal or part of a global menu in the TC.

Supporting non-context launches is optional for both the TP and TC.

If a Basic LTI launch is coming from a non-context placement, the context information is simply omitted and the launch will contain the user and organization information but no context information.

B.5    Basic LTI Sample Launch

The Basic LTI launch protocol is a POST to the launch URL with the Basic LTI parameters described above, properly signed using OAuth. 

The most common launch approach will be for the TC to emit a form to the browser and then include code to automatically submit the form to the launch URL.  The TP will assume that it is in a browser, process the input parameters, setting session information if necessary and optionally redirecting.

Here is a sample of an HTML form using a password of "secret" and oauth_consumer_key of "12345".

<div id="ltiLaunchFormSubmitArea">

<form action="http://dr-chuck.com/ims/php-simple/tool.php"

    name="ltiLaunchForm" id="ltiLaunchForm" method="post"

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

<input type="hidden" name="oauth_version" value="1.0"/>

<input type="hidden" name="oauth_nonce" value="c8350c0e47782d16d2fa48b2090c1d8f"/>

<input type="hidden" name="oauth_timestamp" value="1251600739"/>

<input type="hidden" name="oauth_consumer_key" value="12345"/>

<input type="hidden" name="resource_link_id" value="120988f929-274612"/>

<input type="hidden" name="user_id" value="292832126"/>

<input type="hidden" name="roles" value="Instructor"/>

<input type="hidden" name="lis_person_name_full" value="Jane Q. Public"/>

<input type="hidden" name="lis_person_contact_email_primary" value="user@school.edu"/>

<input type="hidden" name="lis_person_sourced_id" value="school.edu:user"/>

<input type="hidden" name="context_id" value="456434513"/>

<input type="hidden" name="context_title" value="Design of Personal Environments"/>

<input type="hidden" name="context_label" value="SI182"/>

<input type="hidden" name="lti_version" value="LTI-1p0"/>

<input type="hidden" name="lti_message_type" value="basic-lti-launch-request"/>

<input type="hidden" name="tool_consumer_instance_guid" value="lmsng.school.edu"/>

<input type="hidden" name="tool_consumer_instance_description"

    value="University of School (LMSng)"/>

<input type="submit" name="basiclti_submit" value="Launch Endpoint with BasicLTI Data"/>

<input type="hidden" name="oauth_signature_method" value="HMAC-SHA1"/>

<input type="hidden" name="oauth_callback" value="about:blank"/>

<input type="hidden" name="oauth_signature" value="TPFPK4u3NwmtLt0nDMP1G1zG30U="/>

</form>

</div>

<script language="javascript">

    document.getElementById("ltiLaunchFormSubmitArea").style.display = "none";

    nei = document.createElement('input');

    nei.setAttribute('type', 'hidden');

    nei.setAttribute('name', 'basiclti_submit');

    nei.setAttribute('value', 'Press to continue to external tool.');

    document.getElementById("ltiLaunchForm").appendChild(nei);

    document.ltiLaunchForm.submit();

 </script>

 

This form is designed to work even if JavaScript is turned off in the browser – the user simply presses the submit button.  If JavaScript is on, the button is quickly hidden and the form is automatically submitted. 

The JavaScript must add a hidden field to the form when it is auto-submitting the form because the submit value was included in the OAuth base string and signature computation.

The following is the base string prior to the OAuth signature computation:

 

POST&http%3A%2F%2Fdr-chuck.com%2Fims%2Fphp-simple%2Ftool.php&basiclti_submit%3DLaunch%2520Endpoint%2520with%2520BasicLTI%2520Data%26context_id%3D456434513%26context_label%3DSI182%26context_title%3DDesign%2520of%2520Personal%2520Environments%26lis_person_contact_email_primary%3Duser%2540school.edu%26lis_person_name_full%3DJane%2520Q.%2520Public%26lis_person_sourced_id%3Dschool.edu%253Auser%26lti_message_type%3Dbasic-lti-launch-request%26lti_version%3DLTI-1p0%26oauth_consumer_key%3D12345%26oauth_nonce%3Dc8350c0e47782d16d2fa48b2090c1d8f%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1251600739%26oauth_version%3D1.0%26resource_link_id%3D120988f929-274612%26roles%3DInstructor%26tool_consumer_instance_description%3DUniversity%2520of%2520School%2520%2528LMSng%2529%26tool_consumer_instance_guid%3Dlmsng.school.edu%26user_id%3D292832126

 

In the above string, all line wrapping needs to be removed.  Notice that all of the POST values, including the submit button, are included in the base string (i.e., the string signed by OAuth).

B.6    Conformance

Conformance for Basic LTI is granted through the IMS CC-LTI Alliance and consists of certification testing for TC and TP implementations. For additional information about conformance, visit the CC-LTI Alliance here: http://www.imsglobal.org/cc/alliance.html.

 

About This Document

 

Title:                                                      IMS Learning Tools Interoperability Basic LTI Implementation Guide

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

Editor:                                                  Charles Severance (IMS Global)

Version:                                                v1.0

Version Date:                                      17 May 2010

Release:                                                v1.0

Status:                                                   Final

Revision Information:                      Original Release

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

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

 

 

List of Contributors

The following individuals contributed to the authoring of this document:


Hal Herzog                           Learning Objects

Greg McFall                          Pearson

Mark McKell                        IMS Global

Lance Neumann                  Blackboard

Charles Severance               IMS Global

Colin Smythe                       IMS Global

Bruno Van Haetsdaele       Wimba

 


Revision History

 

Version No.

Release Date

Comments

Base Document v1.0

27 July 2009

The first formal release of the Base Document.  This document is released for review by the IMS Global LTI Project Group.

Internal Draft
Final v1.0

30 October 2009

The first formal release of the Internal Draft document.  This document is released for interoperability implementation by the IMS Global Members and Affiliates.

Public Draft v1.0

15 February 2010

The first formal release of the Public Draft.  This document is released for interoperability adoption by the community at large.

Final v1.0

17 May 2010

The first formal release of the Final specification. This document is released for public adoption.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

IMS Global Learning Consortium, Inc. (“IMS Global”) is publishing the information contained in this IMS Global Learning Tools Interoperability Basic LTI Implementation Guide (“Specification”) for purposes of scientific, experimental, and scholarly collaboration only.

IMS Global 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.

IMS Global would appreciate receiving your comments and suggestions.

Please contact IMS Global through our website at http://www.imsglobal.org

Please refer to Document Name: IMS Global Learning Tools Interoperability Basic LTI Implementation Guide v1.0
Revision: 17 May 2010