Skip to main content

Secrets & encryption

Provider secrets you set in the admin console (Resend API key, OAuth client secrets) are encrypted at rest in your own database. This page explains the model, the master key, and rotation.

The master key​

Set one env var:

IDENTSPHERE_CONFIG_KEY="$(openssl rand -base64 32)"   # 32 bytes, base64 or hex
  • It encrypts every dashboard-stored secret. Back it up like IDENTSPHERE_JWT_SECRET — losing it means re-entering provider secrets.
  • If it's unset, dashboard secret storage is disabled and providers fall back to env-var config (existing deployments are unaffected).
  • The server validates it at boot (must decode to exactly 32 bytes, not all-zero) and fails fast on a weak/malformed key.

How it's protected​

  • AES-256-GCM authenticated encryption. Random 96-bit nonce per secret (OS CSPRNG).
  • Context binding (AAD): each ciphertext is bound to its provider:field — a blob cannot be moved from one provider's row to another.
  • Versioned, self-describing blobs (scheme · key-id · nonce · ciphertext) so the format can evolve and the right key is selected on read.
  • Never exposed: secrets are never returned by the API (the dashboard shows only "secret set"), never logged, and never in audit metadata.
  • Fail-safe: if a secret can't be decrypted (wrong/rotated key, tampering), the provider is marked degraded and the server falls back to env — it never panics and never uses a wrong secret.

Rotating the master key (no downtime)​

  1. Keep the current key as the previous (decrypt-only) key and set a new primary: 
    IDENTSPHERE_CONFIG_KEY="<new key>"
    IDENTSPHERE_CONFIG_KEY_PREVIOUS="<old key>"   # comma-separate for multiple
    The server can now decrypt old secrets (selected by their embedded key id) and writes new secrets under the new key.
  2. Re-save each provider's secret in /admin/integrations (this re-encrypts it under the new key). Watch for any degraded badge.
  3. Once nothing is degraded, drop IDENTSPHERE_CONFIG_KEY_PREVIOUS.

Operational notes​

  • Run Postgres with TLS + at-rest disk encryption for defense in depth.
  • A future release can source the master key from a KMS/Vault without changing stored ciphertext (the key provider is a pluggable seam).