oEmbed Token Guide

[karl]

Summary

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.

Audience

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.

Background

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:

/courses/<course id>/external_content/success/external_tool_dialog?return_type=oembed&url=<url>&endpoint=<endpoint>

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.

Create the JWT Body

jwt_body = {
 sub: params['user_id'],
 iss: params['oauth_consumer_key'],
 aud: "https://canvas.instructure.com",
 iat: Time.now.to_i,
 exp: Time.now.to_i + 5.minutes.seconds.to_i,
 url: 'https://www.oembed-example.edu/oembed-url',
 endpoint: 'https://www.oembed-example.edu/oembed-endpoint',
 jti: SecureRandom.uuid
}

Explanation of keys and values:

Key	Value
sub	Must be the current Canvas user LTI ID. This value is found in the standard “user_id” parameter from the LTI launch.
iss	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.
aud	Must be “https://canvas.instructure.com” in Canvas production instances. Must be “https://canvas.beta.instructure.com” in Canvas beta instances.
iat	The time at which the token was issued
exp	The time at which the token expires. We recommend five minutes or less.
url	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.
endpoint	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.

Create the JWT

jwt = JSON::JWT.new(jwt_body)

Sign the JWT

signed_jwt = jwt.sign(

 <shared secret string>,

 :HS256

)

The first argument to “sign” must be the shared secret associated with the consumer key used in the “iss” of the JWT body.

The second argument identifies what algorithm to use for signing. The algorithm used must be HS256

Add the Token to the Return URL

success_url = ".../success/external_tool_dialog?return_type=oembed&oembed_token=#{signed_jwt.to_s}"

Looking into the Future

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.

Migration Guidelines

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

Key Dates

oembed_token required in beta - Thursday, August 13, 2020

oembed_token required in production - Saturday, September 19, 2020