coulomb/user-engine
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
user-engine/docs/configuration.md
tegwick cb67b4318c
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Has been cancelled
Details
Finish USER-WP-0022; leave public registration fail-closed 
In-repo journey, recovery, and security matrix are complete (150 tests).
T03/T04 stay cancelled at coulomb-social and KeyCape. Production enablement
remains an operator flag plus governed verification and SMTP credentials.
2026-08-19 14:34:00 +02:00

2.6 KiB
Raw Permalink Blame History

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.