Master key custody

WI_MASTER_KEY protects the data key that encrypts every stored credential. Back it up off the box, and rotate it with WI_MASTER_KEY_OLD.

For: Administrators responsible for a deployment's secrets · Last updated

WI_MASTER_KEY is the key that protects every credential your company stores in Workforce Intelligence. Treat it as the most important value on the box.

How stored credentials are protected#

Stored credentials are provider API keys and cloud credentials, the single sign-on client secret, the SAML signing key, the outgoing-email password, stored secrets, and the signing key for the tool connection service. All of them are encrypted with a data key that belongs to your company. That data key is itself encrypted with WI_MASTER_KEY and stored in the database next to a short fingerprint that identifies which master key encrypted it. The fingerprint identifies a key; it cannot be used to recover it.

Because the master key protects only the data key, you can replace the master key without re-entering any credential. See Rotate the master key.

The rules#

  • The installer generates it once. On the AWS path the template creates it on first boot. On your own server install.sh creates it, or you generate it yourself with openssl rand -base64 32. install.sh and the template never regenerate it and leave an existing .env alone. It changes only when you rotate it by hand.
  • Back it up off the box. Copy /opt/wi/.env (or the .env next to your compose file) to a secret manager or another secure location that is separate from the machine and from the machine's volume backups. Do this as soon as the file exists, and again after every rotation.
  • Without a matching key, stored credentials are unrecoverable. If the key is lost, or you replace it without following the rotation procedure, the application cannot unlock the data key. You would have to enter each credential again.
  • A restored volume or snapshot needs a key that matches it. The database stores the fingerprint of the master key that encrypted its data key, so a restore needs that key. Store the key separately from the volume it protects. See Backups and recovery on AWS.
  • The application refuses to start with the wrong keys. The Compose file requires WI_MASTER_KEY, and the boot check stops with "WI_MASTER_KEY is unset" when it is empty. In production the application also stops when neither WI_MASTER_KEY nor WI_MASTER_KEY_OLD matches the key stored in the database, and when either value is not a valid base64 AES key. See Production boot checks.
  • A key is checked before the data key is created. On the first start with existing stored credentials, production refuses to start unless WI_MASTER_KEY or WI_MASTER_KEY_OLD opens at least one of them, and writes nothing in that case. A credential that neither key opens, found after the data key exists, never stops the application; Encryption keys lists it as needing to be entered again.

Check the state of your keys#

Sign in as an administrator, select Settings, then the Administration tab, and select Manage on the Secrets card. The Encryption keys card, below the tabs, shows whether WI_MASTER_KEY unlocks your stored credentials, the fingerprint of each configured key, and, during a rotation, whether WI_MASTER_KEY_OLD is still needed. Only administrators see it. See Rotate the master key for what each message means.

What you should and should not do#

  • Do keep a copy of the whole .env, because WI_SESSION_SECRET lives there too.
  • Do restrict the file to root (mode 0600), which the installer and template do for you.
  • Do not paste the key into tickets, chat, or logs.
  • Do not replace WI_MASTER_KEY without setting WI_MASTER_KEY_OLD to the previous value first.

Why it is not in the AWS template#

The template generates the key on the instance. The key value never appears in the template, in a stack parameter, in the instance's user data, or in any AWS API call, so nobody who can describe the instance can read it. That also means AWS holds no copy for you: the only copy is the file on the instance's root volume, so your off-box backup of .env is what protects you. See Backups and recovery on AWS.