Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 0 additions & 5 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -85,11 +85,6 @@
# Default: 0
# FANOUT_DUCKDB_THREADS=

# FANOUT_FIRST_ADMIN_EMAIL; string
# Creates this address as the first active administrator when the control database has no users, instead of printing the one-time setup URL; ignored once users exist.
# Default: (empty)
# FANOUT_FIRST_ADMIN_EMAIL=

# FANOUT_HEALTHCHECK_CERT_FILE; string
# Selects the client certificate fanout healthcheck presents; requires FANOUT_HEALTHCHECK_KEY_FILE and FANOUT_TLS_CLIENT_CA_FILE.
# Default: (empty)
Expand Down
4 changes: 1 addition & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,7 @@ docker run --name fanout --restart unless-stopped -p 7520:7520 \
```

Open the one-time setup URL printed by the container and create the first administrator. Fanout
displays the ingest token exactly once; save it with your collector secrets. To skip the setup URL,
set `FANOUT_FIRST_ADMIN_EMAIL` and issue the first ingest token after signing in; see
[first boot](https://fanout.run/docs/get-started/first-boot). For later sign-in
displays the ingest token exactly once; save it with your collector secrets. For later sign-in
without SMTP, mint a 15-minute, single-use link against the running container's control database:

```sh
Expand Down
32 changes: 2 additions & 30 deletions cmd/fanout/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -205,12 +205,12 @@ func main() {
auditStore := auth.NewAuditStore(sqlite.DB)
setup := auth.NewSetup()

setupRequired, err := prepareFirstAdministrator(cfg.FirstAdminEmail, userStore)
userCount, err := userStore.CountUsers()
if err != nil {
slog.Error("auth status init failed", "err", err)
os.Exit(1)
}
if setupRequired {
if userCount == 0 {
token, _, err := setup.Rotate()
if err != nil {
slog.Error("setup token init failed", "err", err)
Expand Down Expand Up @@ -724,34 +724,6 @@ func browserLoginURL(cfg config.Config) *url.URL {
return loginURL
}

// prepareFirstAdministrator applies FANOUT_FIRST_ADMIN_EMAIL and reports whether the
// control database still has no users, in which case the caller opens the
// one-time setup URL. The administrator is created only in an empty database; once
// any user exists the setting never creates, promotes or reactivates anyone.
func prepareFirstAdministrator(firstAdminEmail string, users *auth.UserStore) (bool, error) {
if firstAdminEmail != "" {
firstAdmin, outcome, err := users.DesignateFirstAdmin(firstAdminEmail)
if err != nil {
return false, fmt.Errorf("designate first administrator from FANOUT_FIRST_ADMIN_EMAIL: %w", err)
}
switch outcome {
case auth.FirstAdminCreated:
slog.Info("auth: first administrator created from FANOUT_FIRST_ADMIN_EMAIL; no setup URL is issued", "email", firstAdmin.Email)
case auth.FirstAdminPresent:
if firstAdmin.Role != auth.RoleAdmin || firstAdmin.Status != auth.UserStatusActive {
slog.Warn("auth: FANOUT_FIRST_ADMIN_EMAIL names an existing account that is not an active administrator; it was left unchanged", "email", firstAdmin.Email, "role", firstAdmin.Role, "status", firstAdmin.Status)
}
case auth.FirstAdminRefused:
slog.Warn("auth: FANOUT_FIRST_ADMIN_EMAIL ignored; the control database already has users and none has this email, so no account was created. Unset it, or have an administrator add the account", "email", firstAdmin.Email)
}
}
count, err := users.CountUsers()
if err != nil {
return false, err
}
return count == 0, nil
}

func printSetupBanner(httpAddr, token string) {
lines := []string{
"============================================================",
Expand Down
87 changes: 0 additions & 87 deletions cmd/fanout/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ import (
"errors"
"flag"
"io"
"log/slog"
"math/big"
"net"
"net/http"
Expand Down Expand Up @@ -220,92 +219,6 @@ func TestCreateLoginLink(t *testing.T) {
}
}

func TestPrepareFirstAdministratorWithoutFirstAdminEmailKeepsSetup(t *testing.T) {
sqlite, err := store.NewSQLite(":memory:")
if err != nil {
t.Fatalf("NewSQLite: %v", err)
}
defer sqlite.Close()
users := auth.NewUserStore(sqlite.DB)
setupRequired, err := prepareFirstAdministrator("", users)
if err != nil || !setupRequired {
t.Fatalf("prepareFirstAdministrator = (%v, %v), want (true, nil)", setupRequired, err)
}
if count, _ := users.CountUsers(); count != 0 {
t.Fatalf("users = %d, want 0", count)
}
}

func TestPrepareFirstAdministratorCreatesAdministratorWhoCanUseLoginLink(t *testing.T) {
cfg := config.Config{
AuthMode: "local",
AuthCodeSecret: "0123456789abcdef0123456789abcdef",
DataDir: t.TempDir(),
Addr: ":7520",
FirstAdminEmail: "First@Example.com",
}
if err := os.MkdirAll(cfg.ControlDir(), 0o755); err != nil {
t.Fatalf("MkdirAll: %v", err)
}
sqlite, err := store.NewSQLite(cfg.ControlSQLitePath())
if err != nil {
t.Fatalf("NewSQLite: %v", err)
}
users := auth.NewUserStore(sqlite.DB)
setupRequired, err := prepareFirstAdministrator(cfg.FirstAdminEmail, users)
if err != nil || setupRequired {
t.Fatalf("prepareFirstAdministrator = (%v, %v), want (false, nil)", setupRequired, err)
}
firstAdmin, err := users.GetByEmail("first@example.com")
if err != nil || firstAdmin.Role != auth.RoleAdmin || firstAdmin.Status != auth.UserStatusActive {
t.Fatalf("firstAdmin = %+v err = %v, want active admin", firstAdmin, err)
}
// A restart with the same setting is a no-op, and still issues no setup URL.
setupRequired, err = prepareFirstAdministrator(cfg.FirstAdminEmail, users)
if err != nil || setupRequired {
t.Fatalf("restart prepareFirstAdministrator = (%v, %v), want (false, nil)", setupRequired, err)
}
if count, _ := users.CountUsers(); count != 1 {
t.Fatalf("users = %d, want 1", count)
}
if err := sqlite.Close(); err != nil {
t.Fatalf("Close: %v", err)
}
var output bytes.Buffer
if err := createLoginLink(cfg, "first@example.com", &output); err != nil {
t.Fatalf("createLoginLink for first administrator: %v", err)
}
if !strings.Contains(output.String(), "login_token=") {
t.Fatalf("login link output = %q", output.String())
}
}

func TestPrepareFirstAdministratorRefusesDifferentAddress(t *testing.T) {
sqlite, err := store.NewSQLite(":memory:")
if err != nil {
t.Fatalf("NewSQLite: %v", err)
}
defer sqlite.Close()
users := auth.NewUserStore(sqlite.DB)
if _, err := users.CreateFirstAdminWithAudit("admin@example.com", "", auth.AuditEvent{EventType: "setup.completed", Outcome: "success"}); err != nil {
t.Fatalf("CreateFirstAdmin: %v", err)
}
var logs bytes.Buffer
previous := slog.Default()
slog.SetDefault(slog.New(slog.NewTextHandler(&logs, nil)))
setupRequired, err := prepareFirstAdministrator(" First@Example.com", users)
slog.SetDefault(previous)
if err != nil || setupRequired {
t.Fatalf("prepareFirstAdministrator = (%v, %v), want (false, nil)", setupRequired, err)
}
if _, err := users.GetByEmail("first@example.com"); !errors.Is(err, auth.ErrUserNotFound) {
t.Fatalf("different address lookup err = %v, want ErrUserNotFound", err)
}
if out := logs.String(); !strings.Contains(out, "level=WARN") || !strings.Contains(out, "FANOUT_FIRST_ADMIN_EMAIL ignored") || !strings.Contains(out, "email=first@example.com") {
t.Fatalf("refusal log = %q, want a warning naming first@example.com", out)
}
}

func TestHealthcheckURL(t *testing.T) {
for _, tc := range []struct{ addr, cert, want string }{
{"", "", "http://127.0.0.1:7520/healthz"},
Expand Down
33 changes: 1 addition & 32 deletions docs/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,33 +40,6 @@ Setup credential behavior:
> screen — can hold it until the credential is consumed or expires. Treat a
> leaked banner as a compromised installation and rebuild the database.

### First administrator email instead of a setup URL

Set `FANOUT_FIRST_ADMIN_EMAIL` to create the first administrator without a setup URL.
When the user count is zero at startup, Fanout creates that address as an
active `admin`, records a `setup.completed` audit event with
`source: first_admin_email`, and prints no banner. The address is validated
when configuration loads. The setting takes effect only on first start with an
empty database. The account is a regular, permanent administrator; changing or
removing the setting later has no effect.

- It creates an account only in an empty control database, under the same
transactional check as interactive setup.
- With users present it creates nothing. A matching account is left as it is;
if that account is not an active administrator, Fanout logs a warning. A
different address is refused with a warning, and no account is created.
- No ingest token is issued at startup. The administrator issues the first one from
**Connect telemetry → Ingest token** or `POST /api/settings/ingest/token/rotate`.
Ingest stays closed until then.

> [!WARNING]
> Until the first administrator signs in, whoever first proves control of that address
> claims the administrator account: anyone who can read its mailbox in local
> mode, or any identity provider account that asserts that email in OIDC mode.
> Use an address you control, sign in promptly after first boot, and in OIDC
> mode confirm that the account's `identity.linked` audit event (in the control
> database's `auth_audit_events` table) came from your own sign-in.

### Before you complete setup

Local mode requires only a 32-character `FANOUT_AUTH_CODE_SECRET`. SMTP is
Expand All @@ -89,11 +62,7 @@ successfully verified. The role is fixed: self-signup can never create an
operator or administrator.
The setting requires complete SMTP configuration and local auth mode.

Self-signup remains unavailable until the first administrator exists. An
administrator created from `FANOUT_FIRST_ADMIN_EMAIL` counts, so with that
setting self-signup opens at first boot, before that administrator has signed
in. It still creates only viewers and cannot claim the administrator's address,
which already belongs to an account.
Self-signup remains unavailable until the first administrator completes setup.
Suspended accounts are not recreated or reactivated. Public installations
should enforce traffic and AI-budget limits at the deployment edge; Fanout also
retains its per-IP, per-address, expiry, and attempt limits described below.
Expand Down
Loading
Loading