OIDC signing keys
Never paste real secrets, keys, tokens or passwords into this site.
The Suite signs ID and access tokens with RS256 keys stored in the SQLite
oidc_signing_keys table. Private keys are encrypted with AES-GCM using
OIDC_KEY_WRAP_SECRET, supplied separately in the Node service environment.
A database backup needs the matching secret to restore sign-in.
Rotation overlap
JWKS at /api/oidc/jwks publishes the current and previous public keys.
The previous key keeps existing tokens verifiable until their expiry.
Rotation retires the older previous key, demotes the current key and inserts
a new current key in one SQLite transaction.
Do not rotate more frequently than tokens live (10 minutes); the operational minimum is one hour and the normal cadence is 90 days. Refresh tokens are opaque database records and are unaffected by signing-key rotation.
Verification and rotation
The npm tools use a SQLite file, on Windows and macOS alike:
npm run db:verify-signing-keys -- --sqlite <file>
npm run db:rotate-signing-key -- --sqlite <file>
npm run db:rotate-signing-key -- --sqlite <file> --yes
Supply OIDC_KEY_WRAP_SECRET through the process environment.
Verification is read-only and prints key identifiers and results without
key material. Rotation prints its plan unless --yes is passed.
The older d1:verify-signing-keys and d1:rotate-signing-key npm names
are compatibility aliases for these SQLite tools. The old --database
and --env remote D1 arguments are no longer accepted by npm commands.
Work on a controlled copy or stop the service before an offline change. A change to a downloaded copy does not update the running VM: install the verified file following the internal Oracle restore procedure, removing stale WAL sidecars while the service is stopped.
Changing the wrap secret
Changing only the environment value makes the stored private key unreadable.
Keep a verified backup and the previous secret before proceeding.
Re-wrap the keys with the new secret or deliberately rotate a new current
key under it, then put the matching value in /etc/suite/suite.env and restart
the suite service. Coordinate the database and environment update while
the service is stopped, then verify sign-in and the JWKS overlap.
A previous private key that no longer unwraps is reported as a warning: its public key still verifies outstanding tokens. A current key that cannot unwrap fails verification.
Test and production have independent SQLite files and secrets. There is no Worker secret to update with Wrangler.
The internal docs/oracle-production.md and docs/secret-rotation.md
runbooks cover custody, deployment and recovery.
Troubleshooting
- No current key: on a fresh database the JWKS and token endpoints bootstrap one automatically. Persistent failures require checking database writes and the wrap secret.
- Unsupported algorithm: inspect and restore the stored key; do not change discovery metadata to hide a key problem.
- Could not be unwrapped: the environment secret and stored key disagree, or the stored key was altered. Retrying cannot fix either condition.
- Secret shorter than 32 characters: generate a strong random secret. HKDF derives a fixed-length key; it cannot add entropy to a short secret.