This document contains drafts for all educator and site operator documentation related to using Open edX as an LTI Tool Provider.

Items marked [VERIFY] need confirmation against the codebase by Claude Code.

EDUCATOR DOCS

1. Using Open edX as an LTI Tool Provider

Diataxis type: concept Tags: educator, concept Status: Major rewrite of existing doc

Open edX can act as an LTI tool provider, allowing you to deliver Open edX course content inside another LMS such as Canvas, Blackboard or any system that supports the LTI standard.

When Open edX acts as an LTI provider, learners interact with Open edX content directly within their primary LMS. The two systems communicate behind the scenes to handle authentication, track learner progress, and synchronize grades.

The LTI provider functionality supports LTI 1.1 only.

How it works

At a high level, the workflow involves three roles:

1. Site operator: Enables LTI provider functionality on the Open edX instance and creates LTI 1.1 credentials for external LMS. See Configuring an Open edX Instance as an LTI Tool Provider (site operator docs).

2. Educator: Identifies the Open edX course content to share, constructs LTI URLs for that content, and adds LTI 1.1 configuration along with those URLs to the external LMS.

3. Learner accesses the Open edX content from within the external LMS.

Grading

When you include problem components from a graded subsection in an external LMS, Open edX grades the learner responses and transfers the scores back to the external LMS.

• If the LTI link points to an individual problem component, Open edX returns the grade for each learner shortly after they submit an answer.

• If the LTI link points to a unit or subsection containing multiple problems, Open edX aggregates the grades and returns them after a configurable delay (15 minutes by default). This aggregation reduces the number of grade update notifications sent to the external LMS.

Note the following requirements for grading to work:

• The problem component must be in a graded subsection of your course.

• Your external LMS may have additional requirements. For example, in Canvas, the LTI URL of a problem component must be added to the Assignments section of a course, or to a module item that points to an assignment. The user who launches the LTI material must be eligible to receive a grade (that is, a learner, not a TA or course designer).

Authentication Modes

The Open edX system supports three authentication modes for learners accessing content via LTI. Your site operator configures these via the LTI Consumer settings in Django admin. The mode determines how learner accounts are created and managed on the Open edX system.

Anonymous (default): The first time a learner encounters Open edX content from the external LMS, the Open edX system automatically creates a user account with a random username and a generated email address. The learner does not interact with the Open edX system directly and may not even be aware that Open edX is involved. No personally identifiable information is stored. This mode provides the most seamless experience.

Auto-create with personal information: When the "Use lti pii" option is enabled, the Open edX system creates a user account using the learner's real name and email address from the LTI launch data. If a user with the same email already exists on the Open edX system, the existing account is linked automatically rather than creating a duplicate. This mode is useful when you need to identify learners or associate their LTI activity with an existing Open edX account.

Require existing account: When the "Require user account" option is enabled, the learner must already be logged into the Open edX instance in the same browser. If the learner is not logged in, they see an error page with a link to the Open edX login page. After signing in, they can return to the LTI content. This mode is useful when learners must have pre-existing accounts on the Open edX system.

If both "Use lti pii" and "Require user account" are enabled, "Require user account" takes precedence and "Use lti pii" is ignored.

What You Need from Your Site Operator

Before you can configure your external LMS to consume Open edX content, you need the following from your site operator:

• Consumer key: A unique identifier for the external LMS. Your site operator creates this when configuring the LTI consumer in Django admin.

• Consumer secret: A shared secret used to authenticate the LTI connection. Created alongside the consumer key.

You will enter these values into your external LMS when setting up the LTI integration. In addition, you will need the LTI URL for each piece of Open edX content you want to deliver — you construct these yourself using the course ID and usage ID. See Determine Content Addresses for LTI.

Limitations

Not all Open edX content types work well when delivered via LTI. For details on which component types are compatible, see Content Compatibility for LTI (reference).

[VERIFY: Add any other known limitations — e.g., mobile browser support, third-party cookie requirements for iframe embedding.]

See Also

• Determine Content Addresses for LTI (how-to)

• Content Compatibility for LTI (reference)

• Use Open edX as an LTI Provider to Canvas (how-to)

• Use Open edX as an LTI Provider to Blackboard (how-to)

• Configuring an Open edX Instance as an LTI Tool Provider (site operators)

2. How-to: Determine Content Addresses for LTI

Diataxis type: how-to Tags: educator, how-to Status: Cleanup of existing doc — fix broken directives, verify methods still work

Overview

To include Open edX course content in another system, you construct an LTI URL that identifies the specific content. This URL combines a course ID and a usage ID that you find in the Open edX LMS.

You might find using a spreadsheet helpful to organize the course ID and usage IDs for the content you want to include.

Find the Course ID

The course ID has the format {key type}:{org}+{course}+{run}, for example, course-v1:OpenedX+DemoX+2024.

To find the course ID:

1. In your Open edX LMS, open your course.

2. In the URL shown by your browser, find the course ID.

For example, the URL https://training.openedx.io/courses/course-v1:OpenedX+DemoX+Demo_Course/about contains the course ID course-v1:OpenedX+DemoX+Demo_Course.

The same course ID applies to every item of content in the course.

Note: Courses created before Fall 2014 may use an older format: {org}/{course}/{run}, for example, OpenedX/DemoX/2014.

Find the Usage ID for Course Content

The usage ID identifies a specific component, unit, or subsection. It has the format {key type}:{org}+{course}+{run}+type@{type}+block@{display name}, for example, block-v1:OpenedX+DemoX+Demo_Course+type@sequential+block@basic_questions.

The following terms in the usage ID indicate the level of the content:

You must have the Staff or Admin role in a course to find usage IDs.

Note: Courses created before Fall 2014 may use an older usage ID format: i4x:;_;_{org};_{course};_{type};_{display name}.

View Staff Debug Info for the Usage ID

To find the usage ID for a unit or component in the LMS:

1. In your Open edX LMS, open the course.

2. Go to the page that contains the unit or component.

3. Select Staff Debug Info.

4. For a component, find the location value.

5. For a unit, scroll down to find the parent value.

The usage ID begins with block-v1.

Note: For courses created before Fall 2014, the usage ID begins with i4x://.

[VERIFY: Does Staff Debug Info still work in the Learning MFE? The existing doc has a note saying the "View Page Source" method for data-usage-id may not work in recent versions. Confirm which methods are currently reliable.]

View the Page Source for the Usage ID

To find the usage ID for a subsection, unit, or component, you can view the HTML page source and search for data-usage-id.

[VERIFY: Does this method still work with the Learning MFE? The existing doc has an inline note saying "This step needs review because is not working in the last versions of the Open edX platform." Confirm and either fix or remove this method.]

Construct the LTI URL

The LTI URL has the following format:

https://{host}/lti_provider/courses/{course_id}/{usage_id}

Examples:

• Subsection (sequential): https://openedx-lti.org/lti_provider/courses/course-v1:OpenedX+01-2024+2024-1/block-v1:OpenedX+01-2024+2024-1+type@sequential+block@4e1de5e13fc3422997fe246b40a43aa1

[VERIFY: The existing doc shows subsection URLs with both a sequential and a vertical block ID appended. Is the vertical block ID required when linking to a subsection, or is just the sequential sufficient? Check the lti_provider/urls.py to see what URL patterns are accepted.]

• Unit (vertical): https://openedx-lti.org/lti_provider/courses/course-v1:OpenedX+01-2024+2024-1/block-v1:OpenedX+01-2024+2024-1+type@vertical+block@78b75020d3894fdfa8b4994f97275294

• Text component (html): https://openedx-lti.org/lti_provider/courses/course-v1:OpenedX+01-2024+2024-1/block-v1:OpenedX+01-2024+2024-1+type@html+block@f9f3a25e7bab46e583fd1fbbd7a2f6a0

See Also

• Using Open edX as an LTI Tool Provider (concept)

• Content Compatibility for LTI (reference)

• Use Open edX as an LTI Provider to Canvas (how-to)

• Use Open edX as an LTI Provider to Blackboard (how-to)

3. Reference: Content Compatibility for LTI

Diataxis type: reference Tags: educator, reference Status: Renamed from "Planning for Content Reuse (LTI)" — updated framing, verify table

Overview

Not all Open edX content types and features work well when delivered via LTI to an external LMS. The following table summarizes compatibility.

[VERIFY: Review this entire table against the current platform. Are there newer component types (e.g., Open Response Assessment, drag-and-drop v2) that should be added? Has anything changed for the items listed?]

Considerations

When selecting content to deliver via LTI, keep the following in mind:

• Discussion components can be confusing for learners in an LTI context because learners may be identified by internally assigned IDs rather than their usernames. Consider using the discussion features in your external LMS instead.

• Features that create groups of learners based on their IDs, such as content experiments and cohorts, are not designed for external use. Set up these features in your external LMS if you need them.

• Course content appears in the external LMS regardless of the start, end, or enrollment dates defined in the Open edX course. This ensures uninterrupted availability.

• Only published content appears in an external LMS. The "Hide from students" visibility setting for sections, subsections, and units does not affect LTI visibility — only the publication status of a unit controls whether content is included.

• You can deliver content from any course on your Open edX instance. Some organizations choose to maintain a dedicated copy of a course specifically for LTI delivery, but this is an operational choice, not a technical requirement.

See Also

• Using Open edX as an LTI Tool Provider (concept)

• Determine Content Addresses for LTI (how-to)

4. How-to: Use Open edX as an LTI Provider to Canvas (Example)

Diataxis type: how-to Tags: educator, how-to Status: Minor updates to existing doc

Note: This example relies on a third-party tool. Because this tool is subject to change by its owner, the steps and illustrations provided here are intended as guidelines and not as exact procedures.

To use Open edX course content in the Canvas LMS, you add a new app to the course and then add external tool module items.

Before you begin, obtain the consumer key and consumer secret from your site operator, and determine the LTI URL for the content you want to include. See Determine Content Addresses for LTI.

1. In Canvas, select your course. In Settings, select Add New App.

2. Enter the Consumer Key and Consumer Secret provided by your site operator. [VERIFY: Are the existing screenshots still representative of the current Canvas UI? Images referenced: lti_edit_external_app_Canvas.png, lti_edit_problem_Canvas.png, lti_canvas_example2.png]

3. In Modules, add a new External Tool item. The URL is the LTI URL that you determined for your course content.

4. Review the content to verify that it appears as you expect.

See Also

• Using Open edX as an LTI Tool Provider (concept)

• Determine Content Addresses for LTI (how-to)

• Content Compatibility for LTI (reference)

• Use Open edX as an LTI Provider to Blackboard (how-to)

5. How-to: Use Open edX as an LTI Provider to Blackboard (Example)

Diataxis type: how-to Tags: educator, how-to Status: Existing doc — flag unverified status

Note: This feature has not been recently tested with Blackboard. However, it works as of Teak with Canvas.

Note: This example relies on a third-party tool. Because this tool is subject to change by its owner, the steps and illustrations provided here are intended as guidelines and not as exact procedures.

To use Open edX course content in the Blackboard LMS, you add a new app to the course and then add external tool module items.

Before you begin, obtain the consumer key and consumer secret from your site operator, and determine the LTI URL for the content you want to include. See Determine Content Addresses for LTI.

1. In Blackboard, select your course.

2. From the course control panel, select Customizations. In the Tool Availability section, verify that the LTI tool has been enabled.

3. Open a Content Area page, and from the Build Content menu select Web Link.

4. On the Create Web Link page, enter an identifying name, the consumer key, the consumer secret, and the LTI URL for the course content.

5. Review the content to verify that it appears as you expect.

See Also

• Using Open edX as an LTI Tool Provider (concept)

• Determine Content Addresses for LTI (how-to)

• Content Compatibility for LTI (reference)

• Use Open edX as an LTI Provider to Canvas (how-to)

6. NEW — Reference: Troubleshooting LTI Provider Issues

Diataxis type: reference Tags: educator, reference Status: New document — needs Claude Code input for common issues

[VERIFY: Review the lti_provider app code, error handling, and community forum posts to identify common issues. The following are likely candidates based on the existing docs and general LTI knowledge.]

Content Not Appearing

• Verify that the content is published in Open edX. Only published content is available via LTI.

• Verify that the LTI URL is correctly constructed. See Determine Content Addresses for LTI.

• Check that the LTI provider functionality is enabled on the Open edX instance. Contact your site operator.

Grades Not Syncing

• Verify that the problem component is in a graded subsection.

• If linking to a unit or subsection, grades may be delayed by up to 15 minutes (or the configured aggregation interval).

• In Canvas, verify that the LTI URL is added to the Assignments section or a module item that points to an assignment.

• The user launching the LTI material must be eligible to receive a grade (a learner, not a TA or course designer).

[VERIFY: What does the lti_provider outcomes.py do when grade passback fails? Are there logs the educator or site operator can check?]

Learner Sees Login Page Unexpectedly

• If the site operator has enabled "Require user account" on the LTI consumer, learners must be logged into Open edX in the same browser. If they are not, they will see an error page with a login link.

• If using the "Require User Account" flag, the LTI consumer must send the learner's email via the lis_person_contact_email_primary POST attribute.

Content Appears Broken in iframe

[VERIFY: What are the current iframe/cookie requirements? The configure_lti.rst doc mentions SESSION_COOKIE_SAMESITE, CSRF_COOKIE_SAMESITE, and X_FRAME_OPTIONS settings. Are there additional browser-specific issues (e.g., Safari blocking third-party cookies by default)?]

• Modern browsers increasingly block third-party cookies, which can prevent Open edX content from loading correctly in an iframe within another LMS. Contact your site operator to verify that cookie and frame settings are correctly configured.

See Also

• Using Open edX as an LTI Tool Provider (concept)

• Configuring an Open edX Instance as an LTI Tool Provider (site operators)

SITE OPERATOR DOCS

7. Index: Configuring an Open edX Instance as an LTI Tool Provider

Diataxis type: (index page, no Diataxis tag) Tags: site operator Status: Minor updates to existing doc

You can configure your Open edX instance to be a Learning Tools Interoperability (LTI) provider to other systems and applications. You can use this LTI capability to present content from an Open edX course in any application that is configured to be a consumer of that content.

The LTI provider functionality supports LTI 1.1 only. LTI 1.3 is not supported in provider mode.

After you enable your Open edX instance as an LTI tool provider and configure credentials for the tool consumers, course teams can deliver Open edX course content in external LMSs.

This section includes the following topics:

• Enable LTI Provider Functionality (how-to)

• Configure Credentials for a Tool Consumer (how-to)

• Define an Interval for Grade Aggregation (how-to)

• Options for LTI Authentication and User Provisioning (concept)

• LTI Provider Configuration Settings (reference)

For information about how course teams set up content for delivery via LTI, see Using Open edX as an LTI Tool Provider in the educator documentation.

See Also

• Configure Credentials for a Tool Consumer

• Using Open edX as an LTI Tool Provider (educators)

8. How-to: Enable LTI Provider Functionality

Diataxis type: how-to Tags: site operator, how-to Status: Needs Tutor instructions added

LTI provider functionality is provided in the lti_provider app, located in edx-platform/lms/djangoapps/lti_provider.

[VERIFY: Is ENABLE_LTI_PROVIDER still required? Is it enabled by default in any recent release? How is it configured in Tutor-based deployments (plugin setting, YAML patch, etc.)?]

Native Installation

By default, the lti_provider app is not enabled. To enable this functionality, follow these steps.

1. In the edx/app/edxapp/lms.yml file, add the following line to the features section:

   "FEATURES" : {
       ...
       "ENABLE_LTI_PROVIDER": true
   }

2. Save the file.

3. Run database migrations.

4. Restart the LMS server.

Tutor-based Installation

[VERIFY: Provide the correct Tutor-specific instructions for enabling ENABLE_LTI_PROVIDER. This likely involves a Tutor plugin or a YAML config patch.]

Verify the Feature Is Enabled

To verify that the LTI provider functionality is enabled, check for the presence of the following database tables:

lti_provider_gradedassignment
lti_provider_lticonsumer
lti_provider_ltiuser
lti_provider_outcomeservice

If these tables are not present, check that the migrations have run properly.

[VERIFY: Are there additional database tables in the current codebase? Check the lti_provider models.py.]

9. How-to: Configure Credentials for a Tool Consumer

Diataxis type: how-to Tags: site operator, how-to Status: Mostly good — verify cookie and iframe settings

For each external LMS that you want to allow access to your Open edX instance as an LTI tool consumer, you create OAuth1 credentials and configure your Open edX instance to allow access. Each external LMS must have separate credentials.

After you complete the configuration on your Open edX system, you can add the consumer credentials to your external LMS.

Configure the Tool Consumer

1. Sign in to the Django administration console for your base URL. For example, http://{your_URL}/admin.

2. In the LTI Provider section, next to LTI Consumers select Add.

3. Enter the following information:

   • Consumer Name: An identifying name for the tool consumer.

   • Consumer Key: The console generates a unique key value. Alternatively, you can use an external application to generate the key.

   • Consumer Secret: The console generates a unique secret value. Alternatively, you can use an external application to generate the secret.

   Important: Do not supply a value for the Instance guid field. The tool consumer generates and supplies a globally unique identifier.

   • Use lti pii: When checked, the Open edX system uses personal information from the LTI launch data (name and email) to create the learner's account. If a user with the same email already exists on the Open edX system, the existing account is linked automatically. When unchecked (default), anonymous accounts are created with random usernames and generated email addresses.

     Note: The LTI consumer must be configured to send learner PII in the launch request. The relevant LTI parameters are lis_person_contact_email_primary, lis_person_name_full (or lis_person_name_given and lis_person_name_family).

   • Require User Account: When checked, the LTI content is available only to learners who are already logged into the Open edX instance in the same browser. If the learner is not logged in, they see an error page with a link to the Open edX login page.

     Important: If both "Use lti pii" and "Require user account" are checked, "Require user account" takes precedence and "Use lti pii" is ignored.

     With this flag checked, the LTI content embedded in iframes requires the following Django configuration: [VERIFY: Are these cookie and iframe settings still correct? In particular:

     • Is SESSION_COOKIE_SAMESITE_FORCE_ALL still a valid setting?

     • X_FRAME_OPTIONS = "ALLOW-FROM" is deprecated in modern browsers in favor of Content-Security-Policy: frame-ancestors. Is this guidance still correct, or should it be updated?

     • Are there any additional settings needed for current browser requirements?]

python

     # Needed for passing user session with the LTI Request
     SESSION_COOKIE_SAMESITE = 'None'
     SESSION_COOKIE_SECURE = True
     SESSION_COOKIE_SAMESITE_FORCE_ALL = True
     CSRF_COOKIE_SECURE = True
     CSRF_COOKIE_SAMESITE = 'None'

     # Needed for showing pages in iframe
     X_FRAME_OPTIONS = "ALLOW-FROM <your-lti-consumer-domain>"

 Caveats:

 - Setting this flag only associates future interactions of the learner. It cannot be used to migrate data from existing anonymous accounts to corresponding user accounts.
 - Unchecking the flag will not roll back auto-linked users. If rollback is needed, create a new LTI consumer with this flag turned off and use the new credentials in the LTI consumer application.

4. Select Save.

See Also

• Configuring an Open edX Instance as an LTI Tool Provider

10. How-to: Define an Interval for Grade Aggregation (Optional)

Diataxis type: how-to Tags: site operator, how-to Status: Fix file reference bug, add Tutor instructions

When an external LMS links to problem components in a graded Open edX subsection, the Open edX system grades the answers and transfers the grades back to the external LMS.

• If the link is to an individual problem component, the grade is returned immediately.

• If the link is to a unit or subsection, you can configure a delay before returning grades. The system aggregates all problems in the unit or subsection that the learner answers during that interval. Aggregating grades reduces the number of notification messages that learners receive.

By default, grades are aggregated every 15 minutes.

Change the Aggregation Interval

[VERIFY: The existing doc says to edit edx/app/edxapp/lms.yml but then says to save /lms/envs/common.py — these are two different files. Where is LTI_AGGREGATE_SCORE_PASSBACK_DELAY actually defined and how should it be overridden? Also provide Tutor-specific instructions.]

1. In edx/app/edxapp/lms.yml, change the value for the following parameter:

   LTI_AGGREGATE_SCORE_PASSBACK_DELAY = 15 * 60

You specify a time value in seconds.

2. Save the file.

3. Restart the LMS processes so that the updated configuration is loaded.

11. Concept: Options for LTI Authentication and User Provisioning

Diataxis type: concept Tags: site operator, concept Status: Major rewrite — now describes three actual modes from code

When you use your Open edX system as an LTI tool provider, data is collected for all learner activity. Each learner has a user account on the Open edX system that is linked to the user account on the tool consumer system, so that activity, grades, and state can be passed between systems.

The Open edX system supports three authentication modes for LTI, all configured on the LTI Consumer in Django admin (under LTI Provider > LTI Consumers). These modes control how learner accounts are created when a learner accesses Open edX content from an external LMS.

Anonymous User Authentication (Default)

When both "Use lti pii" and "Require user account" are unchecked, the Open edX system automatically creates an anonymous user account the first time a learner encounters Open edX content. The account has a randomly generated username and a generated email address. No personally identifiable information is stored. The learner never interacts with the Open edX system directly and may not be aware that Open edX is involved.

This mode presents a virtually seamless experience and requires no additional configuration beyond setting up the LTI consumer credentials.

Auto-create with Personal Information

When "Use lti pii" is checked, the Open edX system creates a user account using the learner's real name and email address from the LTI launch data. If a user with the same email already exists on the Open edX system, the existing account is linked to the LTI consumer automatically rather than creating a duplicate.

This mode requires the LTI consumer (external LMS) to be configured to send learner personal information in the launch request. The relevant LTI parameters are lis_person_contact_email_primary, lis_person_name_full (or lis_person_name_given and lis_person_name_family).

Require Existing Account

When "Require user account" is checked, the learner must already be logged into the Open edX instance in the same browser. If the learner is not logged in, they see an error page with a link to the Open edX login page. After signing in separately, the learner can return to the LTI content in the external LMS.

This mode is useful when you need to associate LTI interactions with pre-existing Open edX accounts rather than auto-created ones.

If both "Use lti pii" and "Require user account" are checked, "Require user account" takes precedence and "Use lti pii" is ignored.

Note: The existing documentation included a doc about configuring LTI authentication via Third Party Auth (Django admin > Third_Party_Auth > Provider Configuration (LTI), using the endpoint /auth/login/lti/). Investigation of the codebase confirmed that this is a completely separate feature — it uses LTI as an SSO login mechanism into Open edX itself and does not deliver embedded course content. It is not part of the lti_provider app and will be documented separately.

12. NEW — Reference: LTI Provider Configuration Settings

Diataxis type: reference Tags: site operator, reference Status: New document — needs Claude Code to extract from codebase

[VERIFY: Extract all settings from common.py and the lti_provider app. The following are the known ones — add any others found in the code.]

This reference lists all configuration settings related to the LTI provider functionality.

[VERIFY: Are there any waffle flags, feature toggles, or additional settings beyond ENABLE_LTI_PROVIDER? Check for any in the lti_provider app code.]

See Also

• Enable LTI Provider Functionality (how-to)

• Configure Credentials for a Tool Consumer (how-to)

CROSS-CUTTING QUESTIONS FOR CLAUDE CODE

The following questions should be verified against the edx-platform codebase (primarily lms/djangoapps/lti_provider/):

1. URL patterns: What URL patterns does lti_provider/urls.py define? Do subsection URLs require both sequential and vertical block IDs?

2. Models: What models exist in lti_provider/models.py? Do they match what the docs describe (LtiConsumer, LtiUser, GradedAssignment, OutcomeService)? Note: we already know about use_lti_pii and require_user_account fields on LtiConsumer.

3. Feature flag: Is ENABLE_LTI_PROVIDER still the correct feature flag? Is it enabled by default in any recent release?

4. Grade passback: How does outcomes.py handle grade passback failures? Are there logs?

5. Staff Debug Info: Does Staff Debug Info still work in the Learning MFE for finding usage IDs?

6. data-usage-id: Does the data-usage-id HTML attribute still exist in the Learning MFE page source?

7. Tutor configuration: How do you enable ENABLE_LTI_PROVIDER and set LTI_AGGREGATE_SCORE_PASSBACK_DELAY in a Tutor-based deployment?

8. X_FRAME_OPTIONS: Is ALLOW-FROM still functional, or should the docs recommend Content-Security-Policy: frame-ancestors?

9. Additional settings or waffle flags: Are there any other configuration points not covered in the existing docs?

10. links.txt: The site operator index.rst includes .. include:: /links.txt. Does this file exist and is it needed?