# How it works

> The trust and proof model behind the integration — the exam flow, the release gate, the two independent protections, and why each deployment is bound to one Canvas.

[Canonical HTML page](https://safeonlineexam.com/docs/how-it-works)

You do not need to read the source code to run this well, but a few ideas make
every later configuration choice obvious. This page is the mental model.

## The exam flow, end to end [#the-exam-flow-end-to-end]

<Steps>
  <Step>
    ### Instructor enables SEB on a quiz [#instructor-enables-seb-on-a-quiz]

    From the Canvas course-navigation tool, an instructor turns on SEB for a Classic
    Quiz or New Quiz. The service creates a Canvas **access code**, writes it to the
    quiz through the Canvas API, and stores the SEB policy. The access code is never
    shown in the normal UI — it is created, hidden, and rotated on the instructor's
    behalf.
  </Step>

  <Step>
    ### Student downloads a fresh configuration [#student-downloads-a-fresh-configuration]

    A student launches the tool, connects Canvas once, and downloads a
    `.seb` configuration file. There is no reusable download link: each download is a
    one-time, 120-second capability bound to that student, that assessment, and the
    **current settings**. When certificate encryption is enabled (the default), the
    file is encrypted to your institution's certificate, so only a managed device
    with the matching private identity can open it.
  </Step>

  <Step>
    ### SEB starts and proves itself [#seb-starts-and-proves-itself]

    When the configuration opens in Safe Exam Browser, SEB reaches Canvas through a
    scoped session URL (the student's normal browser cookies are never copied in).
    On the assessment page, a small **detector script** — loaded through your Canvas
    theme — asks SEB for its Config Key and current URL and sends them to the service
    for verification.
  </Step>

  <Step>
    ### The browser prompt is tied to this assessment [#the-browser-prompt-is-tied-to-this-assessment]

    In an ordinary browser, a Canvas access-code field is only a challenge signal.
    Before showing the Safe Online Exam prompt, the detector checks that the exact
    course and assessment have a matching, enabled, usable SEB requirement. An
    ordinary password-protected Canvas quiz keeps its normal Canvas flow; a missing,
    mismatched, disabled, malformed, unavailable, or rate-limited check does not
    produce a Safe Online Exam launch prompt.
  </Step>

  <Step>
    ### The access code is released — once [#the-access-code-is-released--once]

    Only if the proof succeeds does the service return the access code, the list of
    approved web tools, and an exit grant. The detector fills the code into the
    Canvas prompt automatically. The proof is single-use and valid for two minutes.
    The student never sees the code.
  </Step>

  <Step>
    ### Completion and exit are gated too [#completion-and-exit-are-gated-too]

    The student takes the exam. SEB is allowed to quit only after Canvas itself shows
    the authoritative completed state. A manual or unbound quit attempt is
    deliberately refused.
  </Step>
</Steps>

## The access-code release gate [#the-access-code-release-gate]

The access code is the thing worth protecting, so it is released only when
**all** of the following hold. If any one fails, no code is returned.

| Check                                 | What it confirms                                                                                                                      |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Configuration decrypts (when enabled) | The file opened on a device that holds the approved private identity.                                                                 |
| SEB is genuinely running              | The request comes from Safe Exam Browser, via its JavaScript API — not a normal browser pretending.                                   |
| Config Key matches settings           | The running configuration matches the assessment's **current** server-side settings. Change a setting and old downloads stop working. |
| Right assessment and URL              | The proof is for this assessment, on the expected Canvas exam URL.                                                                    |

<Callout title="Why a settings change forces a re-download">
  The Config Key ties a running configuration to an exact set of settings. When an
  instructor changes a protected setting — allowed tools, passwords, URL policy —
  the old configuration no longer proves against the new settings, so students must
  download a fresh `.seb` file. This is the mechanism, not a bug: it guarantees
  students are always running the current policy.
</Callout>

## Two independent protections [#two-independent-protections]

It is worth being precise: in the default managed-device posture, these protect
different things:

<Cards>
  <Card title="Certificate encryption (default)" description="Stops an unapproved device from opening the configuration at all. Enforced by the private identity living only on managed devices." />

  <Card title="Config Key proof" description="Stops the access code from being released when the running configuration does not match current server settings. Enforced at the moment of release." />
</Cards>

Encryption protects the file at rest and in transit; Config Key proof protects
the release decision at exam time. Certificate encryption is the default and is
the appropriate posture for managed devices. An instance can explicitly set
`SEB_CONFIG_ENCRYPTION_ENABLED=false` when it cannot distribute a client
identity; the configuration is then plaintext unless an instructor sets a start
password. The Config Key proof, one-time grant, session handoff, URL filter, and
lockdown policy remain active, but the download is no longer device-specific.
Treat that as an institution-approved compatibility decision, not a shortcut for
a certificate incident. Config Key proof is not optional.

## Roles [#roles]

The tool routes people by their **signed** Canvas role — identity comes from the
validated LTI launch, never from a query parameter or the page.

| Role                       | Surface                              | Reaches                                                                                                                      |
| -------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Instructor                 | Course-navigation tool               | Discover assessments, set SEB policy, enable/disable, rotate codes for their courses.                                        |
| Student                    | Course-navigation tool (launch-only) | Connect Canvas, run a setup check, download configurations. Never any management action.                                     |
| Root-account administrator | Account-navigation dashboard         | School-wide recovery: password reveal, code rotation, active-course connection, and reusable tool presets with bulk rollout. |

The administrator dashboard requires **both** a signed LTI Administrator role and
Canvas's signed root-account-admin value. An instructor enrollment or a
course-level install is intentionally not enough.

## Assessment identifiers [#assessment-identifiers]

You will see these in URLs, logs, and the admin dashboard. They are stable public
identifiers:

| Assessment type | Canonical content ID                |
| --------------- | ----------------------------------- |
| Classic Quiz    | `classicquiz_{quizId}`              |
| New Quiz        | `newquiz:{courseId}:{assignmentId}` |

## One deployment per Canvas [#one-deployment-per-canvas]

Each deployment is configured for exactly one Canvas origin and one LTI
deployment boundary — one set of client IDs, deployment IDs, OAuth credentials,
database, secrets, and service URL. That isolation is deliberate: it is what keeps
one Canvas environment from ever reading another's tokens or settings.

<Callout type="warn" title="The classic mistake">
  If you register a service that still holds Canvas **cloud** defaults inside a
  **self-hosted** Canvas, the launch redirects the tool frame to
  `sso.canvaslms.com`, which refuses to load in the iframe — you see
  `sso.canvaslms.com refused to connect`. The fix is to point the deployment at the
  self-hosted Canvas's own endpoints. This and related cases are covered in
  [Self-hosted Canvas](/docs/canvas/self-hosted-canvas) and
  [Troubleshooting](/docs/troubleshooting/canvas-launch).
</Callout>

Ready to plan the real thing? Continue to [Prerequisites](/docs/prerequisites).