---
title: "Authentication modes"
summary: "Local codes versus an identity provider, who owns roles in each, and what happens on every login."
description: "Why Fanout has two sign-in modes, what each one owns, and where the boundary between them sits."
status: preview
read_when:
  - "You are choosing between local sign-in and OIDC."
  - "You expect a provider group change to take effect and want to know when it does."
---
Fanout supports local sign-in and OIDC, selected by `FANOUT_AUTH_MODE`.
Both use the same [roles and capabilities](/docs/reference/roles), browser sessions
and account suspension rules.

## Local

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](#account-profiles-and-suspension)
for account APIs and [authentication operations](https://github.com/labstack/fanout/blob/main/docs/authentication.md)
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.

## OIDC

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

`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](https://github.com/labstack/fanout/blob/main/docs/authentication.md#oidc)
for public access and Microsoft Entra ID group-overage handling.

### 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

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

See [namespace access limits](/docs/reference/capabilities#operating-limits).
Dashboard access is scoped to the owner for every role, including administrators.