Instructure Developer Documentation Portal
Community
  • Introduction
  • Services
    • Elevate Standards Alignment - AB Connect API
      • Introduction
        • Authentication
        • Addressing Object Properties
        • Requesting Additional Properties in the Response
        • Filtering Using ODATA Like Statements
        • Sorting
        • Facets
        • Paging Data
        • Call Throttling
        • Working with Related Object
        • Error Responses
        • Character Set Support
        • How To Articles, Recommendations and Suggestions
        • Examples
        • Using AB Connect's Embeddable Widgets
      • Reference
        • Standards
        • Standard Collections
        • Events
        • Topics
        • Concepts
        • Assets
        • Asset Definitions
        • Asset Collections
        • Managing and Predicting Relationships
        • Providers
    • Canvas LMS
      • Basics
        • GraphQL
        • API Change Log
        • SIS IDs
        • Pagination
        • Throttling
        • Compound Documents
        • File Uploads
        • API Endpoint Attributes
        • Masquerading
      • OAuth2
        • OAuth2 Overview
        • OAuth2 Endpoints
        • Developer Keys
      • Resources
        • Access Tokens
        • Account Calendars
        • Account Domain Lookups
        • Account Notifications
        • Account Reports
        • Accounts
        • Accounts (LTI)
        • Admins
        • Analytics
        • Announcement External Feeds
        • Announcements
        • API Token Scopes
        • Appointment Groups
        • Assignment Extensions
        • Assignment Groups
        • Assignments
        • Authentication Providers
        • Authentications Log
        • Blackout Dates
        • BlockEditorTemplate
        • Blueprint Courses
        • Bookmarks
        • Brand Configs
        • Calendar Events
        • Collaborations
        • CommMessages
        • Communication Channels
        • Conferences
        • Content Exports
        • Content Migrations
        • Content Security Policy Settings
        • Content Shares
        • Conversations
        • Course Audit log
        • Course Pace
        • Course Quiz Extensions
        • Course Reports
        • Courses
        • Custom Gradebook Columns
        • Developer Key Account Bindings
        • Developer Keys
        • Discussion Topics
        • Enrollment Terms
        • Enrollments
        • ePortfolios
        • ePub Exports
        • Error Reports
        • External Tools
        • Favorites
        • Feature Flags
        • Files
        • Grade Change Log
        • Gradebook History
        • Grading Period Sets
        • Grading Periods
        • Grading Standards
        • Group Categories
        • Groups
        • History
        • InstAccess tokens
        • JWTs
        • Late Policy
        • Learning Object Dates
        • Line Items
        • LiveAssessments
        • Logins
        • LTI Launch Definitions
        • LTI Registrations
        • LTI Resource Links
        • Media Objects
        • Moderated Grading
        • Modules
        • Names and Role
        • New Quiz Items
        • New Quizzes
        • New Quizzes Accommodations
        • New Quizzes Reports
        • Notification Preferences
        • Originality Reports
        • Outcome Groups
        • Outcome Imports
        • Outcome Results
        • Outcomes
        • Pages
        • Peer Reviews
        • Planner
        • Poll Sessions
        • PollChoices
        • Polls
        • PollSubmissions
        • Proficiency Ratings
        • Progress
        • Public JWK
        • Quiz Assignment Overrides
        • Quiz Extensions
        • Quiz IP Filters
        • Quiz Question Groups
        • Quiz Questions
        • Quiz Reports
        • Quiz Statistics
        • Quiz Submission Events
        • Quiz Submission Files
        • Quiz Submission Questions
        • Quiz Submission User List
        • Quiz Submissions
        • Quizzes
        • Result
        • Roles
        • Rubrics
        • Sandboxes
        • Score
        • Search
        • Sections
        • Services
        • Shared Brand Configs
        • SIS Import Errors
        • SIS Imports
        • SIS Integration
        • Smart Search
        • Submission Comments
        • Submissions
        • Tabs
        • Temporary Enrollment Pairings
        • User Observees
        • Users
        • What If Grades
      • Outcomes
        • Outcomes CSV Format
      • Group Categories
        • Group Categories CSV Format
      • SIS
        • SIS CSV Format
      • External Tools
        • LTI
          • Introduction
          • Registration
          • Launch Overview
          • Configuring
          • Variable Substitutions
          • Deep Linking
          • Grading
          • Provisioning
          • PostMessage
          • Platform Notification Service
          • Placements
            • Placements Overview
            • Navigation
            • Homework Submission
            • Editor Button
            • Migration Selection
            • Link Selection (Modules)
            • Assignment Selection
            • Collaborations
        • xAPI
        • Canvas Roles
        • Plagiarism Detection Platform
          • Overview
          • Plagiarism Detection Platform Assignments
          • Plagiarism Detection Platform Users
          • Plagiarism Detection Submissions
          • Webhooks Subscriptions for Plagiarism Platform
          • JWT Access Tokens
      • Data Services
        • Live Events
          • Overview
            • Introduction
            • Setup
            • Caliper
            • Metadata
          • Event Format
            • Canvas
              • Account
              • Asset
              • Assignment
              • Attachment
              • Content
              • Conversation
              • Course
              • Discussion
              • Enrollment
              • Grade
              • Group
              • Learning
              • Logged
              • Module
              • Outcome
              • Outcomes
              • Plagiarism
              • Quiz
              • Rubric
              • Sis
              • Submission
              • Syllabus
              • User
              • Wiki
            • Caliper IMS 1.1
              • Assessment
              • Basic
              • Forum
              • Grading
              • Navigation Events
              • Session
    • Catalog
      • APIs
        • Analytics
        • Bulk Enrollments
        • Catalogs
        • Certificates
        • Completed Certificates
        • Courses
        • Email Domain Set
        • Enrollments
        • Orders
        • Programs
        • Progresses
        • Tags
        • User Registrations
        • Users
        • Waitlist Applicants
    • Credentials
      • Getting Started
      • Authentication
        • Password-Based Authentication
        • Authorization Code-Based Authentication
      • Pagination
      • APIs
        • Assertions
        • Backpack
        • Badgeclasses
        • Issuers
        • Organizations
        • Users
      • Release Notes
    • Data Access Platform
      • Key Concepts
      • Data Formats
      • Rate Limits & Policies
      • Datasets
        • Namespaces
          • canvas
            • canvas types
          • canvas_logs
          • catalog
        • Additional Notes
        • Entity Relationship Diagram
      • Query API
        • Authentication
        • Reference
      • Command Line (DAP CLI)
        • Getting Started
        • Secure Connection
        • Reference
          • dap snapshot
          • dap incremental
          • dap list
          • dap schema
          • dap initdb
          • dap syncdb
          • dap dropdb
      • Client Library
        • Examples
        • Reference
      • Release Notes
      • Status
    • DataSync
      • Interop API
      • Interop Data API
      • Grades Exchange API
      • OneRoster API
      • Platform API
    • Instructure Media
      • Studio API
    • Quizzes
      • Quiz API
Powered by GitBook
On this page
  • Step 1: Login Initiation
  • Step 2: Authentication Request
  • Step 3: Authentication Response (LTI Launch)
  • Step 4: Resource Display
  • Launching without Cookies

Was this helpful?

  1. Services
  2. Canvas LMS
  3. External Tools
  4. LTI

Launch Overview

PreviousRegistrationNextConfiguring

Last updated 1 month ago

Was this helpful?

Copyright © 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.

The IMS Security Framework uses anOpen ID Connect (OIDC) third-party flow. You'll want to read these specifications in detail, but the following is a Canvas-specific summary:

Step 1: Login Initiation

Canvas initiates a login request to the oidc_initiation_url that is . This request contains an issuer identifier (iss) to recognize that Canvas is launching the tool. As the issuer, Instructure-hosted Canvas instances all use the following, regardless of the specific account domain(s) that the tool was launched from:

  • https://canvas.instructure.com (Production environment launches)

  • https://canvas.beta.instructure.com (Beta environment launches)

  • https://canvas.test.instructure.com (Test environment launches)

On self-hosted Canvas, the iss value must be updated to your Canvas instance's hostname in the config/security.yml file, as the default is https://canvas.instructure.com.

The request also includes a login_hint that is passed in the next step. Last, the request include the target_link_uri that has been configured on the Developer key; this is later used by the tool as a recommended final redirect.

Parameter
Description

iss

The issuer, as described above.

login_hint

Opaque value that must be passed back to Canvas in the next step.

target_link_uri

The recommended final redirect for the tool; not required.

client_id

The OAuth2 client id, or Developer Key id, for convenience.

deployment_id

Unique identifier for the specific deployment of this tool, for convenience.

canvas_region

For hosted Canvas, the AWS region (e.g. us-east-1) in which the institution that provided this token resides. For local or open source Canvas, this will have a value of "unknown". This field is safe to ignore. This can be used for tools that are hosted in multiple regions to launch to one url and redirect to the correct region.

canvas_environment

For hosted Canvas, the environment (e.g. "production", "beta", or "test") from which the tool is being launched. For local or open source Canvas, this will have a value of "production". This field is safe to ignore. Tools can use this to redirect to beta- or test-specific instances of their tool on launch. This is in place of the LTI 1.1 `environments` tool config option, which is not recognized for 1.3 tools.

Step 1.5: Optional Tool-to-tool Redirect

There are situations where a tool wants to use a region-specific or environment-specific instance of itself to respond to the LTI launch, like keeping traffic within the same region as the instance of Canvas, or using a different domain or even launch URL when launched from beta Canvas vs normal production.

Tools can use the canvas_region or canvas_environment parameters specified above, or even the Canvas URL from the request's referrer, to decide if they want to redirect.

Example of redirecting to a different domain based on region and environment:

  • Login request is made to the tool's OIDC initiation URL, mytool.net/login, and contains canvas_region: us-west-2, canvas_environment: beta.

  • The tool redirects to beta-pdx.mytool.net/login, forwarding all of the request parameters.

  • The beta-pdx instance of the tool responds by continuing on to Step 2 below.

Example of redirecting to a different launch URL based on environment:

  • Login request is made to the tool's OIDC initiation URL, mytool.net/login, and contains canvas_environment: beta, target_link_uri: mytool.net/launch.

  • The tool continues on to Step 2 below, but sends redirect_uri: mytool.net/beta_launch instead of using the target_link_uri.

Tools that wish to utilize this redirect need to make sure that all possible initiation URLs, whether the domains or paths vary, are added to the redirect URIs list on their corresponding Developer Key, so that the auth request in Step 2 succeeds.

Tools that utilize different instances for beta and test must also make sure that they are storing the correct corresponding values for Canvas URLS like the OIDC Auth URL, JWKs URL, and the Issuer/iss, and that they use the beta or test versions of all of those URLs when the tool is launched from beta or test Canvas.

Step 2: Authentication Request

To complete authentication, tools are expected to send back an authentication request to an "OIDC Authorization end-point". This can be a GET or POST, however, this request needs to be a redirect in the user’s browser and not made server to server as we need to validate the current user's session data. For cloud-hosted Canvas, regardless of the domain used by the client, the endpoint is always:

  • https://sso.canvaslms.com/api/lti/authorize_redirect (if launched from a production environment)

  • https://sso.beta.canvaslms.com/api/lti/authorize_redirect (if launched from a beta environment)

  • https://sso.test.canvaslms.com/api/lti/authorize_redirect (if launched from a test environment)

    The domain for this endpoint used to be https://canvas.instructure.com. The impetus for this change and other exact details are described in this Canvas Community article. Tools wishing to implement the Platform Storage spec are required to use the new domain for this endpoint, and all other tools should update this endpoint in their configuration store as soon as possible. This change will eventually be enforced, but for now is not a breaking change - the old domain will continue to work. Any questions or issues are either addressed in the linked article or can be filed as a standard support/partner support case, referencing the OIDC Auth endpoint change.

Among the required variables the request should include:

  • a redirect_uri, which must match at least one configured on the developer key.

  • the same login_hint that Canvas sent in Step 1.

  • a state parameter the tool will use to validate the request in Step 4.

Step 3: Authentication Response (LTI Launch)

Step 4: Resource Display

The tool then validates the state parameter matches the one sent in Step 2 and redirects the User Agent to the target_link_uri that was sent in Step 1 (or some other location of its choice) to display the final resource. This redirect occurs in an iframe unless the tool is configured otherwise.

Launching without Cookies

Safari blocking cookies inside 3rd-party iframes made it necessary to create a workaround for storing the state property between the login and launch requests, to prevent MITM attacks. The newly finalized LTI Platform Storage spec provides a way for tools that are launching in Safari or another situation where cookies can't get set to still store data across requests in a secure fashion. Tools can send window.postMessages to Canvas asking it to store and retrieve arbitrary data, which acts as a cookie-like proxy.

The LTI Platform Storage spec includes an implementation guide which needs to be the primary resource for implementing this, though a brief usage overview is included below.

Support for this API is determined by either:

  1. the presence of the lti_storage_target as an extra body parameter in both the login (Step 1) and launch (Step 3) requests, or

  2. a response postMessage to the lti.capabilities postMessage that contains the lti.get_data and lti.put_data subjects.

If the lti_storage_target parameter is absent, or the tool doesn't receive a response postMessage for lti.capabilities, then the tool should not attempt to use this API and should fall back to cookies to verify the launch state parameter.

When the tool sees either of the above signals that Canvas supports this API, then:

  1. In Step 2, instead of storing the state parameter in a cookie the tool should store it in Canvas's LTI Platform Storage using the lti.put_data postMessage. It's recommended that the key include the value (eg key: "state-1234", value: "1234") to avoid any collisions during multiple launches, and to make recovering the value easy.

  2. In Step 4, instead of comparing the state parameter to the stored value in the cookie, the tool should retrieve it using the lti.get_data postMessage. Since this comparison has to happen in Javascript instead of on the server, the tool should render something, then check these values. If the values don't match, the tool can then log the user out or render an error.

According to the spec, the target origin for these postMessages must be the OIDC Auth domain (e.g. https://sso.canvaslms.com). Since every institution's domain varies, Canvas renders a frame at this domain that will respond to postMessages, and the name of this frame is supplied in the lti_storage_target parameter, provided as a body parameter in both login and launch requests. Tools should send their lti.put_data and lti.get_data postMessages to that frame, but can continue to send all other postMessage types to the parent window.

The LTI Platform Storage spec docs:

  • LTI OIDC Login with LTI Client Side postMessages

  • Client-side postMessages

  • postMessage Platform Storage

  • Canvas postMessage documentation


This documentation is generated directly from the Canvas LMS source code, available on Github.

Using the oidc_initiation_urls option described can also produce a similar outcome while removing the need for the tool to perform an internal redirect.

a client_id that matches the developer key. This must be before the launch occurs.

Canvas will use the client_id to lookup which developer key to use and then check the redirect_uri that was sent in the previous step and ensure that there is a exact-matching redirect_uri on the developer key. Canvas then sends its authentication response to the redirect_uri that the tool provided in Step 2. The request will include an id_token which is a signed JWT containing the LTI payload (user identifiers, course contextual data, custom data, etc.). Tools must validate the request is actually coming from Canvas using .

configured on the LTI developer key
in the JSON tool config
registered in the tool
Canvas' public JWKs