tegwick
a9ff77d21d
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a092fe-13b1-7f12-ac74-7d258af4d79c
87 lines
3.4 KiB
Markdown
87 lines
3.4 KiB
Markdown
# 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.
|
|
|
|
|
|
## 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](account-journeys.md).
|