Configuration¶

Every setting is read from the environment or a .env file, prefixed IDEN_. Defaults are development defaults — the ones that matter in production are called out below the table.

Where settings live¶

There are several .env files in the repository, which looks like more configuration than it is. Each belongs to one process, and only one of them is ever in play at a time:

They hold overlapping keys but cannot hold the same values: provider/.env points the database at localhost:5432, and inside a container that address is the container itself. Each has an .env.example beside it to copy.

Every setting in the table below can be set from deploy/.env, whether or not it appears in deploy/.env.example — docker-compose.yml names them all with their defaults. The one exception is IDEN_BOOTSTRAP_ADMIN_PASSWORD, deliberately: a value there would sit in the container's environment for as long as the container lives, where docker inspect reads it.

The provider¶

The two frontends¶

auth-ui and dashboard are static builds, so their configuration is read at container start rather than compiled in — one image serves any deployment. The entrypoint writes these into /config.js.

Under pnpm dev there is no container, so the same three are read from Vite environment variables with a VITE_ prefix — VITE_IDEN_ISSUER, VITE_IDEN_ORG_NAME, VITE_IDEN_ORG_LOGO. Each app has an .env.example to copy.

The four that matter in production¶

IDEN_ISSUER is the identity of the deployment. It goes into every token and every client validates against it. Set it to the public HTTPS URL, and treat changing it as invalidating every token in circulation.

IDEN_SIGNING_KEY_DIR holds the private keys that sign every token. Anyone who reads them can mint a token for anyone. Mount it read-only, keep it off the image, and back it up somewhere you would be comfortable keeping a password.

IDEN_TOTP_KEY_FILE encrypts the one credential IDEN cannot hash. Verifying a time-based code means recomputing it, so the secret has to be readable — and without this a database dump would be a working second factor for every enrolled account, while the passwords beside it are argon2. The key lives in the signing key directory by default, which is already mounted read-only, kept out of the image and backed up. Replace it and every enrolled authenticator stops verifying, and those people cannot sign in until an administrator clears their enrolment.

IDEN_ENV=prod makes the session cookie Secure, so it is never sent over plain HTTP. It also withholds the interactive docs, which are the complete shape of the admin API.

IDEN_FORWARDED_ALLOW_IPS decides who the caller is. IDEN reads the address from the socket unless the peer is named here, in which case it takes the address that peer states in X-Forwarded-For. Both the per-address rate limits and the ip column of the audit log rest on the answer.

Empty behind a proxy makes every per-address limit a deployment-wide one — TOKEN_PER_IP stops being 120 requests a minute per caller and becomes 120 a minute in total — and writes the proxy's address into every audit row. * accepts the header from anyone, which makes both forgeable. Name the proxy's network, and no more of it than necessary.

Rotating a signing key¶

Keys sort by filename and the last one signs, so a date-stamped name makes the newest key active:

keys/
  iden-20260101.pem     ← was signing
  iden-20260801.pem     ← now signing

Keep the old key in place until every token signed with it has expired — it is still published in JWKS, so tokens already issued keep validating. Then delete it.