LTI Migration Guide

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 IMS Global Learning Tools Interoperability® Core Specification v1.3 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.

Documentation

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

• IMS Security Framework Version 1.0 IMS Global Security Framework v1.0 specification
• LTI Core Version 1.3 IMS Global Learning Tools Interoperability® Core Specification v1.3 specification
• Deep Linking Version 2.0 IMS Global Learning Tools Interoperability® Deep Linking 2.0 specification
• Names and Role Provisioning Services Version 2.0 IMS Global Learning Tools Interoperability® Names and Role Provisioning Services specification
• Assignment and Grade Services Version 2.0 IMS Global Learning Tools Interoperability® Assignment and Grade Services specification
• LTI Advantage Implementation Guide IMS Global Learning Tools Interoperability® Advantage Implementation Guide specification
• LTI Advantage Conformance Certification Guide IMS Global Learning Tools Interoperability® Advantage Conformance Certification Guide specification

1.1/1.3 equivalent

Link URLs must stay intact

The details in this migration guide assume that the unchanging part of an LTI Link across migration is the Link URL itself. This helps ensure that a link migration can be supported across import/export workflows where links are packaged in Common Cartridge content packages (where the only way that a link can be imported is via the "domain matching" methodology). There's no support in this document for specifying a set of "translation rules" that could deterministically change the form of link URLs across the migration process; rather, we assume that the link URL itself remains the same. Some LTI Platforms may choose to provide functionality like this, but that would be a vendor-specific feature. Note that this means that the Link URL in LTI 1.1 should become the Target Link URL, unchanged, after a migration to LTI 1.3; the Redirect URL used in LTI 1.3 for a Tool may very well be different to the 1.1 Link URL.

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.

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).

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.

See the LTI 1.3 Core Specification IMS Global Learning Tools Interoperability® Core Specification v1.3 and IMS Security Framework IMS Global Security Framework v1.0 for more details.

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.

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 IMS Global Learning Tools Interoperability® Assignment and Grade Services. 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:

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.

Migrating to Deep Linking 2.0

Deep Linking IMS Global Learning Tools Interoperability® Deep Linking 2.0 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.

Migrating to Names and Role Provisioning Services 2.0

Names and Role Provisioning Service 2.0 IMS Global Learning Tools Interoperability® Names and Role Provisioning Services 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 IMS Global Learning Tools Interoperability® Names and Role Provisioning Services for more details.

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 IMS Global Learning Tools Interoperability® Names and Role Provisioning Services 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"
      ]
    }
  ]
}

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.

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.

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.

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.

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.

oauth_consumer_key

The LTI 1.1 oauth_consumer_key MUST be added to the claim.

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 &
   • oauth_consumer_key
   • deployment_id: the LTI deployment ID found in the enclosing JWT
   • iss: as found in the enclosing JWT
   • client_id: the OAuth client id of the tool, as found as one of the values for the aud claim in the enclosing JWT
   • exp: as found in the enclosing JWT
   • nonce: as found in the enclosing JWT
2. 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
3. base64 The Base16, Base32, and Base64 Data Encodings (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="
}
}

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.

`;