Secrets

This page helps you keep Goiabada’s secrets safe, and back up the one you can’t afford to lose.

The setup wizard generates every secret a deployment needs. Most of them can be replaced later at the cost of a restart, or of everybody signing in again. One can’t: the AES key, which encrypts what the database holds. Back it up before anything else.

Back up the AES key

Lose this key and the database's secrets are lost with it

Without GOIABADA_AES_ENCRYPTION_KEY, a database backup restores to an auth server that can decrypt none of its client secrets, authenticator seeds or signing keys. Never keep the key only beside the database, and never in the same backup: a backup holding both gives every secret to whoever reads it.

1. Read the key where your setup keeps it:

   Docker Compose

   It’s GOIABADA_AES_ENCRYPTION_KEY, under goiabada-authserver in docker-compose.override.yml.

   Native binaries

   It’s GOIABADA_AES_ENCRYPTION_KEY in the env file, goiabada.env as the wizard writes it.

   Kubernetes

   It’s in the goiabada-encryption-key Secret. Read it out of the cluster:

   kubectl get secret goiabada-encryption-key -n goiabada -o jsonpath='{.data.aes-encryption-key}' | base64 -d

2. Store it where your database backups aren’t: a password manager, a secret manager, or an offline copy. Not in a repository, and not beside the backups.

3. Do it again after every rotation of the key, since the rotation puts the database under the new one.

4. Keep each old key as long as you keep a database backup taken under it. A rotation re-encrypts the live database only, so a backup from before it still needs the old key.

What each secret protects

Each server reads its own secrets from its environment, and only when it starts.

Secret	Read by	What it protects	Replaced without a rotation
GOIABADA_AES_ENCRYPTION_KEY	auth server	Everything secret the database stores: client secrets, the SMTP password, authenticator seeds, email verification, password reset and registration codes, and the private keys that sign tokens	The auth server can decrypt none of it
GOIABADA_AUTHSERVER_SESSION_AUTHENTICATION_KEY, GOIABADA_AUTHSERVER_SESSION_ENCRYPTION_KEY	auth server	The auth server’s session cookie, and the session contents it stores in the database	Every user is signed out once
GOIABADA_ADMINCONSOLE_SESSION_AUTHENTICATION_KEY, GOIABADA_ADMINCONSOLE_SESSION_ENCRYPTION_KEY	admin console	The admin console’s session cookie, and its session contents, administrators’ tokens included, which the auth server stores for it	Every administrator is signed out of the admin console once
GOIABADA_DB_PASSWORD	auth server	The database user’s password. Whoever has it and can reach the database reads and changes everything Goiabada stores	The auth server can’t connect until the database user has the same password
GOIABADA_ADMINCONSOLE_OAUTH_CLIENT_SECRET	both	The secret of the admin console’s client, admin-console-client. The admin console presents it at every sign-in and token refresh; the auth server reads it only at its first start, to create that client	The admin console refuses to start, and one already running can’t sign anybody in, until the client in the database has the same secret
GOIABADA_ADMIN_PASSWORD	auth server	The first administrator’s password, read only by the first start, which creates the account	Nothing. Change the administrator’s password in the admin console

Rotate secrets replaces each one without those costs.

Where your setup keeps them

Docker Compose

The wizard writes every secret into docker-compose.override.yml, under the service that reads it, and none into docker-compose.yml, which you can therefore commit. The override is plain text, and its mode, 0600, is its only protection: keep it out of version control and out of shared directories.

Anyone who can run docker on the host reads the secrets too, since docker inspect shows a container’s environment, and so does root.

Native binaries

The wizard writes one file, goiabada.env, holding the configuration and every secret, which both servers read. It’s plain text, and its mode, 0600, is its only protection: keep it out of version control, owned by the user the servers run as, and readable by that user alone.

Root reads it whatever its mode, and the environment of the running processes too.

Kubernetes

The wizard writes two Secrets into goiabada-secrets.yaml: goiabada-encryption-key, holding the AES key alone, and goiabada-secrets, holding every other secret. A Secret’s data is base64, which anyone can decode, so the file’s mode, 0600, is its only protection on disk.

Kubernetes secrets has the Secrets the manifest reads, other ways to create them, and who in the cluster can read the AES key.

When a secret changes

A server reads a secret when it starts and never again, so a change reaches it at its next restart, and not before. That’s what lets the rotations change a secret first and restart second.

Generate each key with openssl, as the wizard does: openssl rand -hex 64 for the two session authentication keys, and openssl rand -hex 32 for the session encryption keys and the AES key. A server refuses to start with a key that isn’t hex or isn’t that long, and names the variable.

To restore a database backup taken under an older AES key, start the auth server with that key as GOIABADA_AES_ENCRYPTION_KEY. Or start it with today’s key there and the old one as GOIABADA_AES_ENCRYPTION_KEY_PREVIOUS: it then re-encrypts the restored data to today’s key before it listens, as a rotation does.

Caution

Running the setup wizard again generates new secrets, and where its files already are it warns and asks before writing over them. If you use its output for a deployment that already has a database, copy your existing values over the new ones first: the AES key above all, since a new one can’t decrypt the database and the auth server refuses to start with it, then the database password and the admin console’s client secret, which must match what the database already holds, and the session keys, unless everybody signing in again is fine.

Next steps

Rotate secretsReplace each secret without signing anybody out.

Upgrade GoiabadaUpdate to a new release, and roll back.

Environment variablesEvery setting both servers read.