LTI User/enrollment provisioning and synchronization

[jpoulos]

Overview

One of the most common questions I'm asked when consulting our Canvas partners is how to synchronize the roster from Canvas into an external application. There are a variety of ways this can be accomplished, each with their advantages and disadvantages depending on the needs of your product and customers. This post is meant to be a resource for external tool providers hoping to maintain a synchronized roster between their systems and Canvas.

LTI-only Workflow

Requirements

This approach requires an LTI integration to be configured and visible somewhere within a Canvas course. Ideally, this LTI connection will already have an LTI SSO mechanism. If username, login ID, email, and/or SIS ID is required, make sure the privacy level is set to Public in the tool configuration. Otherwise, Canvas will only send an opaque LTI user id (as the user_id parameter) and a Canvas ID (as the custom_canvas_user_id).

Advantages

• API access not required
• Interoperable
• Can provision users on-the-fly as they launch the tool

Limitations/Challenges

• LTI tool is only aware of users who've launched their tool at least once
• Unidirectional: cannot push new enrollments to Canvas
• Cannot determine if users drop courses or are deleted from Canvas

Instructor/Admin/Student Workflow

1. Configure an LTI tool in Canvas
2. Launch the tool
3. Tool consumes user information (name, email, ID's, roles, contextual information etc...) and attempts to match on an ID. Best practice is to match on the user_id from the launch and then fall back to some other ID if a match is not found
4. If a match is confirmed (and the signature matches), let the user access their information in your application
5. If no match is found, either or send them through a user-creation flow within the iframe, or auto-create a user for them based on the information in Canvas (you may want to let them set a password at this point, or email them a registration URL)

LTI + API Workflow

The main limitation of the LTI-only workflow is that it requires users to launch the tool through the LMS. This often does not make sense. For example, some tools are used only by instructors, so there is no opportunity for the students to launch an LTI tool. The LTI + API workflow works best for tools targeting teachers or students, but is limited when synchronizing rosters for large accounts.

Requirements

This approach requires an LTI integration to be configured. It also must use OAuth2 to obtain instructor and student API tokens.

Advantages

• Can provision entire courses or sections with a teacher token, or entire accounts with an admin token
• Can remove/hide users that have dropped courses or have been deleted
• Bi-directional: if authorizing user has permissions, can create/update/delete enrollments within Canvas

Limitations/Challenges

• Requires implementation of OAuth2
• Requires heavy usage of Canvas-specific API’s making it not interoperable
• If attempting to sync entire accounts, can be slow for large accounts due to API throttling

Admin Workflow

1. Admin launches the tool from account navigation or elsewhere
2. Tool kicks off OAuth2 if it needs to obtain or refresh a token
3. Tool retrieves a list of courses via the accounts API, then uses the Enrollments API for each course
4. Tool can then create/update/delete users from their database based on the results

NOTE: This approach is not recommended for large accounts due to API throttling. Instead, either use the LTI + SIS + API approach in the next section or see the Instructor Workflow below.

Instructor Workflow

1. Instructor launches the tool from course navigation or elsewhere
2. Tool kicks off OAuth2 if it needs to obtain or refresh a token
3. Tool consumes the custom_canvas_api_domain and custom_canvas_course_id from the LTI launch and checks the Enrollments API for the course. Alternatively, the tool can check the enrollments for the instructor to sync all courses they are enrolled in; this requires consuming the custom_canvas_user_id
4. Tool can then create/update/delete users from their database based on the results

Student Workflow

1. Student launches the tool from the course
2. Tool kicks off OAuth2 if it needs to obtain or refresh a token
3. Tool consumes the custom_canvas_course_id from the LTI launch and checks the Enrollments API for the course

NOTE: Some students may not have permission to view the list of users in their course.

LTI + Reports API Workflow

The main limitation of the LTI + API workflow is that it doesn’t work well for large accounts. By using the Reports API, tools can generate reports that list all users in an account. This is best used for institutions who’ve implemented SIS, but it’s not a requirement.

Advantages

• Can provision entire accounts without worry of being throttled
• Can remove/hide users who have dropped courses or have been deleted
• Bi-directional: if authorizing user has permissions, can create/update/delete enrollments within Canvas via SIS Imports API

Limitations/Challenges

• Requires an admin-level token
• Best if institution has implemented SIS; SIS exports only show resources with SIS ID's. If SIS ID's are absent, you'll need to understand how to interpret the provisioning report
• Requires implementation of OAuth2
• Requires heavy usage of Canvas-specific API’s making it not interoperable
• Requires parsing CSV's and downloading files
• Requires understanding the structure of SIS CSV files or the provisioning report

Admin Workflow

1. Admin launches the tool from account navigation
2. Tool kicks off OAuth2 if it needs to obtain or refresh a token
3. Tool starts a report via API

NOTE: There are two reports of interest here. The easiest to interpret is the SIS Export report; however, the SIS Export report only shows users with SIS ID's. In this scenario, you’ll need to rely on the provisioning report instead.

1. Tool polls the report to check progress
2. When the report is complete, tool downloads the report and parses the data to synchronize users
3. Tool can then create/update/delete users from their database based on the results

Instructor/Student Workflow

Instructors and students don’t have access to the reports API. However, the same functionality of the LTI + API integration described in previous sections can still be used to compliment the LTI + Reports API workflow. For example, you may want to do a nightly sync at the account level, but still use API + LTI to synchronize data when a user launches the tool.

NOTE: Admins can also manually send reports to a tool provider for one-time provisioning of new customers; however, in order to maintain an accurate list of users and enrollments, the tool would still need to sync data via LTI and/or API.

NOTE: The workflows which leverage API can be further automated or simplified by obtaining an admin token with the “become other users” permission. This token can then be used to make API requests on behalf of teachers and students by appending as_user_id=<student/teacher user id>. However, this can be problematic for high numbers of assignments or students as you’ll likely experience throttling issues.

SIS-only Integrations

This won’t be discussed here. For more information about integrating with Canvas as a SIS provider, please contact: Chase Pendleton <cpendleton@instructure.com> (SIS Partnerships Manager)

Roadmap: LTI Names and Role Provisioning Services (Membership Service)

We’re currently working toward implementation of the IMS LTI Names and Role Provisioning Service. We hope to have most, if not all, of the service implemented by the end of 2018. This service will make the LTI-only workflow more useful for instructors in particular as it doesn’t require all users in a course to launch the tool, and it'll allow tools to be aware of changes in the course roster.

Requirements

The requirements are the same as the LTI-only workflow outlined above, but you must also conform to the IMS LTI Names and Role provisioning Service as a tool provider.

Advantages

• Does not require API access
• Can provision an entire course on-the-fly when an instructor or admin launches a tool from the course
• Interoperable

Limitations/Challenges

• Will not be able to synchronize an entire account
• Launch must occur in the context of a course
• Unidirectional: cannot push new enrollments to Canvas

Workflow

• User launches tool from course
• Canvas sends a service URL that a tool can use to see a full list of users for the course
• Tool can then create/update/delete users from their database based on the results

Concluding Remarks

This isn’t a comprehensive guide to solving the challenge of synchronizing users and enrollments between systems. I encourage creativity and product discovery with your customers to see how they envision your product working within Canvas. My hope is that this guide has at least allowed you to gain a better understanding of what is and isn’t possible so your organization can make decisions that help our mutual users have the greatest experience possible.

For those who’ve already solved this problem, how has your integration combined API and LTI to provision users from Canvas? Are there any interesting approaches you've taken that I haven’t considered here? Please share in the comments!


Jesse Poulos
Partner Integrations Specialist
Instructure