Configuration¶

All backend configuration is provided through environment variables.

JustIAM supports two deployment modes:

Single-tenant (default) — one instance, one database. DATABASE_URL, JWT_SECRET, and OIDC_ISSUER are supplied as env vars.
Multi-tenant — one instance serves multiple tenants, each isolated at its own hostname. Per-tenant credentials are loaded from Kubernetes Secrets or a YAML file.

Single-tenant mode¶

Required variables¶

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgres://justiam:secret@postgres:5432/justiam?sslmode=disable`
`JWT_SECRET`	HMAC secret used to sign portal session JWTs	A long random string
`OIDC_ISSUER`	Public URL of JustIAM — used as the OIDC issuer and WebAuthn relying-party origin	`https://justiam.example.com`

Optional variables¶

Variable	Default	Description
`PORT`	`8080`	HTTP port the backend listens on
`LOG_LEVEL`	`info`	Logging verbosity (`debug`, `info`, `warn`, `error`)
`GIN_MODE`	`release`	Gin framework mode (`release` or `debug`)
`APP_VERSION`	`dev`	Version string returned by `/api/v1/version` and logged on startup
`TRUSTED_PROXIES`	(none)	Comma-separated CIDR list for `X-Forwarded-For` trust (e.g. `10.1.0.0/16`)
`GRPC_PORT`	`9090`	Port for the agent gRPC server. External agents connect here to receive task assignments. Set to empty (`GRPC_PORT=`) to disable.

Kubernetes secrets example¶

apiVersion: v1
kind: Secret
metadata:
  name: justiam-secrets
  namespace: justiam
type: Opaque
stringData:
  DATABASE_URL: "postgres://justiam:secret@postgres:5432/justiam?sslmode=disable"
  JWT_SECRET: "replace-with-a-long-random-string"
  OIDC_ISSUER: "https://justiam.example.com"

Reference these in k8s/backend.yaml as envFrom.secretRef.

Multi-tenant mode¶

In multi-tenant mode the backend does not read DATABASE_URL, JWT_SECRET, or OIDC_ISSUER at startup. Instead, it loads per-tenant configuration from one of two sources:

Option A — Kubernetes Secrets (production)¶

Variable	Default	Description
`TENANTS_NAMESPACE`	`justiam-mt`	Kubernetes namespace that contains the tenant ConfigMap and Secrets

The backend reads:

ConfigMap justiam-tenants (key tenants) — newline or comma-separated list of tenant slugs.
Secret justiam-tenant-<slug> per slug — must contain:

Key	Required	Description
`db_url`	Yes	PostgreSQL connection string for this tenant
`jwt_secret`	Yes	HMAC secret for portal JWTs
`vault_key`	No	AES-256 key for the built-in secrets vault
`login_worker_mode`	No	Where claim/attribute scripts run during OIDC and SAML login flows. `""` or `inline` (default) = in-process on the backend pod; `shared` = `login-worker-shared` deployment; `dedicated` = `login-worker-<slug>` deployment. Infrastructure failures always fail-open so users are not blocked by a down worker.
`login_worker_url`	No (required when `login_worker_mode=shared\\|dedicated`)	Base URL of the login-worker pod, e.g. `http://login-worker-shared.justiam-mt.svc:8090`
`login_worker_token`	No (required when `login_worker_mode=shared\\|dedicated`)	Bearer token for backend → login-worker auth. Must match `WORKER_TOKEN` in the login-worker pod.
`login_worker_agent_token`	No (required when `login_worker_mode=shared`)	Agent token the shared login-worker uses to authenticate backend API calls for this tenant. Auto-provisioned from `worker_agent_token` when switching to shared mode via the control plane. Dedicated workers use the `AGENT_TOKEN` env var in their pod Secret instead.
`login_worker_max_concurrent`	No	Per-tenant concurrency cap for login script executions on the login-worker. `0` (default) uses the worker's `MAX_CONCURRENT_PER_TENANT` env var.
`worker_mode`	No	How scheduled tasks are executed: `""` / `inline` (default, run inside the backend process) or `agent` (external gRPC agent). See External Agents.

The OIDC issuer is derived automatically from the request Host header (https://<slug>.totmicro.com).

Option B — YAML file (development / CI)¶

Variable	Description
`TENANT_CONFIG_FILE`	Path to a YAML file listing tenant configurations

Example tenants.yaml:

tenants:
  - slug: acme
    db_url: "postgres://acme:secret@localhost:5432/acme?sslmode=disable"
    jwt_secret: "acme-jwt-secret"
  - slug: globex
    db_url: "postgres://globex:secret@localhost:5432/globex?sslmode=disable"
    jwt_secret: "globex-jwt-secret"

When TENANT_CONFIG_FILE is set, TENANTS_NAMESPACE is ignored.

Settings (runtime)¶

Many operational parameters are stored in the database and can be changed at runtime from the Settings page in the admin UI without restarting the server. See Settings for the full list.

OIDC RSA key¶

JustIAM generates its own RS256 signing key pair on first startup and stores it in the system_config table. You do not need to supply an external key. The public key is exposed at /.well-known/jwks.json.

In multi-tenant mode each tenant has its own independently generated key pair.

SMTP (optional)¶

Email is only required for password-reset functionality. Configure it via the Settings page:

SMTP host / port / username / password — standard SMTP relay
From address — the From: header on outgoing emails

If smtp_host is empty, password reset emails are disabled.