LTI 1.3 Development and Migration Checklist

This document:

• highlights differences between LTI versions 1.1 and 1.3;
• lists important, commonly-forgotten points when developing a new LTI 1.3 tool, or porting an LTI 1.1 tool to LTI 1.3.

For an introduction to migrating an LTI 1.1 tool, first read the LTI 1.1 to 1.3 Migration Guide.

Table of Contents

1. Getting a Basic Launch Working
2. LTI 1.3 Registration (LTI Developer Key) Configuration
3. Launch Data
4. Deep Linking
5. Target Link URI, Domain, and Migration Process
6. LTI Advantage Services
7. Appendix: Finding Matching LTI 1.1 and 1.3 Tools

1. Getting a Basic Launch Working

See LTI 1.3 Launch Flow for background.

1.1 Implement the OIDC Initiation (Login) Endpoint

See Step 1: Login Initiation.

• Validate the client ID and platform iss.
• Optionally handle each environment and/or region differently.. (Note that Canvas also supports different oidc_initiation_urls for different Canvas regions.)
• Generate a state and nonce.
• Set a partitioned cookie (non-partitioned cookies in iframes may be blocked) tied to the state and/or nonce, to be validated in the next step. This ensures the user agent that completes the process is the one that started it.
• Forward back to the platform's initiation URL.
  • Canvas URLs can be determined by environment, which can be determined by iss (but are NOT the same domain). If you only need to support cloud Canvas, you can hardcode these into your tool. Otherwise, platforms also advertise their URLs during Dynamic Registration.

1.2 Implement the Launch / Authentication Response Endpoint

See Step 3: Authentication Response.

• Validate the id_token signature against the platform's public JWKs. As with the platform's authorization URL, this is provided during Dynamic Registration, and the Canvas URL can be determined based on environment (beta, test, prod).
• Validate the iss, azp, aud, alg, exp, and iat claims.
• Validate the state, nonce, and the partitioned cookie tied to these.
• Make sure the nonce has not been used before. The iat and/or exp can be used to limit the amount of time a nonce is stored.
• This endpoint must be listed in the redirect URIs in the tool configuration.

2. LTI 1.3 Registration (LTI Developer Key) Configuration

2.1 Create JWKs for Your Key

See LTI 1.3 Asymmetric Key Flow for background.

• It's highly recommended to create a public JWKs endpoint, so you can rotate keys without downtime -- you'll need three JWKs ("past", "present", "future").
• Tool JWKs are not used in a simple tool launch, but used in most other LTI 1.3 extensions and services.
• It's often convenient to use one JWK Set / URL for all tenants.

2.2 Placements

• LTI 1.1 included the resource_selection placement by default. This placement is not for use with LTI 1.3 tools -- use assignment_selection and link_selection instead.

2.3 Registrations vs. Deployments

• Unlike self-contained LTI 1.1 Deployments, LTI 1.3 Deployments inherit their configuration from an LTI 1.3 Registration (AKA LTI Developer Key).
• If your LTI 1.1 tool is typically installed many times in the same Canvas root account (tenant / institution) -- in subaccounts and courses -- your LTI 1.3 tool will have one Registration, and many Deployments.
• Registrations can only be created in Canvas root accounts, never in subaccounts or courses. LTI 1.3 Deployments exist in courses, subaccounts, and root accounts, just like LTI 1.1 tools.
• Deployment-level customizations are very limited. If multiple LTI 1.1 deployments for one tenant had unique configuration, you will likely need to keep track of that configuration in the tool itself, keying off the https://purl.imsglobal.org/spec/lti/claim/deployment_id launch claim.

2.4 Dynamic Registration (DR)

• It is highly recommended to use Dynamic Registration for the easiest installation, rather than Canvas's older proprietary JSON configuration.

2.5 target_link_uri and domain

• The domain and default target_link_uri fields on a Registration help Canvas determine if the tool replaces an existing 1.1 tool. Choose carefully: see Finding Matching LTI 1.1 and 1.3 Tools.
• Canvas uses the target_link_uri (may be placement-specific) in the Registration configuration when launching using placements. Resource Links, such as those created by Deep Linking and AGS, may contain their own specific target_link_uri. You will want to make sure you handle both of these, as well as resource link (non-placement) launch URLs generated by your LTI 1.1 tool.
• Recall that the platform does not actually send traffic directly to an LTI 1.3 tool's Target Link URIs, but rather to its OIDC Initiation URI(s) and Redirect URLs.

3. Launch Data

• Data in an LTI 1.1 launch was transferred via query parameters, which meant values were always implicitly strings. LTI 1.3 launch data is in the JWT id_token, so as JSON it allows for nested claims of various types.
• While it is tempting to transform existing LTI 1.3 JSON into legacy LTI 1.1 param strings, long-term it's better and more direct to use an abstraction layer that can parse either format.
• Almost all Custom Fields and expansions supported in LTI 1.1 are supported in LTI 1.3 with identical behavior. (These are in the https://purl.imsglobal.org/spec/lti/claim/custom claim and are not prefixed with custom_ as in LTI 1.1 query params)
• The https://purl.imsglobal.org/spec/lti/claim/lti1p1 claim carries your old LTI 1.1 identifiers (user_id, resource_link_id, oauth_consumer_key, oauth_consumer_key_sign) so you can map data from your 1.1 tool -- see What's in the lti1p1 claim? for the field-by-field structure, and the 1EdTech Migration Guide for the spec.
  • For user ids, best practice is to use the sub claim going forward, but if your app has stored LTI 1.1 user ids, use lti1p1's user_id to map those users to their new sub value
  • Similarly, use resource_link_id to map old resource links to their new ones.
  • The oauth_consumer_key/oauth_consumer_key_sign fields identify the associated LTI 1.1 tool -- see Finding Matching LTI 1.1 and 1.3 Tools.

4. Deep Linking

• 1EdTech Deep Linking 2.0 is the replacement for LTI 1.1 Content Item -- see Deep Linking for the concept. The tool can return various types of content items, including resource links which can later be used to launch into the tool with the returned target_link_uri.
• If the LTI 1.3 message type is LtiDeepLinkingRequest, the tool may send a response (via the user agent) to the deep_link_return_url, signed using the tool's private key.
• Unlike LTI 1.1 Content Item, LTI 1.3 Deep Linking Responses are always signed.
• Some placements, such as link_selection, may allow LTI 1.3 tools to return multiple content items.
• See "Message Types" in the Deep Linking spec for a mapping between LTI 1.1 Content Item media types and new Deep Linking types.
• The older proprietary Canvas ext_content_return_types is covered by the accept_* LTI 1.3 claims.

5. Target Link URI, Domain, and Migration Process

• As mentioned in the Migration Process, immediately after an LTI 1.3 tool is installed (when a Deployment is created), Canvas will begin using your LTI 1.3 tool to launch any matching LTI 1.1 Resource Link in a Context (course/account) where the LTI 1.3 tool is available. You cannot control whether your tool launches via LTI 1.1 or LTI 1.3 at launch time.
• Rollback is accomplished by simply uninstalling the LTI 1.3 tool (Deployment) -- but the exact behavior depends on whether the LTI 1.1 tool is still installed; see Can I rollback the migration? for the details.
• Matching tools are determined principally by the launch URL, and the URL (default target_link_uri) and domain of the new tool.
• Placements (assignment_selection, course_navigation, etc.) reference the tool directly, so if a user clicks on the placement associated with the LTI 1.1 tool, it will launch the LTI 1.1 tool. If you have both the LTI 1.1 and the LTI 1.3 tool available in the same Context (course/account), they will both appear until the LTI 1.1 tool is deleted.
• There may not be a one-to-one correspondence between an LTI 1.3 tool and the LTI 1.1 tool it replaces: for instance, if an LTI 1.1 tool is installed in two courses, but an LTI 1.3 tool that matches is installed in the account those courses live in, Resource Links created by both tools will launch using the same LTI 1.3 tool.
• It is highly recommended you test the migration in a sandbox account, and/or on Canvas beta instances, before rolling out to real institutions -- see Can I test the migration without affecting users? for a fuller walkthrough. Remember that beta/test is not a full test though, since they have little to no real user traffic.

6. LTI Advantage Services

6.1 Overview

• A number of services, based on 1EdTech specs, are available to LTI 1.3 tools.
• To obtain a token for use with these, tools must use the client_credentials OAuth2 grant with a client assertion signed using one of their private keys.
• Tools must also include the scopes corresponding to each endpoint it wishes to use in their Registration -- see LTI Advantage Services permissions for the full list of scopes.
• The URLs for most of these services are provided in claims in launches. For Canvas, AGS and NRPS may also be determined given knowledge of a Canvas course ID.

6.2 Assignment and Grades Services (AGS)

See Assignment Tools and the 1EdTech Assignment and Grading Services Specification for details.

• AGS replaces LTI 1.1 Grade Passback.
• Beyond grading, it also provides the ability to create and manage line items (assignments).
• There are some differences between AGS and Grade Passback, such as Score Scaling and timestamp rules.
• LTI 1.3 does not use LTI 1.1's sourcedid; instead, a line item URL (which doubles as an ID) is included in the https://purl.imsglobal.org/spec/lti-ags/claim/endpoint claim in launches. A tool may also list all of the line items it owns for a course, even ones not associated with the current launch.

6.3 Names and Roles Provisioning Service (NRPS)

• NRPS provides course and group membership (enrollment) information -- see also LTI Advantage: Names and Role Provisioning Service.
• Older LTI 1.1- and LTI 2.0-era services such as the older Canvas Membership Service should not be used.

6.4 Platform Notification Service (PNS) and Asset Processor

• Platform Notification Service provides a way for platforms to notify LTI 1.3 tools of certain events, in a server-to-server request (no user agent involved)
• Asset Processor allows LTI 1.3 tools to process student-submitted content. Among other applications, it replaces the Canvas LTI 2.0 Plagiarism Platform.

Appendix: Finding Matching LTI 1.1 and 1.3 Tools

Canvas tries to match an LTI 1.3 tool with links created by an LTI 1.1 tool in two situations, listed below. These processes -- combined with your old tool's deep link launch URLs, tool-level launch URL (tool url field), and tool domain -- influence how you should choose your new 1.3 tool's domain, default target_link_url, and (indirectly) new deep link target_link_uris.

Both situations affect non-placement launches, such as assignments, module items, collaborations, and resource links returned via content-item (such as from an editor_button launch). They do not affect direct placement-based launches (in which Canvas lists the available tools) such as navigation (course_navigation, etc.) or Content Item / Deep Linking requests (assignment_selection, editor_button, etc.).

Situation 1: Just-in-time matching

This is the matching you have to worry about most, since it is the final chance to find a matching 1.3 tool for an old 1.1 link, and it covers items the initial on-install batch migration may have missed. It is based on the LTI link launch URL.

• if an LTI 1.3 tool matches on exact URL including exact query params, it is used. Otherwise, if an LTI 1.1 tool matches on exact URL including exact query params, it is used.
• if an LTI 1.3 tool matches on URL and every query param (but the launch URL may have additional query params), it is used. Otherwise, if an LTI 1.1 tool matches in this way, it is used.
• if an LTI 1.3 tool matches on domain or subdomain (e.g. launch URL foo.example.com, tool domain foo.example.com or example.com), it is used. Otherwise, if an LTI 1.1 tool matches in this way, it is used.

Because of these three tiers, if an LTI 1.1 link matches at an earlier tier than an LTI 1.3, the link may not launch until the 1.1 tool is deleted (unless already migrated, see Situation 2). However, you need to make sure your new tool's URL or domain is general enough to cover all your possible LTI 1.1 links and your new target_link_url links.

Situation 2: Link Batch Migration

The batch migration is initiated when an LTI 1.3 tool is installed which matches an existing LTI 1.1 tool. It makes line items available to your tool (via AGS) before any launches happen for them.

Its matching works slightly differently to just-in-time matching because it is looking first for a 1.1 tool that matches on the 1.3 tool's url or (if none) domain. As a result, it may miss links the just-in-time matching covers, or in some cases, it may migrate links that the just-in-time matching would normally not find until the 1.1 tool is deleted.

Recommendation

In most cases, it is suggested to:

• use the same domain/subdomain to host both versions of your tool, and indicate the domain in the domain field of both tools.
• and/or use the URL of your LTI 1.1 deep links (if consistent) as the default target_link_url of your new tool.