Protected assessment workflows, built for Canvas.

The access, infrastructure, people, and decisions to settle before you start — so the setup runs without stalls.

Settle everything on this page before you begin. Most failed or half-finished installs trace back to a missing prerequisite discovered mid-way — a scope that cannot be added, a domain that is not final, or a device fleet with no management tooling.

People and access

A Canvas administrator

Someone who can create and manage Developer Keys, install external apps, edit account themes / JavaScript, and configure OAuth scopes at the root account.

Cloud or host access

Owner/editor on a Google Cloud project (for Cloud Run), or root on a Linux host with Docker (for the self-hosted path).

A device-management owner

Whoever runs your MDM/device fleet, to install the SEB configuration-encryption identity onto exam devices.

Infrastructure

Requirement	Why
A final, stable HTTPS origin (`TOOL_URL`)	Canvas registrations bind to it. It must be decided before you create developer keys. Changing it later is a Canvas re-registration, not a redeploy.
PostgreSQL 17 or newer	The durable store for settings, tokens, sessions, one-time state, and locks. Managed (Cloud SQL) or self-run.
TLS termination	Cloud Run provides it; on a VPS you run a reverse proxy (Caddy, nginx, Traefik). Canvas will not launch a plain-HTTP tool.
Outbound access to Canvas	The service calls the Canvas REST and New Quiz APIs and Canvas's OAuth/JWKS endpoints.

Decide the URL first

The public origin flows into the LTI registration, the OAuth callback, the JWKS URL, and the detector script URL. Pick the final hostname (and, if you use one, finish the custom-domain mapping) before creating any Canvas keys. Both deploy guides reserve a stable URL as their first step for this reason.

Safe Exam Browser and devices

Supported SEB clients installed on exam devices (macOS and/or Windows). The generated configuration relies on client features such as Config Key proof and, on macOS, Automatic Assessment Configuration (AAC).
A way to install a certificate/identity profile on those devices — an MDM or equivalent. The private identity must be installed non-extractably and scoped to the SEB application; you cannot hand students a .p12 file.
Time to run a setup check on a representative device before any real exam.

Accessibility note

On macOS, AAC can block some third-party assistive technology. Plan accommodations that need such tools as a separately approved arrangement rather than by weakening the shared configuration. See Certificate management and SEB configuration policy.

Decisions to make now

Deployment target

Google Cloud Run + Cloud SQL

Recommended. Managed HTTPS, managed PostgreSQL, immutable images, Secret Manager, and a Cloud Build release gate that runs migrations before traffic.

Docker Compose on a VPS

The same container on any Linux host. You operate DNS, TLS, backups, scheduling, and monitoring yourself.

The application runtime is provider-agnostic — the Google-specific parts are confined to the checked-in Cloud Build configuration.

Canvas environment: cloud or self-hosted

Canvas cloud (*.instructure.com): the built-in defaults apply; no endpoint overrides needed.
Self-hosted Canvas: you must override the authorization and JWKS endpoints and confirm the exact iss (issuer) Canvas sends. Read Self-hosted Canvas before you start — a self-hosted Canvas can still use https://canvas.instructure.com as its issuer, so do not infer it from the hostname.

Deployment-ID policy

By default the service accepts launches only from the specific installed deployment ID you configure. A controlled self-service mode (LTI_DEPLOYMENT_ID_CHECKING_ENABLED=false) accepts any signed launch from your Canvas issuer and client ID — use it only if everyone who can install this app in Canvas is trusted. See Configuration.

Isolation

Confirm the list of independent environments you need. Each one gets its own service URL, database, secrets, LTI deployment, and OAuth credentials. Never share these across a test and a production Canvas.

Values you will collect

Keep a secure scratch document (not in version control, not in chat) for the values that appear during setup. You will move them into your secret store:

Value	Source
`TOOL_URL`	Your final HTTPS origin.
`CANVAS_DOMAIN`	Your Canvas base origin.
`LTI_CLIENT_ID`	LTI 1.3 Developer Key client ID.
`LTI_DEPLOYMENT_ID`	Assigned when you install the external app.
`CANVAS_API_CLIENT_ID` / `CANVAS_API_CLIENT_SECRET`	API OAuth Developer Key.
LTI signing key, session/state secrets, DB password	Generated during deploy.
SEB encryption certificate + private identity	Generated during deploy; the private half goes to the device vault only.

When these are ready, continue to the Setup overview.

Prerequisites