Config Reference

Config Reference

The config reference covers global runtime settings used by Xferity.

What belongs here

Global configuration usually includes:

• flow and partner directories
• state backend selection
• logging and audit settings
• security defaults and hardened mode
• UI and API settings
• authentication settings
• worker and runtime performance controls

How to read it

Use config reference when you need field-level meaning. Use deployment guides when you need environment-specific recommendations.

Authentication

auth.mode

Controls the browser login mode for the UI.

Supported values:

• oidc — browser UI uses the OIDC redirect/callback flow
• local — browser UI uses the local username/password sign-in form

Header token auth via ui.auth_token remains available for scripts and automation and is separate from auth.mode.

auth.local.username

The local operator username accepted by the browser login form when auth.mode=local.

• required when auth.mode=local
• no default value
• used as the persisted auth identity for the local browser login user

auth.local.password_ref

Secret reference for the local operator password when auth.mode=local.

Expected usage:

• env:...
• file:...
• vault:...

Example:

auth:
  mode: local
  local:
    username: admin
    password_ref: env:UI_LOCAL_PASSWORD

There is no default password.

When to use oidc

Use auth.mode=oidc when the deployment should rely on an identity provider for browser operator access.

When to use local

Use auth.mode=local for private/internal, early-rollout, lab/test, or air-gapped deployments where OIDC is not in use but the UI must still require authenticated browser access.

Local mode backend requirement

auth.mode=local currently requires:

state:
  backend: postgres

Reason:

local browser auth uses persisted browser session state and auth user records.

If this is misconfigured, startup/validation fails with an explicit message:

auth.mode=local requires state.backend=postgres because browser sessions use persisted auth state

Cookie and session expectations

For browser auth modes (oidc and local):

• session cookie is HttpOnly
• session cookie uses SameSite=Lax
• session cookie is Secure on HTTPS / trusted forwarded HTTPS
• session TTL uses auth.session_duration
• logout revokes the persisted session and clears the cookie

First-login behavior in local mode

On first successful local sign-in:

• the configured username and password reference are validated
• a persisted auth user is created if one does not already exist
• that local browser-auth user is created as an admin
• a normal persisted session is created