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

  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"
    ]
  }
]
}

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

  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.

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="
}
}

  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.