Configuration reference#

Source of truth: internal/configuration/config.go (Config, Defaults(), Validate(), applyEnv()). This page lists every key, its default, and what it does. Keys marked no effect are parsed and (where noted) validated but no code reads them yet; they are listed so operators do not rely on them. api/schemas/config.schema.json describes the same keys for editors and validators; the contract test TestConfigSchemaMatchesStructs fails when the server accepts a key the schema lacks or the schema lists a key the server rejects. Prefer this page for what a key does.

Loading rules#

• The YAML file is given with -config path or PROUDAUTH_CONFIG. Without a file the defaults below apply (and validation fails until required keys are set).

• Unknown keys are rejected, so typos fail startup instead of being ignored.

• Environment overrides (below) are applied after the file.

• Durations use Go syntax: 90s, 15m, 12h, 2160h (no d unit).

• Secret references (DEP-006): values documented as "secret ref" accept

  • file:/path — file contents, surrounding whitespace trimmed (Docker/Kubernetes secrets);
  • env:NAME — an environment variable;
  • cred:NAME — a systemd credential ($CREDENTIALS_DIRECTORY/NAME, from LoadCredential=);
  • vault:<mount>/data/<path>#<field> — a HashiCorp Vault KV v2 field. VAULT_ADDR and VAULT_TOKEN (or VAULT_TOKEN_FILE) come from the process environment; VAULT_ADDR must be https unless it is a loopback address;
  • kms:<path> — a key file wrapped by a KMS or HSM, unwrapped at use by keys.kms.command (below, keys.md);
  • any scheme registered by an operator-built adapter (configuration.RegisterSecretResolver).

  Any other string is used literally. In production, literals are refused for keys.root_keys, keys.pepper_keys, keys.signing_wrap_keys, the database password, storage.migration_database_url, SMTP password, metrics token, email-provider callback secret (delivery.email.events_secret), SMS webhook secret and challenge-provider secrets. A vault: request times out after 5 seconds and a kms: unwrap after keys.kms.timeout; no reference takes longer than 5 minutes. References other than key material are resolved again at each use (SMTP password, SMS and callback secrets, challenge-provider secrets), so a vault: or kms: reference there calls Vault or the KMS command each time.

• Key material (keys.*_keys[].ref) must resolve to 32 bytes encoded as hex or base64 (standard or URL alphabet, padded or not).

• There is no live reload and no file watcher: every change to the file or the environment takes effect when a process restarts, so a half-written file can never weaken a running process. Review a change with identity-cli config-diff first (below). Realm policy, clients and other realm configuration are not in this file; they change through the administration API (or configuration import) and are versioned and audited there.

• Validation rules are listed in installation.md.

Reviewing a change#

identity-cli config-diff (DEP-020, internal/configuration/diff.go, TestDiffClassifiesAndRedacts) compares the current file with a proposed one without connecting to the database:

identity-cli config-diff -from /etc/proudauth/config.yaml -to ./config.next.yaml
identity-cli config-diff -from /etc/proudauth/config.yaml -to ./config.next.yaml -json

• -from defaults to PROUDAUTH_CONFIG; -to is required. Both files are loaded like a server loads them, including the environment overrides of the shell that runs the command.
• The proposed configuration is validated first; an invalid file stops the command (proposed configuration is invalid: ...) and nothing is compared. The current file is only loaded, not validated.
• Each changed key is printed as <mark> key: old -> new (restart), where the mark ! flags a change that moves a security boundary and needs a second reviewer: mode, keys.*, sessions.*, tokens.*, security.*, impersonation.*, privacy.*, limits.*, webauthn.*, server.trusted_proxies, server.public_origin, server.internal_listen, server.metrics_token, server.host_policy, server.public_listen, server.tls_cert_file, server.tls_key_file, server.mtls_listen, server.mtls_origin, server.client_cert_header, federation.allow_private_network, federation.ca_file, saml.*, directory.enabled, directory.allow_private_network, directory.egress_allowlist, directory.ca_file, federation.egress_allowlist, delivery.allow_private_webhooks, delivery.egress_allowlist, delivery.email.allowed_sender_domains, delivery.email.events_secret, delivery.sms.webhook_secret, storage.database_url, storage.migration_database_url, storage.runtime_role, observability.metrics_enabled, observability.otlp_endpoint and workers.metrics_listen (DEP-020, TestDiffBoundaryKeys, TestDiffMutualTLSBoundaries). Other keys are not flagged: review them yourself.
• Values are shown as in a support bundle: secret references are printed, literal secrets as [REDACTED].
• -json prints {"valid": true, "changes": [{"key", "old", "new", "effect", "security_boundary"}]}. effect is always restart: every key in this file is read at process start.

Environment overrides#

Environment overrides fail closed (DEP-020, TestEnvParseErrorsFailClosed): a boolean variable must be one of true, True, TRUE, t, T, 1, false, False, FALSE, f, F or 0 (Go strconv.ParseBool), and PROUDAUTH_SMTP_PORT (1–65535), PROUDAUTH_ARGON_MEMORY_KIB (1–4194304) and PROUDAUTH_ARGON_TIME (1–100) must be integers in range. Anything else stops every binary at startup with environment: <VARIABLE>: ... instead of silently turning a protection off. Empty variables are ignored.

Top level#

server#

identity#

storage#

keys#

See keys.md before changing anything here.

sessions#

tokens#

security#

Rate-limit counters are fixed windows stored in PostgreSQL (rate_limit_counters) with digested keys, so every node shares them. A budget whose limit (or window) is 0 is not applied. Exhausted budgets on the custom APIs return 429 rate_limited with Retry-After; the token endpoint answers 429 slow_down.

Fixed budgets (not configurable): shared-signals pushes 600 per minute per transmitter and 1200 per minute per address; check-session origin checks 300 per minute per address; registry tokens 600 per minute per address, and 20 failed registry sign-ins per address per 15 minutes; dynamic client registration 20 per hour per address and 500 per hour per realm.

impersonation#

federation#

Upstream OIDC and GitHub-style OAuth connections (internal/federation). Connections themselves are realm data, managed through /api/v1/realms/{realm}/identity-providers.

OIDC discovery and JWKS caches last one hour per provider/issuer/URL in each server process. Concurrent misses share one fetch; unknown keys and failed metadata responses retry at most once a minute. Failure cooldowns also cover malformed JSON, issuer mismatches, redirects, oversized replies and timeouts (FED-017, NFR-006). A cancelled request stops its own wait; the shared fetch retains its independent fetch_timeout, including DNS. Valid cached signing keys remain usable within their ordinary TTL. Workload JWKS uses its documented five-minute cache and transport/status fallback; Shared Signals uses a ten-minute cache and bounds signature-triggered refreshes by the same minute. Budgets are per process and cache identity, not deployment-wide DB counters. Administrative configuration changes and fresh connection diagnostics invalidate their provider caches deliberately. No TLS, address/residency, response-size or signature check is relaxed.

saml#

SAML 2.0 identity provider (SAML applications) and broker (SAML connections), internal/saml (saml.md). Applications, connections and signing keys are realm data managed through /api/v1/realms/{realm}/saml/....

directory#

LDAP/Active Directory federation and synchronization, and outbound SCIM provisioning, internal/directory (directory.md, outbound-provisioning.md). Connectors are realm or organization data managed through /directory-connectors; these keys are deployment-wide bounds.

delivery#

Outbound HTTPS connections other than those to upstream identity providers and workload key sets (federation.ca_file) and to directories (directory.ca_file), such as webhooks, hooks, back-channel logout, outbound SCIM provisioning and the SMS gateway, verify certificates against the system trust store only; there is no delivery CA bundle. To reach a destination whose certificate comes from a private CA, add the CA to the trust store of the host or container image (on Linux the Go runtime also reads SSL_CERT_FILE, which replaces the system bundle, and SSL_CERT_DIR). scripts/interop-keycloak.sh does this for back-channel logout to Keycloak.

workers#

observability#

privacy#

limits#

Explicit bounds on input size and work per request (NFR-001). Each key has a safe range: every product feature works inside it, and a value outside it stops startup (limits.<key> must be <min>..<max>). Lower bounds follow from what the product itself sends or accepts: migration-adapter import batches of up to 192 KiB and SAML POST messages need a 256 KiB body, and a policy definition nested to its own limit (8 condition levels) inside a configuration document needs a JSON depth of about 24. Raise a limit only for a measured need: larger bodies, tokens and pages cost memory and time on every request that uses them.

extensions#

Trust for signed plugin packages (EXT-014, plugins.md). Realm-level extension settings are realm policy, not configuration: extensions.plugin_review (second_admin by default, or single_admin) and extensions.workflow_publish_approval (default false; workflows.md).

webauthn#

Deployment-wide passkey trust settings (PASS-009, PASS-010, internal/configuration/webauthn.go). Realm passkey policy (attestation, allow and block lists, related origins, credProtect) is realm policy under webauthn, not configuration (passkey-trust.md). identity-cli config-diff marks every webauthn.* change as a security boundary change.

Values that are not configuration#

Some limits are fixed in code: PAR request lifetime 60 s; device polling interval 5 s (+5 s per slow_down); DPoP proof age 2 minutes; client assertion lifetime at most 5 minutes; handoff and impersonation caps; setup tokens 72 h for administrator-created users and 2 h for assisted recovery; job download tokens 5 minutes; previous webhook secret valid 24 h after rotation; signing-key cache 5 s; realm cache 2 s (also the delay before an emergency grant control applies on every node); registered-origin cache 5 s; maintenance and debug-window state cache 2 s; debug windows at most 1 h in production (24 h otherwise); lifecycle jobs at most 100 accounts per rule, realm and run; bulk user operations at most 1000 accounts per job. Shared signals: 5 streams per receiver, 8 push attempts, undelivered events expire after 7 days and are deleted after 14, received-event records kept 30 days, 50 transmitters per realm, transmitter key sets cached 10 minutes (shared-signals.md). Authentication flow revisions: 20 open drafts per realm, 200 simulation cases per request. Federation transfers: 50000 entries per transfer, 2000 per request. Registry tokens: 60–3600 s per registry service. Protocol extensions: JARM responses expire after 10 minutes; fapi2 clients get authorization codes of at most 60 s and access tokens of at most 10 minutes; dynamic registration allows 20 registrations per hour per network and 500 per realm; HOTP enrollment expires after 15 minutes and resynchronization allows 5 attempts per 15 minutes; workload key sets are cached 5 minutes (refetched at most once a minute for an unknown key) with a 60 s clock skew for assertions; relationship decisions stop at depth 6, 64 object reads and 1000 tuples per object, and list-objects at 5000 candidates and 1000 checks; policy engine answers at most 64 KiB; access reviews cover at most 10000 assignments; elevation lasts 5 minutes to 7 days.