Learning Tools Interoperability 1.3 Migration Guide

1EdTech Learning Tools (LTI)® Interoperability Migration Guide

1EdTech Final Release
Version 1.3
1EdTech Final Release
Date Issued:7 May 2019
Status:This document is made available for adoption by the public community at large.
This version: https://www.imsglobal.org/spec/lti/v1p3/migr/

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 © 2019 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/speclicense.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.

Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources.

© 2019 1EdTech Consortium, Inc. All Rights Reserved.

Trademark information: http://www.imsglobal.org/copyright.html

Abstract

This 1EdTech Learning Tools Interoperability (LTI)® document provides implementation guidance for tools and platforms migrating from earlier versions of LTI™ (v1.0, v1.1, and v1.2) to LTI™ v1.3 and the LTI™ Advantage specifications.

  1. LTI Migration Guide

  1.1 Introduction

While drastically modifying the runtime behavior of LTI, the LTI 1.3 specifications aimed at content backward compatibility by not introducing new concepts that would require a redefinition of what makes an LTI link. For example, a course already set up with links and grade book columns can see the tool be switched from 1.1 to 1.3 without having to modify those links or apply any data migration on the content, the tool can be switched to LTI 1.3 'in flight', each LTI 1.1 parameter having a counter part in the LTI claims found in the LTI 1.3 id_token.

While the above represents the ideal case, in practice some migration work might still be needed on the tool side as some ids may have shifted; for example, the user id may be a new id, following the adoption of the OpenId Connect flow in LTI 1.3. Other identifiers may have shifted too.

In LTI 1.3, the tool OAuth client_id is not the counter part of the oauth_consumer_key; the tool needs to reconcile the tool's deployment identified by the LTI 1.3 deployment_id to an actual account.

This document is a companion to the LTI 1.3 specification [LTI-13] that exposes the main changes introduced with LTI 1.3. It also introduces a dedicated claim to carry the LTI 1.1 legacy data allowing the platform to keep exposing previous identifiers and thus allow the tool to offer an uninterrupted service when it is transitioned to use LTI 1.3 payloads.

For simplicity purposes, this specification will use the terminology of LTI 1.1 to refer to LTI 1.0, LTI 1.1, LTI 1.2 and their security patch releases.

  1.2 Documentation

The following LTI v1.3 and LTI Advantage related specification documents are available:

  • 1EdTech Security Framework Version 1.0 [SEC-10] specification
  • LTI Core Version 1.3 [LTI-13] specification
  • Deep Linking Version 2.0 [LTI-DL-20] specification
  • Names and Role Provisioning Services Version 2.0 [LTI-NRPS-20] specification
  • Assignment and Grade Services Version 2.0 [LTI-AGS-20] specification
  • LTI Advantage Implementation Guide [LTI-IMPL-13] specification
  • LTI Advantage Conformance Certification Guide [LTI-CERT-13] specification

  1.3 Conformance Certification

This document is an informative resource in the Document Set of the LTI Advantage specification [LTI-13]. As such, it does not include any normative requirements. Occurrences in this document of terms such as MAY, MUST, MUST NOT, SHOULD or RECOMMENDED have no impact on the conformance critera for implementors of this specification.

1EdTech offers a process for testing the conformance of products using the 1EdTech certification test suite. Certification designates passing a set of tests that verify the standard has been implemented correctly and guarantees a product’s interoperability across hundreds of other certified products. The LTI Advantage Conformance Certification Guide [LTI-CERT-13] provides details about the testing process, requirements, and how to get started.

  2. 1.1/1.3 equivalent

  2.1 Deployment Id and multi-tenant model

LTI 1.1 deployment model usually centered around the sharing of a consumer key, identifying the deployment, and a shared secret, securing it. Each new deployment had typically its own key and secret. This model was a good fit when most learning platforms were deployed on premises. Nowadays, Software as a Service model (SAAS) is a prevalent model. To better support this model, LTI 1.3 separates the registration of the tool (security and configuration) from its actual deployment.

  2.1.1 Register once

A tool typically registers once with the LMS platform; registering includes the exchange of keys and the various other configurations needed for the tool to function such as the OpenID and OAuth Token endpoints.

A tool registration is identified as a client_id issued by the learning platform (the issuer).

  2.1.2 Deploy multiple times

A tool may then be deployed to many organizations running under the same learning platform. Each deployment is identified by a unique deployment_id minted by the learning platform.

LTI 1.1 parameter LTI 1.3 equivalent Note
oauth_consumer_key (issuer, client_id, deployment_id) In single tenant model, there will only be only a single deployment_id per (issuer, client_id) tuple and registration and deployment may then still be done as a single operation.
oauth_ JSON Web Signature claims LTI 1.3 relies on asymmetric keys (public/private keys)

See the LTI 1.3 Core Specification [LTI-13] and 1EdTech Security Framework [SEC-10] for more details.

  2.2 From POST parameters to claims

The table belows maps the 1.1 parameters with their LTI 1.3 claims equivalent; the format for 1.3 is: {claim_uri} or {claim_uri}#property when the claim itself is an object and referring to a property of that claim.

LTI 1.1 parameter LTI 1.3 claim equivalent Note
lti_message_type https://purl.imsglobal.org/spec/lti/claim/message_type
lti_version https://purl.imsglobal.org/spec/lti/claim/version for LTI 1.3 version is 1.3.0
user_id sub
lis_person_name_given given_name
lis_person_name_family family_name
lis_person_name_full name
lis_person_contact_email_primary email
user_image picture
lis_person_sourcedid https://purl.imsglobal.org/spec/lti/claim/lis#person_sourcedid
lis_course_offering_sourcedid https://purl.imsglobal.org/spec/lti/claim/lis#course_offering_sourcedid
lis_course_section_sourcedid https://purl.imsglobal.org/spec/lti/claim/lis#course_section_sourcedid
resource_link_id https://purl.imsglobal.org/spec/lti/claim/resource_link#id
resource_link_title https://purl.imsglobal.org/spec/lti/claim/resource_link#title
resource_link_description https://purl.imsglobal.org/spec/lti/claim/resource_link#description
roles https://purl.imsglobal.org/spec/lti/claim/roles LTI 1.3 deprecates short roles and uses fully qualified role URIs.
context_id https://purl.imsglobal.org/spec/lti/claim/context#id
context_type https://purl.imsglobal.org/spec/lti/claim/context#type LTI 1.3 deprecates short names and uses fully qualified context type URIs.
context_title https://purl.imsglobal.org/spec/lti/claim/context#title
context_label https://purl.imsglobal.org/spec/lti/claim/context#label
launch_presentation_locale https://purl.imsglobal.org/spec/lti/claim/launch_presentation#locale
launch_presentation_css_url Not supported in LTI 1.3
launch_presentation_document_target https://purl.imsglobal.org/spec/lti/claim/launch_presentation#document_target
launch_presentation_width https://purl.imsglobal.org/spec/lti/claim/launch_presentation#width
launch_presentation_height https://purl.imsglobal.org/spec/lti/claim/launch_presentation#height
launch_presentation_return_url https://purl.imsglobal.org/spec/lti/claim/launch_presentation#return_url
tool_consumer_info_product_family https://purl.imsglobal.org/spec/lti/claim/tool_platform#product_family_code
tool_consumer_info_version https://purl.imsglobal.org/spec/lti/claim/tool_platform#version
tool_consumer_instance_guid https://purl.imsglobal.org/spec/lti/claim/tool_platform#guid In multi-tenant identifies the institution not the vendor platform.
tool_consumer_instance_name https://purl.imsglobal.org/spec/lti/claim/tool_platform#name
tool_consumer_instance_description https://purl.imsglobal.org/spec/lti/claim/tool_platform#description
tool_consumer_instance_url https://purl.imsglobal.org/spec/lti/claim/tool_platform#url
tool_consumer_instance_contact_email https://purl.imsglobal.org/spec/lti/claim/tool_platform#email
custom_keyname https://purl.imsglobal.org/spec/lti/claim/custom#keyname The value is always a String
role_scope_mentor https://purlimsglobal.org/spec/lti/claim/role_scope_mentor
ext_ https://{domain}/{claimPath} Extensions are added by custom claims using fully qualified URI as name

  3. Migrating from Basic Outcome to Assignment and Grade Services 2.0

LTI Advantage introduces a richer API around grades reporting, called Assignment and Grade Services [LTI-AGS-20]. The API still supports a flow similar to Basic Outcome where on each resource link message the end point where to send scores is passed in:

LTI 1.1 parameter LTI 1.3 claim equivalent Note
lis_outcome_service_url https://purl.imsglobal.org/spec/lti-ags/claim/endpoint#lineitem The endpoint is specific for each activity
lis_result_sourcedid sub Grades are reported for a given (lineitem, user)

Scores are JSON payloads and passes both the points earned and the points possible rather than a normalized score as in Basic Outcome. However a tool may still set the points possible to 1 and carrying on normalizing the score.

See the Assignment and Grades Services for more details.

  4. Migrating to Deep Linking 2.0

Deep Linking [LTI-DL-20] remains mostly unchanged between version 1.0 and 2.0 from a functional viewpoint; the same kind of content item can be created/picked, and the UI Flow is identical:

  1. An LTI Request to start the deep linking response opens the tool's interface for content selection/creation.
  2. Control is passed back by redirecting the browser to the platform with the actual content item selection as the POST body.

However, the actual payload being exchanged in the request and in the response are significantly different in their format. The differences are:

  1. Deep Linking Launch follows the OIDC 3rd party initiated login flow
  2. The Deep Linking Request is thus an id_token with a dedicated claim for deep linking
  3. Deep Linking response is a single JSON Web Token (JWS) with a simplified content items structure
  4. JSON-LD is no more used
  5. The type system has been clarified
  6. Multiple presentations option (window, embed, iframe) can be included per content item

See the Deep Linking V2.0 for more detailed mapping between the 2 versions.

  5. Migrating to Names and Role Provisioning Services 2.0

Names and Role Provisioning Service 2.0 [LTI-NRPS-20] offers the same functionality as its previous version, the changes mostly focusing on rationalizing the payload:

  1. JSON-LD is no more used
  2. Less nesting
  3. paging and differences links are now exposed in the link header rather than being included in the actual response payload
  4. New mediatypes to reflect the content structure changes

This service is now protected by an access token; it defines an OAuth scope and the claim to advertise its endpoint in the actual LTI messages.

See the Names and Roles Provisioning Service 2.0 [LTI-NRPS-20] for more details.

  5.1 lti11_legacy_user_id

If the user id is changing with the migration to LTI 1.3, a platform should include the lti11_legacy_user_id as an additional member attribute. It should contain the userId value from LTI 1.1 Names and Roles Provisioning Service 1.0 [LTI-NRPS-10] for that same user.

{
"id" : "https://lms.example.com/sections/2923/memberships",
"context": {
  "id": "2923-abc",
  "label": "CPS 435",
  "title": "CPS 435 Learning Analytics",
},
"members" : [
  {
    "name": "Jane Doe",
    "given_name" : "Jane",
    "family_name" : "Doe",
    "user_id" : "0ae836b9-7fc9-4060-006f-27b2066ac545",
    "lti11_legacy_user_id": "668321221-2879",
    "roles": [
      "http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor"
    ]
  }
]
}
Figure 1 Example of application/vnd.ims.lis.v2.membershipcontainer+json media type with lti11_legacy_user_id.

This allows the tool to migrate the full course roster upfront rather than having to wait for each user to launch and relying on the LTI 1.1 migration claim (see below) to map the old and new user identifiers.

  5.2 Deprecation of lis_result_sourced_id

Names and Roles Provisioning Service was often used to discover the Basic Outcome lis_result_sourced_id. This usage is now deprecated in favor of using the actual user id in the score POST from Assignment and Grades service, and this information may no longer be included in the response.

  6. LTI 1.1 migration claim

This specification introduces the claim https://purl.imsglobal.org/spec/lti/claim/lti1p1 which allows a platform to pass to the tool a mapping of ids that have shifted with the transition to LTI 1.3, allowing the tool to associate existing records to new LTI 1.3 identifiers.

It also allows to securely pass the oauth_consumer_key to avoid interruption due to a need to remap the tool to a new registration/deployment.

If a platform supports this claim, it MUST include that claim in all messages sent to the tool, including resource links and deep linking messages.

Support for this claim is recommended for platforms that already support LTI 1.1 tools, in particular if the move to LTI 1.3 causes ids to change of value.

  6.1 Remapping parameters

The following parameters all follow the same rules:

If the launch may actually have happened prior to the migration, and if the parameter's value is not the same as its LTI 1.3 equivalent, the platform MUST include the parameter and its LTI 1.1 value. Otherwise the platform MAY omit that attribute or have it be the same value as its LTI 1.3 equivalent.

The parameter's value MUST be the same as the value that would have been passed would the current user have done the launch with the tool under its LTI 1.1 configuration.

The migration data is immutable, the platform MUST NOT change the mapping once it has been advertised.

Claim property LTI 1.1 parameter include if different from LTI 1.3 claim equivalent
user_id user_id sub
context_id context_id https://purl.imsglobal.org/spec/lti/claim/context#id
tool_consumer_instance_guid tool_consumer_instance_guid https://purl.imsglobal.org/spec/lti/claim/tool_platform#guid
resource_link_id resource_link_id https://purl.imsglobal.org/spec/lti/claim/resource_link#id

  6.2 OAuth Consumer Key and automatic re-binding of deployment id

In addition to allowing a mean to map identifiers that have changed during the migration, this specification also allows to securely pass in the LTI 1.1 OAuth Consumer Key for simplified or automatic account migration.

In LTI 1.1 it is common practice for a tool to associate a tool's account to the OAuth Consumer Key, the tool often issuing the actual key value. The flow is reversed in LTI 1.3 where the platform issues a deployment_id to identify each tool's deployment and the tool usually has to bind that id to an account, for example by prompting the user when a tool is first launched after its deployment.

Passing the LTI 1.1 oauth_consumer_key may actually allow to automate or at least ease the re-binding of the deployment to a pre-existing account.

As the oauth_consumer_key is publicly exposed, it cannot be trusted on its own to transition the existing account to the new deployment_id. This specification relies on the pre-established LTI 1.1 trust using the shared secret to assert the migration request is coming from the actual LTI 1.1 tool deployment identified by the oauth_consumer_key.

  6.2.1 oauth_consumer_key

The LTI 1.1 oauth_consumer_key MUST be added to the claim.

  6.2.2 oauth_consumer_key_sign

The platform MAY include a signature of the oauth_consumer_key to allow the tool to automate a migration. The oauth_consumer_key_sign is built using the following steps:

  1. compute base base_string: concatenates the following values in the following order, separated by & (ampersand) sign, with no trailing &
  2. oauth_consumer_key
    • deployment_id: the LTI deployment ID found in the enclosing JWT
  3. iss: as found in the enclosing JWT
  4. client_id: the OAuth client id of the tool, as found as one of the values for the aud claim in the enclosing JWT
  5. exp: as found in the enclosing JWT
  6. nonce: as found in the enclosing JWT
  7. sign the base_string encoded as UTF-8 Octets using hmac-sh256 using the LTI 1.1 shared secret encoded as UTF-8 Octets as the key
  8. base64 [RFC4648] (https://tools.ietf.org/html/rfc4648#section-4) encode the result

A platform should usually not automatically migrate a tool based on the oauth_consumer_key if the oauth_consumer_key_sign property is not present or if the signature was not verified.

Example:

sign=base64(hmac_sha256(utf8bytes('179248902&689302&https://lmsvendor.com&PM48OJSfGDTAzAo&1551290856&172we8671fd8z'), utf8bytes('my-lti11-secret')))

{
"nonce": "172we8671fd8z",
"iat": 1551290796,
"exp": 1551290856,
"iss": "https://lmsvendor.com",
"aud": "PM48OJSfGDTAzAo",
"sub": "3",
"https://purl.imsglobal.org/spec/lti/claim/deployment_id": "689302",
"https://purl.imsglobal.org/spec/lti/claim/lti1p1": {
    "user_id": "34212",
    "oauth_consumer_key": "179248902",
    "oauth_consumer_key_sign": "lWd54kFo5qU7xshAna6v8BwoBm6tmUjc6GTax6+12ps="
}
}
Figure 2

  6.3 Rolling back to LTI 1.1

This specification does not cover any process to rollback to LTI 1.1 once a migration is completed. However a tool MAY consider retaining the LTI 1.1 identifiers and the shared secret. The tool MAY then add new properties to existing entities to store the LTI 1.3 new identifiers rather than replacing values in existing properties, allowing the tool to still be able to receive LTI 1.1 requests.

  A. References

  A.1 Normative references

[LTI-13]
1EdTech Learning Tools Interoperability (LTI)® Core Specification v1.3. C. Vervoort; N. Mills. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/lti/v1p3/
[LTI-AGS-20]
1EdTech Learning Tools Interoperability (LTI)® Assignment and Grade Services. C. Vervoort; E. Preston; M. McKell; J. Rissler. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/lti-ags/v2p0/
[LTI-CERT-13]
1EdTech Learning Tools Interoperability (LTI)® Advantage Conformance Certification Guide. D. Haskins; M. McKell. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/lti/v1p3/cert/
[LTI-DL-20]
1EdTech Learning Tools Interoperability (LTI)® Deep Linking 2.0. C. Vervoort; E. Preston. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/lti-dl/v2p0/
[LTI-NRPS-20]
1EdTech Learning Tools Interoperability (LTI)® Names and Role Provisioning Services. C. Vervoort; E. Preston; J. Rissler. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/lti-nrps/v2p0/
[RFC4648]
The Base16, Base32, and Base64 Data Encodings. S. Josefsson. IETF. October 2006. Proposed Standard. URL: https://tools.ietf.org/html/rfc4648
[SEC-10]
1EdTech Security Framework v1.0. C. Smythe; C. Vervoort; M. McKell; N. Mills. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/security/v1p0/

  A.2 Informative references

[LTI-IMPL-13]
1EdTech Learning Tools Interoperability (LTI)® Advantage Implementation Guide. C. Vervoort; J. Rissler; M. McKell. 1EdTech Consortium. April 2019. 1EdTech Final Release. URL: https://www.imsglobal.org/spec/lti/v1p3/impl/
[LTI-NRPS-10]
1EdTech Learning Tools Interoperability (LTI)® Names and Role Provisioning Services. S. Vickers. 1EdTech Consortium. 24 May 2016. 1EdTech Final Release. URL: https://www.imsglobal.org/specs/ltimemv1p0

  B. List of Contributors

The following individuals contributed to the development of this document:

Name Organization Role
Viktor HaagD2L
Dereck Haskins1EdTech
Martin LenordTurnitin
Karl LloydInstructure
Mark McKell1EdTech
Bracken Mosbacker1EdTech
Marc PhillipsInstructure
Eric PrestonBlackboard
James Rissler1EdTechEditor
James TseGoogle
Charles SeveranceUniversity of Michigan
Colin Smythe1EdTech
Claude VervoortCengageEditor

1EdTech Consortium, Inc. ("1EdTech") is publishing the information contained in this document ("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: Learning Tools Interoperability Migration Guide 1.3

Date: 7 May 2019