Secret Management and File-Based Configuration Guide

Safe Online Exam supports file-based alternatives for every sensitive environment variable, allowing secrets to be supplied through Docker or Kubernetes secret mounts without embedding plaintext values in environment files or shell arguments. This page covers the _FILE pattern, the OAuth token encryption keyring format, the compat vs enforce mode, the Docker Compose secrets profile, and safe rotation procedures for each class of secret.

Never place secret values in shell command arguments, terminal history, screenshots, log output, or version-controlled files. File-based secrets exist specifically to keep sensitive material out of the process environment and system logs. Protect every secrets directory and file with restrictive filesystem permissions before writing any content into it.

File-Based Secret Alternatives

For each of the sensitive variables below, the application accepts a mutually exclusive _FILE alternative. Set either the direct variable or its file alternative — never both.

The application explicitly rejects a configuration where both a direct variable and its _FILE counterpart are present in the environment. It reports the conflict and exits without reading either value. Unreadable paths are also reported as errors without echoing any secret contents.

Direct variable	File alternative	When to use the file form
`DATABASE_PASSWORD`	`DATABASE_PASSWORD_FILE`	Any production deployment; always required in hardened runtimes.
`LTI_PRIVATE_KEY`	`LTI_PRIVATE_KEY_FILE`	Preferred for RSA JWK JSON — avoids multiline quoting issues.
`CANVAS_API_CLIENT_SECRET`	`CANVAS_API_CLIENT_SECRET_FILE`	All production deployments.
`SESSION_SECRET`	`SESSION_SECRET_FILE`	All production deployments.
`STATE_ENCRYPTION_KEY`	`STATE_ENCRYPTION_KEY_FILE`	All production deployments.
`OAUTH_TOKEN_ENCRYPTION_KEYRING`	`OAUTH_TOKEN_ENCRYPTION_KEYRING_FILE`	Always preferred; avoids shell escaping of JSON.
`SEB_QUIT_PASSWORD`	`SEB_QUIT_PASSWORD_FILE`	When a managed exit-password fallback is configured.

Files are read exactly once during configuration startup. Required-value validation treats a missing or empty file result as equivalent to a missing direct variable — startup fails before listening with a descriptive error message.

OAuth Token Encryption Keyring

Safe Online Exam encrypts every stored Canvas OAuth access token and refresh token using AES-256-GCM. The keyring is a JSON object whose keys are string key IDs and whose values are 32-byte AES keys encoded as canonical base64url strings (no padding, URL-safe alphabet).

{
  "primary": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "retired-v1": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
}

Each key value must decode to exactly 32 bytes. The application rejects any keyring entry with an invalid length, non-canonical encoding, or an illegal key ID character. Key IDs must match the pattern [A-Za-z0-9][A-Za-z0-9._-]{0,63}. OAUTH_TOKEN_ENCRYPTION_ACTIVE_KEY_ID identifies which key ID in the keyring is used for new token writes. Every read operation accepts any key ID present in the keyring, so old records remain decryptable after a key rotation as long as the retired key is not yet removed.

Generating a New AES Key

Use Node.js to generate a cryptographically random 32-byte base64url key:

node -e "const {randomBytes}=require('crypto'); console.log(randomBytes(32).toString('base64url'));"

Write the output directly to a file rather than passing it through a shell variable:

node -e "const {randomBytes}=require('crypto'); process.stdout.write(randomBytes(32).toString('base64url'));" \
  > ./secrets/oauth_token_encryption_keyring_new_key

Keyring File Format

When using OAUTH_TOKEN_ENCRYPTION_KEYRING_FILE, write the full JSON keyring object to the file. The file must contain valid JSON with no BOM:

{"primary":"<32-byte-base64url-key>"}

After a key rotation with multiple keys present:

{"primary":"<new-32-byte-base64url-key>","v1":"<old-32-byte-base64url-key>"}

Encryption Mode: enforce vs compat

OAUTH_TOKEN_ENCRYPTION_MODE controls how the application handles stored token records.

Mode	Behaviour
`enforce`	All new token writes are encrypted. Existing unencrypted records can still be read and are updated to the active key when explicitly rewritten via `npm run db:encrypt-oauth-tokens:built`. Use this mode for all production deployments.
`compat`	New writes are stored without encryption (legacy plaintext format). This mode exists only as a temporary rollback preparation path and must not be used as a permanent configuration.

Set OAUTH_TOKEN_ENCRYPTION_MODE=enforce in every production environment. The compat mode is documented only so that operators understand it is not a supported long-term state.

The `db:encrypt-oauth-tokens` Maintenance Command

After rotating to a new active key ID, run the bulk rewrite command to update every stored record to the new key before removing the old key from the keyring:

npm run db:encrypt-oauth-tokens:built

This command scans all rows in the canvas_oauth_tokens table and re-encrypts any record whose stored key ID does not match OAUTH_TOKEN_ENCRYPTION_ACTIVE_KEY_ID. It reports counts only and fails closed — if any row cannot be decrypted with the keys in the current keyring, the command exits with an error and leaves all remaining rows untouched. Only remove a retired key from the keyring after two successive runs of this command both report zero updated rows. This guarantees that every stored record has been rewritten under the active key.

Docker Compose Secrets Profile

The checked-in compose.secrets.yaml override implements the full file-based secrets pattern for Docker Compose deployments. Start it with .env.compose.secrets.example as the environment file. The override does the following for every service that handles secrets (postgres, migrate, app, cleanup, and encrypt-oauth-tokens):

Clears the corresponding direct secret variable to an empty value.
Supplies the _FILE path pointing to /run/secrets/<name>.
Mounts only the named secret files into each container via Docker’s secrets: mechanism.

services:
  app:
    environment:
      DATABASE_PASSWORD:
      DATABASE_PASSWORD_FILE: /run/secrets/database_password
      LTI_PRIVATE_KEY:
      LTI_PRIVATE_KEY_FILE: /run/secrets/lti_private_key
      CANVAS_API_CLIENT_SECRET:
      CANVAS_API_CLIENT_SECRET_FILE: /run/secrets/canvas_api_client_secret
      SESSION_SECRET:
      SESSION_SECRET_FILE: /run/secrets/session_secret
      STATE_ENCRYPTION_KEY:
      STATE_ENCRYPTION_KEY_FILE: /run/secrets/state_encryption_key
      OAUTH_TOKEN_ENCRYPTION_KEYRING:
      OAUTH_TOKEN_ENCRYPTION_KEYRING_FILE: /run/secrets/oauth_token_encryption_keyring
      SEB_QUIT_PASSWORD:
      SEB_QUIT_PASSWORD_FILE: /run/secrets/seb_quit_password
    secrets:
      - database_password
      - lti_private_key
      - canvas_api_client_secret
      - session_secret
      - state_encryption_key
      - oauth_token_encryption_keyring
      - seb_quit_password

The PostgreSQL service also receives the database password through its native POSTGRES_PASSWORD_FILE input via the same mechanism.

Directory Permissions

The SECRETS_DIRECTORY (default ./secrets) is the host directory from which Compose reads each named file. On Linux hosts, set the containing directory to mode 0700 so that only the deploying user can list its contents:

mkdir -p ./secrets
chmod 0700 ./secrets

Individual secret files within the directory can be mode 0644 — Docker mounts only the named files into each container, and the 0700 directory prevents enumeration from other accounts on the same host. Required files in SECRETS_DIRECTORY for the secrets profile:

database_password
lti_private_key
canvas_api_client_secret
session_secret
state_encryption_key
oauth_token_encryption_keyring
seb_quit_password            (may be empty when no managed fallback is configured)
seb-config-encryption.crt.pem

Secret Rotation Effects on Live Sessions

Each secret class has a distinct impact when rotated. Rotate one secret at a time and follow the create → deploy → smoke-test → disable-old sequence.

SESSION_SECRET rotation

Rotating SESSION_SECRET immediately invalidates all active user sessions. Every user will be redirected to re-authenticate with Canvas on their next request. There is no grace period. Schedule rotation during a low-traffic window and communicate the expected re-authentication to users in advance.

STATE_ENCRYPTION_KEY rotation

Rotating STATE_ENCRYPTION_KEY invalidates all outstanding opaque LTI and OAuth state tokens. Any user in the middle of an LTI launch or Canvas OAuth authorisation flow at the moment of rotation will see an error and need to restart that flow. Sessions that have already completed are unaffected.

LTI_PRIVATE_KEY rotation

Rotating the LTI signing key requires coordination with Canvas. The new public key must appear in the JWKS endpoint at ${TOOL_URL}/lti/jwks before Canvas can verify launches signed with it. After deploying the new key, re-register the tool in Canvas by fetching the configuration from ${TOOL_URL}/lti/config so Canvas stores the updated JWKS reference.

OAUTH_TOKEN_ENCRYPTION_KEYRING rotation

To rotate an OAuth token encryption key safely:

Add a new 32-byte base64url key under a new key ID to the keyring JSON.
Update OAUTH_TOKEN_ENCRYPTION_ACTIVE_KEY_ID to the new key ID.
Deploy the updated keyring and active key ID.
Run npm run db:encrypt-oauth-tokens:built to rewrite all stored tokens to the new key.
Run the command a second time and confirm zero updated rows.
Only after both runs report zero updates, remove the old key from the keyring JSON and deploy again.

The old key must remain in the keyring until all records have been rewritten. Removing it prematurely causes decryption failures for any record that has not yet been rewritten.

SEB certificate rotation

Rotating SEB_CONFIG_ENCRYPTION_CERT_PEM or SEB_CONFIG_ENCRYPTION_CERT_PATH requires distributing the matching new private identity to all managed SEB client devices before deploying the new certificate. Existing downloaded SEB configurations encrypted with the old certificate will no longer open after rotation. Issue fresh SEB configurations for all active assessments after deploying the new certificate.

Overview

Deployment

Configuration

User Workflows

Operations

Secret Management and File-Based Configuration Guide

File-Based Secret Alternatives

OAuth Token Encryption Keyring

Generating a New AES Key

Keyring File Format

Encryption Mode: enforce vs compat

The `db:encrypt-oauth-tokens` Maintenance Command

Docker Compose Secrets Profile

Directory Permissions

Secret Rotation Effects on Live Sessions

​File-Based Secret Alternatives

​OAuth Token Encryption Keyring

​Generating a New AES Key

​Keyring File Format

​Encryption Mode: enforce vs compat

​The db:encrypt-oauth-tokens Maintenance Command

​Docker Compose Secrets Profile

​Directory Permissions

​Secret Rotation Effects on Live Sessions

File-Based Secret Alternatives

OAuth Token Encryption Keyring

Generating a New AES Key

Keyring File Format

Encryption Mode: enforce vs compat

The `db:encrypt-oauth-tokens` Maintenance Command

Docker Compose Secrets Profile

Directory Permissions

Secret Rotation Effects on Live Sessions