Registering Safe Online Exam as a Canvas LTI 1.3 App

Safe Online Exam integrates with Canvas LMS through two separate Developer Keys — an API OAuth key for assessment management and a LTI 1.3 key for signed course launches — plus a theme-loaded detector script that runs on quiz pages. This page walks a Canvas root-account administrator through creating both keys, installing the external app, loading the detector through the Canvas theme, and verifying the full integration.

Complete Deployment and confirm that the service’s public TOOL_URL is final before creating any Canvas registrations. For Docker/VPS deployments, establish DNS and TLS before this step. The Cloud Run bundle reserves the stable URL before it pauses for the Canvas steps.

Prerequisites

You need a Canvas root-account administrator who can manage Developer Keys, external apps, account themes, and OAuth scopes. You also need the deployed service URL and access to the deployment’s secret store. Before changing Canvas, confirm these service endpoints respond:

curl -fsS "${TOOL_URL}/health"
curl -fsS "${TOOL_URL}/lti/config"
curl -fsS "${TOOL_URL}/.well-known/jwks.json"
curl -fsS "${TOOL_URL}/js/canvas-seb-detector.js" | head

The /setup and /setup/guide pages on the service provide a public role-oriented checklist. They confirm that the service responds, not that Canvas has stored the intended registration or loaded the detector.

Values to Record

Keep a record of these values as you progress through the steps:

Value	Canvas source	Runtime destination
`CANVAS_DOMAIN`	The Canvas base origin, such as `https://canvas.example.edu`	`CANVAS_DOMAIN`
`LTI_CLIENT_ID`	LTI 1.3 Developer Key client ID	`LTI_CLIENT_ID`
`LTI_DEPLOYMENT_ID`	External App deployment ID after installation	`LTI_DEPLOYMENT_ID` when checking is enabled
`CANVAS_API_CLIENT_ID`	API OAuth Developer Key client ID	`CANVAS_API_CLIENT_ID`
`CANVAS_API_CLIENT_SECRET`	API OAuth Developer Key secret	`CANVAS_API_CLIENT_SECRET`
`CANVAS_REDIRECT_URI`	OAuth callback registration	`${TOOL_URL}/api/oauth2callback`

The LTI client ID and Canvas API OAuth client ID come from different registrations. Mixing them breaks either signed LTI launches or Canvas API authorization.

Installation Steps

Create the Canvas API OAuth Developer Key

The application uses user-scoped Canvas OAuth tokens for assessment discovery and access-code changes. Do not replace this with a personal access token.In Canvas, open Admin, select the root account, open Developer Keys, and create an API Key. Use a recognizable name, owner email, and purpose, then set this exact redirect URI:

${TOOL_URL}/api/oauth2callback

If the Canvas instance supports enforced scopes, allow this complete application scope set:

url:GET|/api/v1/courses
url:GET|/api/v1/courses/:course_id/quizzes
url:GET|/api/v1/courses/:course_id/assignments
url:GET|/api/quiz/v1/courses/:course_id/quizzes/:assignment_id
url:PUT|/api/v1/courses/:course_id/quizzes/:id
url:PATCH|/api/quiz/v1/courses/:course_id/quizzes/:assignment_id
url:GET|/api/v1/login/session_token

For the root-account administrator dashboard, also allow this administrator scope set on the same OAuth key:

url:GET|/api/v1/accounts/:id
url:GET|/api/v1/accounts/:account_id/permissions
url:GET|/api/v1/accounts/:account_id/courses
url:GET|/api/v1/accounts/:account_id/terms
url:GET|/api/v1/courses/:id
url:GET|/api/v1/courses/:course_id/quizzes/:id

Every Canvas connection requests the complete scope set regardless of the user’s role. This prevents a person who is an instructor in one course and a student in another from holding an incompatible role-specific grant. Canvas continues to enforce the authorizing user’s actual account and course permissions.Store the API key’s client ID and secret in the deployment’s secret store as CANVAS_API_CLIENT_ID and CANVAS_API_CLIENT_SECRET.

Create the LTI 1.3 Developer Key

Return to the root account’s Developer Keys, create an LTI Key, and choose Canvas’s JSON configuration URL option. Enter:

${TOOL_URL}/lti/config

The configuration document supplies the title, course-navigation and root-account-navigation placements, OIDC initiation URL, target link URI, public JWKS URL, and signed custom fields. Prefer this URL over manually copying fields — the deployed service remains the registration source of truth.For reference, the individual values the configuration document provides are:

Canvas field	Value
JSON configuration URL	`${TOOL_URL}/lti/config`
OIDC initiation URL	`${TOOL_URL}/lti/login`
Target link URI	`${TOOL_URL}/lti/launch`
Redirect URI	`${TOOL_URL}/lti/launch`
Public JWK URL	`${TOOL_URL}/.well-known/jwks.json`

Enable the key and record its client ID as LTI_CLIENT_ID.

Install the External App

At the root account (or desired account scope), open Settings → Apps → View App Configurations. Add an app By Client ID, paste the LTI client ID from the previous step, approve the registration, and record the deployment ID Canvas assigns as LTI_DEPLOYMENT_ID.Set the deployment ID in LTI_DEPLOYMENT_ID, update the LTI client ID in the deployment’s secret store, and deploy a new service revision before testing. On Cloud Run, add numbered Secret Manager versions and re-run the setup or upgrade. On Docker/VPS, update the protected environment or mounted secret and recreate the application container.

For a controlled self-service rollout where instructors may add the app to their own courses, set LTI_DEPLOYMENT_ID_CHECKING_ENABLED=false on the service. This accepts any non-empty deployment ID in a Canvas-signed launch from the configured issuer and client ID. Only use it if everyone able to install this client ID in Canvas is trusted to grant access to the tool.

Use a root-account-level installation for a broad rollout and for the administrator dashboard. Use a course-level installation only for an isolated instructor/student pilot; a course-level installation does not provide the root-account navigation surface.

Load the Detector Script Through the Canvas Theme

The detector runs on Canvas quiz-taking pages. It treats a Canvas access-code field only as a challenge signal, verifies the exact course/assessment against the service, fills an access code only after Config Key proof, shows approved web tools, and detects Canvas-confirmed completion.For a Cloud Run bundle deployment, generate the upload-ready loader file first:

./canvas-theme-loader.sh cloudrun.env

This writes a canvas-theme-loader.js file containing the exact configured public origin. Upload that generated file rather than manually transcribing the URL.The stable loader URL is:

${TOOL_URL}/js/canvas-seb-detector.js

From Admin, select the intended account, open Themes, edit or create the active theme, and upload the loader as its desktop JavaScript. Preview, save, and apply the theme.

Some self-hosted Canvas deployments reject uploaded theme JavaScript with ActionController::InvalidCrossOriginRequest (HTTP 422). If you see that error in the browser console, configure the account theme’s js_overrides value to the externally hosted loader URL instead:

${TOOL_URL}/js/canvas-seb-theme-loader.js

Do not disable Canvas CSRF protection globally to work around this. See the Canvas Setup source documentation for a Rails runner workaround for root-account recovery.

Verify the Integration

Use separate administrator, instructor, and student accounts.

As a root-account administrator, retrieve /lti/config, confirm Canvas has the intended client and deployment IDs, and confirm both the Safe Online Exam Admin root-account navigation entry and the course app in a target course.
Open Safe Online Exam Admin, complete Canvas authorization, verify school courses load, create and assign a school tool preset, refresh a test course, reveal and rotate a test exit password, and confirm each operation appears in recent administrator activity.
As an instructor, launch the tool from Canvas, complete OAuth, refresh assessments, enable the assigned school tool, create a quiz-only tool, set an exit-password policy, and enable one Classic Quiz and one New Quiz.
In a normal browser, open each assessment page and verify that the theme loaded the detector script without console errors.
As a student, launch the course-navigation tool, complete the one-time Canvas connection, and run the optional setup check.
Hide the course-navigation placement from students, revisit both assessment pages in a normal browser, and confirm Open Safe Exam Browser still starts the signed LTI launch.
Download a fresh configuration. On an approved SEB client, verify the configuration opens, reaches Canvas, proves its Config Key, fills the access-code prompt, and makes only selected exam tools available.
For each assessment type, cancel one Canvas submission confirmation and ensure no exit occurs. Then submit successfully and ensure the exit flow begins only after Canvas shows the authoritative completed state.

Deployment Boundary

Why Each Canvas Instance Needs Its Own Deployment

The service has one active LTI platform configuration: CANVAS_DOMAIN, LTI_ISSUER, LTI_KEY_SET_URL, LTI_AUTH_URL, LTI_CLIENT_ID, and LTI_DEPLOYMENT_ID. Canvas cloud values are the defaults. If a service configured with cloud defaults is registered in a self-hosted Canvas, /lti/login redirects the embedded tool frame to sso.canvaslms.com — a page that is intentionally not embeddable by a self-hosted Canvas — and the browser shows sso.canvaslms.com refused to connect. Deploy a separate service for each independent Canvas instance. Keep separate client IDs, deployment IDs, OAuth credentials, PostgreSQL databases, secrets, and service URLs for environments that must remain isolated (production, test, beta).

Self-Hosted Canvas Signing Keys

Canvas must sign LTI launch tokens with an RSA key of at least 2048 bits. Before registering the tool, inspect ${CANVAS_DOMAIN}/api/lti/security/jwks. Do not use the legacy sample JWKs shipped with some Canvas Docker configurations. The service rejects undersized RS256 keys rather than accepting a weaker platform signature.For a running Canvas instance, rotate the three platform keys through Canvas’s own Lti::KeyStorage and restart its web service so its JWKS response reloads the new keys. After the restart, verify that every key at ${CANVAS_DOMAIN}/api/lti/security/jwks has a 2048-bit (or larger) modulus before reopening the external tool.

LTI Launch Recovery

Use the visible error state to choose the next diagnostic step:

What appears in Canvas	Meaning	Recovery
`sso.canvaslms.com refused to connect`	The tool is using Canvas cloud’s authorization endpoint for a self-hosted Canvas.	Set `LTI_AUTH_URL` and `LTI_KEY_SET_URL` to the self-hosted Canvas endpoints, deploy the tool, and relaunch.
`Canvas Signing-Key Error`	Canvas’s platform JWKS contains an RSA key smaller than 2048 bits.	Rotate the three `Lti::KeyStorage` keys, restart Canvas web, verify the public JWKS, and reopen the tool.
`Invalid LTI Launch`	The tool could not verify the signed launch for another reason.	Reopen the tool. If it repeats, compare the deployment ID, issuer, client ID, target-link URI, and public JWKS URL with the Canvas Developer Key.
`Connect Canvas`	The LTI launch succeeded but the current user has not yet granted Canvas API access.	Select Connect Canvas and complete the Canvas authorization flow.

Common Integration Failures

LTI Deployment Configuration Required

Deployment-ID checking is enabled and Canvas installed the app with an ID not yet allowed by the service. Retrieve the deployment_id from Canvas’s External Tools API for that course or account app, append it to LTI_DEPLOYMENT_ID without replacing existing IDs, deploy a new revision, then reopen the tool. For an intentional self-service rollout, an administrator can instead set LTI_DEPLOYMENT_ID_CHECKING_ENABLED=false.

Canvas reports an LTI configuration or identity error

Refresh the registration from /lti/config. Confirm the launch includes the signed numeric Canvas user custom field and that LTI_DEPLOYMENT_ID matches the installed app.

Instructor is asked to authorize repeatedly

Confirm the API OAuth redirect URI exactly matches ${TOOL_URL}/api/oauth2callback, the OAuth key is enabled, and the configured client ID and secret are the API-key values (not the LTI key values).

Administrator dashboard is missing or denied

Install the LTI app at the root account from the current /lti/config. Use an actual root-account administrator. Confirm Canvas expands the account/root-account/root-admin custom fields and that the administrator OAuth scopes are allowed. A course installation or instructor enrollment is intentionally insufficient.

Student cannot connect Canvas or configuration download fails

Confirm the exact url:GET|/api/v1/login/session_token scope is allowed in the OAuth key and that the student is authorizing the same Canvas environment as the LTI launch.

Access code is not filled in SEB

Confirm a fresh configuration was downloaded, the detector loaded on the actual assessment route, Config Key proof succeeded, and the Canvas prompt is not ambiguous.

Detector never loads

Check the active account theme, inherited theme behavior, browser console, CSP headers, and that the public detector URL returns JavaScript content.

Next Steps

With Canvas registered and the detector loaded, provision the SEB client encryption identity following the Certificate Management guide, then complete the full Canvas and SEB acceptance sequence described in the Testing guide.

Overview

Deployment

Configuration

User Workflows

Operations

Registering Safe Online Exam as a Canvas LTI 1.3 App

Prerequisites

Values to Record

Installation Steps

Deployment Boundary

Why Each Canvas Instance Needs Its Own Deployment

Self-Hosted Canvas Signing Keys

LTI Launch Recovery

Common Integration Failures

Next Steps

​Prerequisites

​Values to Record

​Installation Steps

​Deployment Boundary

​Why Each Canvas Instance Needs Its Own Deployment

​Self-Hosted Canvas Signing Keys

​LTI Launch Recovery

​Common Integration Failures

​Next Steps

Prerequisites

Values to Record

Installation Steps

Deployment Boundary

Why Each Canvas Instance Needs Its Own Deployment

Self-Hosted Canvas Signing Keys

LTI Launch Recovery

Common Integration Failures

Next Steps