user-engine/docs/configuration.md

Configuration Boundaries

Standalone Mode

Standalone mode is for local development, tests, prototypes, and small single-service deployments.

Expected characteristics:

• local configuration file or environment variables;
• local database or file-backed persistence during early development;
• fixture or local identity claims adapter;
• deterministic authorization test adapter;
• no password, MFA, or token issuance responsibility inside user-engine.

Platform Mode

Platform mode is for a NetKingdom-aligned shared service deployment.

Expected characteristics:

• verified IAM Profile claims arrive from an identity layer;
• authorization decisions are requested through the authorization check port;
• runtime secrets are delivered through a scoped secret provider;
• audit records and outbox events are correlated with platform sinks;
• tenant and application bindings are explicit.

Secret Names

The code should refer to logical secret names, not platform paths. Concrete secret lookup is owned by the active SecretProvider adapter.

Initial logical names:

• database.url
• event.signing_key
• webhook.shared_secret

Production Guardrails

• Local issuers must be rejected by production adapters.
• Sensitive writes must fail closed when authorization is unavailable.
• Claims enrichment must be optional and must not make user-engine a token issuer.

Portal integration settings

The production portal requires its existing database, OIDC, proxy-marker, and identity-provisioning settings. Platform tenant creation is enabled only when both of these settings are present:

• USER_ENGINE_TENANT_MANAGEMENT_URL — tenant-authority base URL;
• USER_ENGINE_TENANT_MANAGEMENT_TOKEN — workload-scoped bearer token.

The adapter calls POST /v1/tenants with correlation and idempotency headers. The token is never returned in errors, audit records, outbox events, or browser responses. When the settings are absent, ordinary portal behavior remains available and platform tenant creation fails closed as unavailable.

Public registration is off unless USER_ENGINE_PUBLIC_REGISTRATION=true. Enabling it also requires the verification adapter and allow-lists:

• USER_ENGINE_REGISTRATION_VERIFICATION_URL
• USER_ENGINE_REGISTRATION_VERIFICATION_TOKEN
• USER_ENGINE_REGISTRATION_CLIENTS
• USER_ENGINE_REGISTRATION_TENANTS
• USER_ENGINE_REGISTRATION_PASSWORD_SETUP_ORIGINS
• USER_ENGINE_MAIL_URL and USER_ENGINE_MAIL_TOKEN when verification mail is delivered through the outbox

The service fails closed when those settings are absent. Do not add a placeholder or reused credential to turn the flag on.

USER_ENGINE_MAIL_CLIENT_BINDINGS is optional and unset by default. When unset, invitation mail envelopes keep the legacy shape (no client_id). When set, it is a JSON list of [tenant_glob, client_id] pairs (1–128 rows, unique globs, case-sensitive whole-string */? matching), for example [["tenant:*-family", "coulomb-social"]]. Each invitation mail carries the single matching client_id, so email-connect can admit it as a scoped caller (EMAIL-WP-0008). A tenant with no match, or with matches naming different clients, is denied as mail_binding_denied before either delivery lane is contacted; the platform event never carries client_id. An invalid value stops startup — it never falls back to the legacy shape.

Application access readback

Off unless USER_ENGINE_READBACK_URL is set. When it is set, these are also needed:

• USER_ENGINE_READBACK_URL: base URL of access-engine's dedicated flex-auth-application-readback pin;
• USER_ENGINE_READBACK_TOKEN_FILE: the readback caller token, read on every call. This is a separate file from USER_ENGINE_FLEX_AUTH_TOKEN_FILE. The pin admits it only under the application-readback binding, so it can never act on /v1/check;
• USER_ENGINE_READBACK_TIMEOUT: optional, in seconds (default 3).

The account page (/onboarding) then lists each workload bound in all three records:

• the user-engine application record;
• its binding's protected_system_id;
• the readback system's client_binding, whose issuer and client id must equal our OIDC issuer and the binding's oidc_client_id.

The rows are rendered as follows. No row is ever inferred as allow:

access-engine answer	Shown
allow before expires_at	Available
deny	Not available
not_applicable	Not available: not offered here
failure, missing row, or allow past or without expires_at	Not available: could not be checked

Answers are read only on account-page views. They are reused per session and subject for at most 60 seconds, and never past the earliest allow's expires_at. Logout drops them. A failed read is not reused. Contract: access-engine docs/application-access-readback.md (FLEX-DEC-2026-019).

Authenticator management handoff

USER_ENGINE_MFA_MANAGEMENT_URL is optional and empty by default. When set, the public /security help page offers a fixed HTTPS provider-management link. No credentials, query parameters or fragments are allowed in this URL. The portal never collects an OTP, reads an OTP seed, or marks a factor enabled from a return URL. It cannot currently display authoritative enrollment status.

Enable only after verifying provider self-service identity checks, confirmation before activation, cancellation/recovery, and enrolled-factor enforcement under KEY-WP-0035. A reachable provider homepage alone is insufficient. Leave unset while this dependency is unresolved; users get an explicit unavailable state and help without needing to complete OTP login first. See account journeys.