Authentication modes
Fanout supports local sign-in and OIDC, selected by FANOUT_AUTH_MODE.
Both use the same roles and capabilities, browser sessions
and account suspension rules.
Active users sign in with an emailed code when SMTP is configured. Without
SMTP, an operator with access to the control database mints a single-use link
with fanout login-link <email>. Administrators manage accounts and roles
inside Fanout. See account profiles and suspension
for account APIs and authentication operations
for invitation delivery and recovery.
FANOUT_SELF_SIGNUP allows verified email addresses to create viewer accounts.
It defaults to false and requires complete SMTP configuration. Self-signup is
available only after the first administrator completes setup. Viewers can read
all telemetry, manage their own dashboards and run the built-in agent.
The built-in agent sends requests to your configured model provider and can
incur charges. Enabling self-signup grants that access to anyone who can verify
an email address.
An identity provider handles sign-in. Group and domain allowlists are evaluated on every login, including for linked identities. Removing a user’s eligibility blocks their next login; it does not revoke a browser session already issued. Suspending the account in Fanout blocks access and revokes its sessions.
If neither FANOUT_OIDC_ALLOWED_GROUPS nor FANOUT_OIDC_ALLOWED_DOMAINS is
configured, no eligibility allow policy is enforced; membership is managed locally.
Account provisioning
Section titled “Account provisioning”FANOUT_OIDC_AUTO_PROVISION creates eligible accounts on first sign-in after
administrator setup. It requires an allowed group or domain. The role comes
from the configured group mapping, falling back to FANOUT_OIDC_DEFAULT_ROLE
(viewer).
FANOUT_OIDC_EMAIL_VERIFICATION=required requires a verified email. The issuer
policy trusts the configured issuer and requires an allowlist. See
OIDC operations
for public access and Microsoft Entra ID group-overage handling.
Role ownership
Section titled “Role ownership”If FANOUT_OIDC_ADMIN_GROUPS or FANOUT_OIDC_OPERATOR_GROUPS is configured, the
provider reapplies the mapped role on every login. Users outside mapped groups
receive FANOUT_OIDC_DEFAULT_ROLE. A role change revokes browser sessions and
writes an audit event in the same transaction.
Without a role-group mapping, administrators manage roles inside Fanout and OIDC sign-in preserves them. Reconciliation cannot demote the last active administrator; promote a second administrator before applying that mapping.
Account profiles and suspension
Section titled “Account profiles and suspension”Administrators create active accounts with POST /api/users, supplying email,
display_name and role. Edit profiles with PATCH /api/users/{id}; change
roles with PATCH /api/users/{id}/role and {"role":"viewer"}. Suspend with
PATCH /api/users/{id}/status and {"status":"suspended"}; restore with
{"status":"active"}. Unknown fields and invalid statuses return 400.
Email, role and status changes revoke browser sessions. Suspension blocks local
and OIDC sign-in and OAuth token use. Reactivation does not restore revoked
sessions. The last active administrator cannot be demoted, suspended or deleted.
Access boundaries
Section titled “Access boundaries”See namespace access limits. Dashboard access is scoped to the owner for every role, including administrators.