Skip to content

Authentication Modes

Trobar authenticates in one of three modes, set by AUTH_MODE. In every mode, ADMIN_USERNAME names the account that is promoted to admin.

Mode What it does
local (default) Every user has a username/password stored by the app itself. Simplest way to run it — no external auth system needed. Fail-closed default.
oidc Recommended for SSO. The app is an OpenID Connect client: it redirects users to your identity provider and cryptographically verifies the returned ID token (signature + standard claims). Works with any OIDC provider — Authentik, Authelia, Keycloak, Zitadel, … — configured directly, no ForwardAuth middleware.
forward Trust X-authentik-*-style identity headers set by a ForwardAuth reverse proxy. The app performs no authentication of its own in this mode. (authentik is accepted as an alias.)

Prefer oidc over forward unless you specifically run a blanket ForwardAuth proxy: it's verified in-app (nothing to spoof) and needs no per-app proxy configuration.

local

Nothing else to configure. The first visit creates the admin account (locked to ADMIN_USERNAME); other household accounts are created in the Administration panel. Don't expose the instance publicly until first login is done.

oidc

Set OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET, and register the app in your IdP with redirect URI https://<your-host>/oidc/callback. Users are auto-provisioned on first login, taking the username from OIDC_USERNAME_CLAIM (default preferred_username). The /login page still offers a local password as a break-glass fallback for when the IdP is down — under oidc mode this is an admin-only operational control, set from Administration → Configuration, not from a regular user's Profile.

If the IdP can't be reached, Sign in with SSO says so on the login page, instead of failing with an error page, and that an administrator can still sign in with their local password (the break-glass fallback above). Logging out still works: the Trobar session ends, and only the IdP's own session (OIDC_LOGOUT) is left open until it's reachable again.

Variable Default Purpose
OIDC_ISSUER (unset) Your IdP's issuer URL (discovery at {issuer}/.well-known/openid-configuration)
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET (unset) Credentials from the app you register in your IdP
OIDC_SCOPES openid profile email Requested scopes
OIDC_USERNAME_CLAIM preferred_username Which ID-token claim maps to the app username
OIDC_LOGOUT false If true, logout also ends the SSO session at the IdP (RP-initiated logout)

forward

The proxy must gate every route

The app performs no authentication of its own in this mode — it trusts the identity headers it is handed. If the app port is reachable directly, anyone can set that header themselves and become admin.

Set FORWARD_AUTH_SECRET — a shared secret your proxy injects as X-Forward-Auth-Secret — so a stray direct request fails closed.

A request that arrives without the identity header is refused (401), and the refusal is logged with the path it asked for. That's a proxy that isn't setting the header, or a request that reached the app's port directly. Only a local development server (TROBAR_DEV_SERVER) lets it in, as DEV_USER.

Accounts are matched by username. A user the proxy names is the Trobar account with that username, created on first visit. So switching an existing install to forward (or to oidc, which does the same with the username claim) links each existing account to the identity of the same name, with no other check. Make sure the usernames agree before you switch.

The profile menu has no Log out in this mode: the proxy signs users in, and would sign them straight back in. Sign out at the proxy or your identity provider instead. On the emergency port, where Trobar signs the admin in itself, Log out is there.

EMERGENCY_PORT (forward mode only)

In forward mode the proxy fronts everything — so if your SSO stack is down, even a valid local session cookie is useless, because the proxy never lets the request through. EMERGENCY_PORT opens a second listener the proxy does not front, so the admin's break-glass local password still works during an IdP outage:

Publish it on a LAN/VPN address only

e.g. 192.168.1.10:5001:5001 — never to the internet. This listener is deliberately the one your proxy does not front, so it sits outside whatever gating the proxy provides.

  • Identity headers are never trusted on this port, regardless of mode.
  • It refuses to start unless AUTH_MODE=forward — in local/oidc the normal port already serves local logins, and an extra listener would be pure attack surface.

If you run local or oidc, ignore this option entirely.

See also