Configuration

The FerrisKey API is configured entirely through command-line flags, each of which has a matching environment variable. Every setting has a default that works for local development, so you only override what your deployment needs.

Run ferriskey-api --help to see the flags and their long descriptions straight from the binary.

Environment variables

Admin

The admin account is created on first boot in the master realm.

FerrisKey applies ADMIN_PASSWORD only while the admin user has no password. Changing the variable on a running deployment does not change the password: use the console. Starting with a different ADMIN_USERNAME creates a second admin user instead of renaming the first.

Database

The pool is per instance. A connection idle for 60 seconds is closed, down to the minimum. Each connection costs PostgreSQL a few MiB, so a smaller pool is lighter on the database.

Count more than the pool when you size PostgreSQL’s max_connections. With the config cache on (see Caching), each instance holds two extra connections outside the pool for LISTEN/NOTIFY. Across replicas, replicas × (DATABASE_MAX_CONNECTIONS + 2) has to fit under the server’s limit, next to every other client of that database.

Server

ALLOWED_ORIGINS deserves a note of its own. Each entry must be a serialized origin (scheme://host[:port]), with no path and no wildcard, and an invalid entry stops the server at start. It applies to every route, including the ones that carry no realm: /config, the health probes, and the API documentation. Clients also declare their own web origins per realm, but those only cover realm-scoped routes, so a console served from a different origin than the API still needs its origin listed here.

Console and webapp links

Leave WEBAPP_URL_FROM_REQUEST off unless one deployment serves several hostnames, each with the webapp at / and the API under SERVER_ROOT_PATH. When it is on:

• The server refuses to start without WEBAPP_ALLOWED_HOSTS. Links are built from the Host header, so an unlisted host could otherwise put an attacker’s address in password reset and magic link emails.
• Each entry is host, host:port or *.domain, where * stands for exactly one label: *.example.com matches acme.example.com, not example.com and not a.b.example.com. Case and one trailing dot are ignored. An entry without a port only matches the default port of the scheme.
• The scheme is https when X-Forwarded-Proto is https and http otherwise, so the proxy must set or overwrite that header.
• A request whose Host is missing, repeated, not ASCII or not on the list is refused with 400 on the routes that build a webapp link.
• A passkey stays bound to the host it was registered on: one registered on a.example.com does not work on b.example.com.

WEBAPP_URL still matters at start in this mode: it seeds the redirect URI of the admin console.

TLS

Both variables are required together. Set neither to serve plain HTTP and terminate TLS at your proxy.

Caching

Each instance caches realms and their settings, clients, the scopes assigned to a client with their protocol mappers, and the roles and groups of a service account. A write made through the API clears the entry at once on the instance that handled it. The other replicas see the change after the TTL.

The service account state matters most for the client_credentials grant: a change to a service account’s roles or groups, made on any instance, reaches new tokens only after the TTL.

Sessions and revoked tokens are cached for the same TTL, capped at 30 seconds. Replicas tell each other about changes through PostgreSQL LISTEN/NOTIFY on the channel ferriskey_token_state, so a logout or a revocation on one replica empties the caches of the others right away. While an instance has no working listener, it skips the cache and reads sessions from the database. LISTEN needs a connection that keeps its session, so connect to PostgreSQL directly or through a pooler in session mode, not in transaction mode.

With CONFIG_CACHE_TTL_SECONDS=0 nothing is cached, there is no listener and no extra connection per instance.

The per-client web origins that drive CORS are cached for 30 seconds per realm, whatever the TTL, and that delay is fixed. Changing them through the API refreshes the instance that handled the change at once. Other replicas catch up within 30 seconds.

Password hashing

New password hashes use Argon2id with the cost below.

These values only apply to new hashes. Verifying a password reads the cost from the stored hash, and when a user signs in with a stored hash that used another cost, FerrisKey replaces it with a hash at the configured cost. Raise the cost, and each user’s hash is upgraded at their next login.

The server checks the values at start and refuses these:

The default cost, 7168 KiB with 5 iterations and a parallelism of 1, is one of the Argon2id configurations OWASP lists.

The budget caps memory, not requests. A hash or verification that would push the total past the budget waits until memory frees up instead of allocating more, so a burst of logins queues rather than growing the process. Verifying a stored hash that costs more than the whole budget takes the entire budget and runs alone.

Keep the budget well under the container’s memory limit. The Helm chart gives the API pod a 512Mi limit by default, and Argon2 is only one part of what the process holds.

Secrets at rest

--help does not print the value. Secrets at rest covers the format, rotation and what stays unencrypted.

Authorization

With the variable off, those routes are not mounted and answer 404. Turning it on does not switch authorization on for anyone: each realm still has to enable tenant authorization for itself. See Authorization.

Logging

Outbound requests

FerrisKey refuses to call loopback and private addresses when it delivers webhooks or fetches client metadata documents. These two switches lift that rule, and each logs a warning at start while it is on.

Observability

Prometheus metrics are also exposed directly on /metrics, with no collector needed.

Client addresses and throttles

FerrisKey records the caller’s IP address in SeaWatch security events and Compass flows, and a few throttles count requests per address. By default the address is the one of the TCP peer. Behind an Ingress or any proxy, that is the proxy: every caller shares one address, the audit records are honest but of little use, and the throttles count all your users as one.

Set SERVER_TRUST_FORWARDED_FOR=true to take the address from X-Forwarded-For instead. FerrisKey reads the first, leftmost entry, so the proxy has to replace the header with the real client address rather than append to it. Only enable it when a proxy you control is the only way in. With the flag on, a client that reaches the API directly can write any address it likes, and that address is what gets recorded and throttled.

The throttles are fixed, kept in memory and counted per replica, so running three replicas triples the effective allowance. IPv6 callers are grouped by their /64 prefix.

Startup checks

The API validates its configuration at start and exits, printing the reason, when one of these holds:

A data migration that fails also stops the start. See Upgrading.

Generating the OpenAPI spec

The API binary carries a subcommand that prints its OpenAPI document without touching the database:

ferriskey-api gen-api --output openapi.json

Omit --output to write the spec to stdout.

Deployment examples

Docker Compose

services:
  api:
    environment:
      - DATABASE_HOST=db
      - DATABASE_PORT=5432
      - DATABASE_NAME=ferriskey
      - DATABASE_USER=ferriskey
      - DATABASE_PASSWORD=a-strong-password
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=a-strong-admin-password
      - ADMIN_EMAIL=admin@yourorg.com
      - ALLOWED_ORIGINS=https://iam.yourorg.com
      - WEBAPP_URL=https://iam.yourorg.com
      - LOG_FILTER=info

Bare metal

Set the variables directly, or put a .env file in the directory you start the server from. The server also looks in the parent directories.

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=ferriskey
DATABASE_USER=ferriskey
DATABASE_PASSWORD=a-strong-password
ADMIN_USERNAME=admin
ADMIN_PASSWORD=a-strong-admin-password
ADMIN_EMAIL=admin@yourorg.com
ALLOWED_ORIGINS=https://iam.yourorg.com
WEBAPP_URL=https://iam.yourorg.com
SERVER_PORT=3333
LOG_FILTER=info

Then run the server:

./ferriskey-api

Moving configuration between realms

Portal themes, portal layouts and email templates export and import as files, and password hashes from another IAM can be imported per user. See Export & Import.

SMTP configuration

Email delivery for magic links, password resets, and email verification is configured per realm, in the database, not through environment variables. Open Emails in the admin console sidebar, switch to the SMTP tab, and fill in the host, port, encryption mode, credentials and sender. The SMTP password is one of the values SECRETS_ENCRYPTION_KEYS encrypts.