Protected assessment workflows, built for Canvas.

Launch and identity failures — refused connections, signing-key errors, invalid launches, deployment-ID rejections, and a denied administrator dashboard.

These symptoms appear when the tool is opened from Canvas navigation, before any Canvas API work happens. Read the exact error text — it maps to a cause.

`sso.canvaslms.com refused to connect`

The tool is using Canvas cloud's authorization endpoint for a self-hosted Canvas, and that page refuses to embed.

Fix: set LTI_AUTH_URL and LTI_KEY_SET_URL to the self-hosted Canvas endpoints, deploy, and relaunch. Confirm the exact issuer too. Full procedure in Self-hosted Canvas.

`Canvas Signing-Key Error`

Canvas's platform JWKS contains an RSA key smaller than 2048 bits (common with the legacy sample JWKs in some Canvas Docker setups).

Fix: rotate the three Lti::KeyStorage keys, restart Canvas web, verify every key at ${CANVAS_DOMAIN}/api/lti/security/jwks is ≥2048-bit, then reopen the tool. See Self-hosted Canvas → Platform signing keys.

`Invalid LTI Launch`

The signed launch could not be verified for another reason.

Fix: reopen the tool first — a stale iframe token is the common cause. If it repeats, compare, against the Canvas Developer Key: the deployment ID, the issuer, the client ID, the target-link URI, and the public JWKS URL. A mismatch in any one produces this error.

`LTI Deployment Configuration Required`

Deployment-ID checking is enabled and Canvas installed the app with an ID the service does not yet allow.

Fix: retrieve the deployment_id from Canvas's External Tools API for that course/account app, append it to LTI_DEPLOYMENT_ID (do not replace existing IDs — the value supports a comma/newline allowlist), 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 — but only if everyone who can install this client ID is trusted. See Install the app → deployment-ID policy.

`Connect Canvas` appears

The launch succeeded, but the user has not granted Canvas API access to this Canvas instance yet. This is expected on first use.

Fix: select Connect Canvas and complete the authorization. If it loops, see OAuth & scopes.

Canvas reports an LTI configuration/identity error

Fix: refresh the registration from ${TOOL_URL}/lti/config; confirm the launch includes the signed numeric Canvas user custom field and that LTI_DEPLOYMENT_ID matches the installed app. A Canvas administrator may need to refresh the LTI registration so Canvas supplies the configured custom-field substitutions.

Administrator dashboard is missing or denied

The dashboard requires a genuine root-account administrator context — not an instructor enrollment or a course-level install.

Fix, in order:

Install the LTI app at the root account from the current /lti/config.

Use an actual root-account administrator account.

Confirm Canvas expands the account / root-account / root-admin custom fields in the launch.

Allow the administrator OAuth scopes on the API key (see API OAuth key).

A course installation or instructor enrollment is intentionally insufficient.

A launch works in one environment but not another

Client IDs, deployment IDs, URLs, OAuth keys, secrets, and PostgreSQL databases are environment-specific. Mixing a test value into a production deployment (or vice versa) is the usual cause.

Fix: treat every one of those as belonging to exactly one environment and audit them against the isolation rule. Do not share a database or secret across two Canvas environments.

Canvas launch