Minor LTI 1.3 Changes: New OIDC Auth Endpoint, Support for Platform Storage

The content in this blog is over six months old, and the comments are closed. For the most recent product updates and discussions, you're encouraged to explore newer posts from Instructure's Product Managers.

xmoffatt
Instructure
Instructure
‎06-20-2023 01:35 PM
47
16670

3.png

Canvas is changing its LTI 1.3 OIDC Auth domain to align with security practices and to support the new LTI 1.3 Platform Storage specification. This specification lets LTI tools function when browsers disable cross-site 3rd-party cookies. LTI 1.3 tool developers, read on for an implementation guide and the full status of Platform Storage support. These are not breaking changes.

For Canvas admins:

What is changing?

We are asking tool developers to update some of the Canvas URLs that they store in their tool configuration. The old URLs will continue to work, but updating will prevent future possible issues with LTI Tools and the Content Security Policy feature, and will allow tools to take advantage of a new 1EdTech LTI 1.3 specification called Platform Storage.

Platform Storage is an 1EdTech LTI specification that allows tools to function when browsers disable cross-site cookies. Until now, tools launching from Canvas have relied on cookies to store information. Browsers have been locking down this behavior to protect users from marketing and ill-intentioned uses. Since tools have a valid need for these cookies, we have enabled a way for them to store information with Canvas instead of as a cookie, so they are not impacted.

As a Canvas administrator, this change will only require work on your part if you have LTI 1.3 tools configured for your account that you needed to configure yourself. For example, if you installed an LTI 1.3 tool and as part of the setup you had to enter URLs from Canvas like the OIDC Auth endpoint or Public JWKs URL, then you will need to update those URLs in the tool's configuration. Specific steps can be found in the "What will I need to change?" section below.

Otherwise, this won't require any work on your part! LTI 1.3 tool providers wishing to use Platform Storage will need to implement the specification on their side in order to allow them to continue working when cross-site cookies are disabled, but those changes should not require any modifications from within Canvas. You will need to work with the tool providers directly to learn more about their plans to implement this specification.

On August 19, 2023 (July 17 for Beta), the Platform Storage API will be fully supported by Canvas, and the OIDC Auth endpoint and other 1.3 configuration URLs recommended in our API docs will change. No existing LTI 1.3 behavior will break after those dates, and tools do not need to switch endpoints before those dates. We recommend that all 1.3 tools move to use these endpoints as soon as possible, but will not be enforcing the change at this time.

If you’re curious, you are more than welcome to read the rest of the article to understand the context behind these changes!

How is this change being communicated?

In addition to being posted here, notices that link to this article will be posted in our API Docs, on the Developer Keys page in Canvas, in the Canvas release notes, and sent to our LTI partners. You are welcome to contact your tool providers to make sure they have seen this information and learn more about their plans to implement the feature.

If you have questions about this process, please contact Instructure support through the normal avenues and be sure to mention LTI Platform Storage.

For LTI 1.3 tool developers:

What is changing?

The domain of the OIDC Auth endpoint and other Canvas endpoints used in configuring LTI 1.3 tools is changing from canvas.instructure.com to sso.canvaslms.com. The reasoning behind this change and the exact modifications you will need to make are all documented below. You can make these changes at any point starting now.

In addition, the 1EdTech specification for Platform Storage will be fully supported in Canvas on August 19, 2023 (July 17 for Beta) for LTI 1.3 tools. Canvas already supports most of this specification, and tools are already developing against it. An overview of the spec and a full implementation progress update is laid out at the end of this article.

Updating the OIDC Auth endpoint is required to fully implement the 1EdTech specification for Platform Storage. This feature is not supported in LTI 1.1, so we want to take this opportunity to encourage you to begin your migration to LTI 1.3 if you have not yet. We are continuing to develop new and exciting features for LTI 1.3 and it will be the go-forward specification. Note that there is not a sunset date for LTI 1.1 at this time and we are committed to providing 12 months of full support after a date is announced as well as an additional 12 months after that where the code is still available though not fully supported. 

What is the OIDC Auth Endpoint?

It's a canvas endpoint that usually looks like https://canvas.instructure.com/api/lti/authorize_redirect that tools redirect to during the LTI Launch process. The LTI 1.3 Launch flow is built on the OIDC (Open ID Connect) spec, which uses the OAuth 2 Client Credentials flow to securely give credentials (in this case, the LTI launch parameters) to a trusted source (the LTI tool). During tool "registration", or the process of creating a trusted relationship between Canvas and a tool using an LTI Developer Key, the tool is required to store some Canvas-specific configuration variables, one of which is the OIDC Auth endpoint.

Why is it changing?

The canvas.instructure.com domain is not only used for OIDC authentication and redirection, but also for our Free for Teacher offering that lets anyone try Canvas for free. As you can imagine, this free domain comes with both happy users and a lot of spam. The main impetus for this change is to separate the distinct functions of 1) a central, authentication-related domain and 2) an actual Canvas instance open to the public.

The need for this change was emphasized by problems with two separate features, stemming from the browser security feature called the Content Security Policy. The CSP Header helps to mitigate XSS (Cross-Site Scripting) attacks on one domain from another. As you will see, these aren’t capital-P problems like “Canvas doesn’t protect against XSS attacks”, but are instead reinforcements to existing security.

  1. Canvas supports configuring this header at the root account level, so that institutions can allow only certain websites to be rendered inside <iframe> elements in Canvas. Domains for installed LTI tools are automatically added to this list, but the LTI 1.3 launch flow also requires the OIDC Auth domain (ie, canvas.instructure.com) to be added to this list.
  2. The LTI Platform Storage spec (more on this at the end if you aren't familiar with it) requires that tools send Javascript postMessages to Canvas using the OIDC Auth endpoint for the target origin. This requires a message listener running on that domain, which makes for an interesting engineering puzzle. Since Canvas is a multi-tenant application and domains vary by institution, this required work on our side. The spec allows a platform like Canvas to direct tools to send postMessages to a specific named browser frame, which helps to solve this specific problem. However, rendering this listener frame also requires the OIDC Auth domain to be added to the CSP list.

This is where the duties of canvas.instructure.com start to work against one another. As the OIDC Auth domain, it's required to be present in the CSP header so that it can serve content inside iframes in Canvas. But, as the Free for Teacher domain, there is a lot of content that it serves that can be spammy or even malicious. We aren't comfortable making that tradeoff and don't want to enable content from canvas.instructure.com to be served to every other Canvas institution.

Enter sso.canvaslms.com, a newer domain that performs just the right function we need - centralized authentication and SSO login. This domain has been around for a while, and presented the perfect solution to this CSP dilemma. Content served from this domain is only from Instructure, and so can be confidently added to the CSP header, and used as the new OIDC Auth endpoint for all LTI 1.3 tools moving forward.

What will you need to change?

Right off the bat, it's crucially important to note that the Issuer Identifier (iss) is not changing. That will continue to be canvas.instructure.com, since that is a unique identifier for Canvas as an LTI Platform, and not actually a URL.

Other than that, any Platform-related URLs that live in your tool's datastore that use canvas.instructure.com should switch to using sso.canvaslms.com.

URLs that will change:

In addition, any references to other Canvas environments like Beta and Test should also change in the same manner:

  • canvas.beta.instructure.com becomes sso.beta.canvaslms.com
  • canvas.test.instructure.com becomes sso.test.canvaslms.com

As a side note, there are some tools and institutions that use their direct Canvas domain in place of canvas.instructure.com for these endpoints. Though this practice doesn't technically conform to the LTI spec, it's accepted and will continue to work with both *.instructure.com domains, and all vanity domains. These configurations do not need to switch to the new endpoint to continue working, although we recommend using the new endpoint to conform to the LTI 1.3 spec. However, note that to fully conform to the Platform Storage spec, postMessages must be addressed to the OIDC Auth endpoint defined by the platform, which in this case will be sso.canvaslms.com.

What are the consequences of not making this change?

You may have already picked up on the fact that even though we are asking you to use sso.canvaslms.com, canvas.instructure.com still exists and works. These endpoints are accessible from every Canvas institution, even your own. There isn't a point in time where using https://canvas.instructure.com/api/lti/authorize_redirect during the LTI 1.3 launch flow will suddenly stop working.

But, there are consequences for not making this change. You can decide how severely these will impact your tool. If a tool does not switch domains:

  1. The tool will not be able to fully conform to the Platform Storage specification. For now, Canvas will still accept postMessages with a target origin of *, even though this limits postMessage security. Eventually, all tools will need to use the new OIDC Auth domain for the target origin for all postMessages. LTI launches that don't properly use the Platform Storage spec will be open to MITM (man in the middle) attacks. LTI tools can decide whether to use cookies or the Platform Storage spec in most browsers, but in browsers that block 3rd party cookies (like Safari), they will need to correctly store the state parameter in Platform Storage.
  2. In the future, if a Canvas institution in which the tool is installed decides to enable the CSP feature and restrict domains that can serve content in that institution, launches to the tool will fail unless the institution admins explicitly add the old canvas.instructure.com domain to the CSP Domain Allowlist. The tool developers will need to communicate with the institution admins directly, as Instructure won't provide support for making this change. We do not yet have an enforcement date for this, as we want to provide tools with the necessary time to make the change so that we minimize impact on educators. We will announce the enforcement date as we monitor tools’ migrations to the new endpoint.

When is this change happening?

Tools are free to change their stored config for Canvas and use this new endpoint starting right now. We recommend that all 1.3 tools begin using this new endpoint as soon as possible, but it's important to note that no current LTI 1.3 behavior will break if tools do not update their configuration. This is an opt-in change for now, and enforcement of consequence 2 listed above will happen on a later, unspecified date - accompanied by a 90-day change notice.

However, tools wishing to use Platform Storage should note that the consequence listed in point 1 above will take effect in Beta on July 17, 2023, and in Production on August 19, 2023. In addition, the full implementation of the Platform Storage API will be enabled that day, including the requirement to use sso.canvaslms.com for the target origin of Platform Storage postMessages (see the support update below for exact details).

Notices that link to this article will be posted in our API Docs, on the Developer Keys page in Canvas, in the Canvas release notes, and sent to our LTI partners via newsletter.

If you have questions about this process, please contact Instructure support through the normal avenues, and be sure to mention LTI Platform Storage.

Who is behind this change?

The Interoperability (or Interop) team focuses on LTI in Canvas and enabling all of our 3rd-party tools and partners with LTI APIs, Developer Keys, and a few other tools like Live Events. We wanted to take this opportunity to introduce a couple of ourselves to the Canvas community!

My name is Alexis Nast, and I joined Instructure in January 2022. Before this, I worked as a middle school math teacher and then as a product manager at other software organizations. I’m the product manager for the Interop team, and I look forward to continuing to work closely with both schools and ed-tech integrators.

And I'm Xander Moffatt, a software engineer on the Interop team. I first joined Instructure in 2017 for an internship and never (really) left. I've been working on LTI-related code for a while now, and contributed to the Platform Storage spec as a member of the LTI working group.

LTI Platform Storage Overview and Support Update

Some browsers (as of writing, only Safari) block 3rd party cookies inside iframes - that is, cookies set on a domain that is different from the domain of the parent frame. The main reason for this change is to discourage tracking for ad/marketing purposes. This interrupts some LTI 1.3 functionality, including securing the two halves of the launch process together, and setting cookies as a tool inside an LTI iframe.

The LTI working group established the Platform Storage spec to let tools still accomplish these goals by treating the platform (in this case, Canvas) as a storage method for cookie-like data, using the window.postMessage API, the standard for cross-frame Javascript communication. This will help tools secure their launches, prevent MITM (man in the middle) attacks, and continue to function inside Canvas as they have in the past.

There is work required on the tool side to take advantage of these new APIs, mostly during the login and launch requests to store and retrieve the state parameter. There is a tool-side implementation guide that is part of the LTI spec, and for other information about using postMessage in Canvas, please see our API documentation.

Canvas supports almost all of the spec, with a few important exceptions. Until August 19, 2023 (July 17 for Beta), Canvas will not accept any messages that use the OIDC Auth URI origin as the target origin, which is an important part of securing these messages to provide the same end-to-end launch security as using a cookie to store the state parameter. After August 19, 2023 (July 17 for Beta), Canvas will conform fully to the spec in all regards. Details are laid out below, organized by the section of the specification they regard, as well as links to the various spec documents:

LTI Client Side postMessages

  • ➖ 2: Canvas supports most of this section, with some caveats below.
    • ✅ 2.2: target frame will be provided by the lti_storage_target body parameter in both login and launch requests, as well as in the response to the lti.capabilities postMessage. Until August 19, 2023 (July 17 for Beta), this value will be _parent or not present, which signifies that tools should use the parent frame. After then, the value will be post_message_forwarding, which signifies that tools should use the frame with that name.
    • ❌ 2.3.2: the OIDC Auth URI Origin will not be accepted as a target origin until August 19, 2023 (July 17 for Beta). Until then, tools should use the * target origin for all messages, which isn’t part of the spec.
  • ✅ 3: Canvas supports all request parameters and conforms to all response parameters and error codes in this section.
  • ✅ 4: Canvas supports the lti.capabilities message and response in its entirety. Until August 19, 2023 (July 17 for Beta), all returned subjects will not have a frame parameter, signifying that tools should send these messages to the parent frame. After then, the lti.get_data and lti.put_data subjects will have frame: 'post_message_forwarding' to signify that those messages should be sent to the frame with that name.
    • ❗Note that in a previous version of this spec, the subject for this message was org.imsglobal.lti.capabilities, and was simplified after IMS Global was renamed to 1EdTech. Canvas currently supports both formats, and will remove support for this previous format after August 19, 2023 (July 17 for Beta).

LTI postMessage Storage

  • ➖ 1: Canvas supports most of this section, with some caveats below.
    • ❌ 1.1.1.1: Until August 19, 2023 (July 17 for Beta), Canvas will not accept any messages with the OIDC Auth URI origin as its target origin. After then, Canvas will conform fully to this portion of the spec.
  • ✅ 2: Canvas conforms to all request and response message definitions for lti.get_data and lti.put_data.
    • ❗Note that in a previous version of this spec, the message subjects for this section were org.imsglobal.lti.get_data and org.imsglobal.lti.put_data, and were simplified after IMS Global was renamed to 1EdTech. Canvas currently supports both formats, and will remove support for this previous format after August 19, 2023 (July 17 for Beta).
  • ✅ 3: Canvas provides the minimum storage limits for each tool to use.
  • ✅ 4: Canvas uses localStorage as the backing for this API, which has no Time-to-Live. It does not encrypt any data before storing it. If tools wish their data to be encrypted, they should do it before storing it.

Implementation Guide

✅ 2.1: Canvas sends lti_storage_target as an extra body parameter in both the login and launch requests. Until August 19, 2023 (July 17 for Beta), this value will always be _parent, signifying that tools should send all messages to the parent frame. After then, the value will be post_message_forwarding, signifying that the Platform Storage messages should be sent to the frame with that name.

The content in this blog is over six months old, and the comments are closed. For the most recent product updates and discussions, you're encouraged to explore newer posts from Instructure's Product Managers.

47 Comments