Configuration

How configuration works#

You configure aegis entirely through environment variables. The gateway takes no command-line flags and reads no configuration file. Its own code reads the 77 variables in the reference tables below; the AWS SDK behind the credential broker also reads the standard AWS variables. Each optional subsystem stays off until the variables it needs are set.

To turn a feature off, unset its variable rather than setting it to an empty string. Many variables treat an empty value as set: an empty AUTH_ALLOWED_TENANTS refuses every tenant, and an empty DATABASE_URL still switches the gateway to the Postgres catalog. The Helm chart omits empty values for this reason.

Most subsystems log their state at startup, for example Auth: DISABLED, RBAC DISABLED (no DATABASE_URL) or Audit log DISABLED (no CLICKHOUSE_URL). Read that log after each change to confirm what is actually on.

Two stores are checked before the gateway serves traffic. It connects to Redis at startup and exits if it cannot. When DATABASE_URL is set, it tries to load the catalog 10 times, 2 seconds apart, and exits if Postgres is still unreachable. ClickHouse is not checked this way: if the audit schema cannot be set up at startup, the gateway starts with the audit log off and logs Audit log DISABLED, so look for that line after every deploy.

A production baseline looks like this. Replace every placeholder, and supply the secret values from your secret store rather than from a file in source control.

REDIS_URL=redis://redis:6379
DATABASE_URL=postgres://USER:PASSWORD@postgres:5432/DBNAME
CLICKHOUSE_URL=http://clickhouse:8123
AUDIT_HMAC_KEY=REPLACE_WITH_A_LONG_RANDOM_SECRET
AUTH_JWKS_URL=https://idp.example.com/.well-known/jwks.json
AUTH_ISSUER=https://idp.example.com/
AUTH_AUDIENCE=aegis
METRICS_TOKEN=REPLACE_WITH_A_RANDOM_TOKEN

Variable reference#

Core and stores#

Authentication#

Verifiers are tried in order (HS256, then JWKS, then the gateway's own issuer when OAUTH_ISSUER is set), and the first one that validates wins. Each verifier pins its algorithm, so an HS256 token can never pass an RS256 verifier. AUTH_ISSUER and AUTH_AUDIENCE scope the JWKS verifier only. With no verifier configured, authentication is off and every caller runs as anonymous in tenant default.

Rate limits#

Limits use fixed one-minute windows in Redis. A limited call gets HTTP 429 with -32029. If Redis is unreachable, the limiter lets calls through.

Threat detection#

Audit#

Upstream resilience and TLS#

An open breaker or a full concurrency cap fails fast with -32063. For each mTLS pair, a _FILE path takes precedence over the inline _PEM value. The settings apply to every https:// upstream and have no effect on http:// upstreams. If they are set but invalid, for example a certificate without its key, the gateway refuses to start rather than falling back to plain TLS.

Metrics#

With neither variable set, /metrics returns 503. When both are set, the token applies.

Commercial modules#

The broker reads AWS credentials from the standard AWS credential chain, such as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY or an IAM role provided by your platform. Federated login for /oauth/authorize is not implemented yet. Without OAUTH_DEV_AUTHORIZE, that endpoint returns 501.

Production checklist#

Put these settings in place before the gateway receives real traffic:

• Configure at least one verifier. With none, every caller runs as anonymous.
• Prefer AUTH_JWKS_URL with AUTH_ISSUER and AUTH_AUDIENCE. Unset AUTH_HS256_SECRET entirely, not just to an empty string. Every configured verifier is accepted, so anyone holding the shared secret could sign a token for any subject.
• Set DATABASE_URL so the catalog and RBAC are enforced.
• Set CLICKHOUSE_URL and a strong, random AUDIT_HMAC_KEY, then confirm the startup log reports the audit log as enabled.
• Set METRICS_TOKEN rather than METRICS_PUBLIC.
• Keep the stores private. Put Redis, Postgres and ClickHouse on a network segment that only the gateway can reach, and connect with the redis://, postgres:// and http:// URL forms shown in the baseline.
• Keep logging at info. The gateway sets its log level to info in code and does not read RUST_LOG. If you raise it in your own build, keep production at info, because HTTP client wire logging at debug and trace can include header values.
• Never set OAUTH_DEV_AUTHORIZE. If you use OAuth issuance, set a stable OAUTH_SIGNING_KEY_PEM.
• Keep secret values out of source control. In the Helm chart, prefer pointing secrets.existingSecret at a Secret you manage, for example through an external secrets operator. If you pass values to the chart instead, use --set or a values file kept out of git. Put DSNs that embed a password under secrets.*, not config.*, which renders a plaintext ConfigMap.

Related pages#

• Deploy aegis: how the Helm chart and Compose stack set these variables.
• Identity and access: verifiers, tenants and RBAC in depth.
• Threat detection: what each detector and mode does.
• Audit and observability: the audit chain, metrics and SIEM export.
• Error codes: the refusal codes these settings produce.