Instructure recently issued a security advisory for a “medium” level security issue around Canvas + oEmbed. To mitigate this issue, a breaking change to the Canvas oEmbed flow was made that validates the identity of the party requesting the retrieval of an oEmbed object.
This guide details the changes to Canvas, a release schedule, and what changes tool providers need to make to be ready.
This guide is only applicable to tool providers that use the oEmbed format to embed content in the Canvas rich content editor.
Tools who leverage the IMS Content Item or IMS Deep Linking specifications can safely ignore the changes described below.
oEmbed is a format used for embedding third-party content on a site. oEmbed is supported by Canvas LMS in the rich content editor LTI placement and allows LTI tools to return links, images, or rich content such as HTML fragments.
Historically this has been achieved when the launched LTI tool redirected the user agent to a return URL (given in the LTI launch) and sets the “return_type” parameter to “oembed”.
In that same request, “url” and “endpoint” parameters were sent to indicate to Canvas where the oEmbed object should be retrieved from:
Beginning September 19, 2020 a new token parameter will be required in this request for a tool to successfully embed content in Canvas via oEmbed (See “Key Dates” below). This parameter is named “oembed_token” and is a JWT constructed as shown below and signed with the tool’s shared secret.
Constructing a Token
For an introduction to JSON Web Tokens (JWTs) see the introduction page at jwt.io which also links to the RFC.
The following example illustrates creating the “oembed_token” using Ruby and the json-jwt gem. Similar libraries are available to help in the construction of this token for many other languages.
Must be the current Canvas user LTI ID. This value is found in the standard “user_id” parameter from the LTI launch.
The consumer key of the tool that was launched. The corresponding shared secret will later be used to sign the JWT. This value is found in the standard “oauth_consumer_key” parameter from the LTI launch.
The time at which the token expires. We recommend five minutes or less.
The oEmbed object URL. Should be the same value as the “url” parameter currently being set in the request to “/external_content/success/external_tool_dialog”. Should not be URL encoded. If no URL is given, an empty string should be used for this property.
The oEmbed object endpoint. Should be the same value as the “endpoint” parameter currently being set in the request to “/external_content/success/external_tool_dialog”. Should not be URL encoded. If no endpoint is given, an empty string should be used for this property.
Most capabilities offered by oEmbed are also offered in the IMS Deep Linking specification. We recommend LTI tool providers move to the IMS Deep Linking flow while upgrading from LTI 1.x to LTI 1.3. Doing so will ensure that tool providers can take advantage of new innovations currently available and coming in the future to IMS Deep Linking.
To facilitate migration to the new “oembed_token,” Canvas will provide a testing period where LTI tool providers may test in Canvas beta environments.
The presence of an “oembed_token” will not be required in Canvas production during this period. Canvas beta environments, however, will be updated to require an “oembed_token.” See “Key Dates” below for more details.
It’s recommended that tool consumers begin sending the “oembed_token” parameter alongside the current “url” and “endpoint” parameters in production before it becomes a requirement. Doing so will ensure a smooth transition on the “oembed_token required in production” date (see “key Dates” below).
oembed_token required in beta - Thursday, August 13, 2020
oembed_token required in production - Saturday, September 19, 2020