From 6a099a1e76c0a00b5cce1896e8c598d6f0de5dde Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sat, 7 Nov 2026 10:51:40 -0800 Subject: [PATCH 1/3] feat(auth): designate the first administrator with FANOUT_OWNER_EMAIL The one-time setup URL puts an administrator credential in process logs, which is awkward for automated and container deployments. With FANOUT_OWNER_EMAIL set, startup creates that address as an active administrator when the control database has no users and prints no setup banner. The owner signs in with an email code, `fanout login-link`, or OIDC. The setting designates only the first administrator. It reuses the transactional empty-database check of interactive setup, so once any user exists it creates nothing: a matching account is left unchanged (with a warning if it is not an active administrator) and a different address is refused with a warning. The address is validated when configuration loads. No setup request runs, so the owner issues the first ingest token from Connect telemetry or POST /api/settings/ingest/token/rotate, which already accept an empty ingest setting; a test now covers that path. Closes #427 --- .env.example | 5 + README.md | 4 +- cmd/fanout/main.go | 32 +++++- cmd/fanout/main_test.go | 79 +++++++++++++++ docs/authentication.md | 17 ++++ internal/api/settings_test.go | 51 ++++++++++ internal/auth/owner.go | 52 ++++++++++ internal/auth/owner_test.go | 97 +++++++++++++++++++ internal/config/config.go | 8 ++ internal/config/config_test.go | 17 ++++ internal/ingest/auth.go | 7 +- internal/settings/ingest.go | 5 +- .../docs/docs/get-started/first-boot.mdx | 37 ++++++- .../docs/docs/guides/troubleshooting.mdx | 8 +- .../docs/reference/configuration/auth.mdx | 5 + 15 files changed, 412 insertions(+), 12 deletions(-) create mode 100644 internal/auth/owner.go create mode 100644 internal/auth/owner_test.go diff --git a/.env.example b/.env.example index 770958379..e7bd97518 100644 --- a/.env.example +++ b/.env.example @@ -172,6 +172,11 @@ # Default: (empty) # FANOUT_OIDC_OPERATOR_GROUPS= +# FANOUT_OWNER_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_OWNER_EMAIL= + # FANOUT_PPROF_ENABLED; boolean # Exposes Go's net/http/pprof handlers at /debug/pprof/* for CPU/heap/mutex/goroutine profiling under load. Off by default; the routes require an admin browser session with operations:read. # Default: false diff --git a/README.md b/README.md index 17d33d14e..c69a900e5 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,9 @@ 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. For later sign-in +displays the ingest token exactly once; save it with your collector secrets. To skip the setup URL, +set `FANOUT_OWNER_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 without SMTP, mint a 15-minute, single-use link against the running container's control database: ```sh diff --git a/cmd/fanout/main.go b/cmd/fanout/main.go index a3dbf7068..6e77bde77 100644 --- a/cmd/fanout/main.go +++ b/cmd/fanout/main.go @@ -195,12 +195,12 @@ func main() { auditStore := auth.NewAuditStore(sqlite.DB) setup := auth.NewSetup() - userCount, err := userStore.CountUsers() + setupRequired, err := prepareFirstAdministrator(cfg.OwnerEmail, userStore) if err != nil { slog.Error("auth status init failed", "err", err) os.Exit(1) } - if userCount == 0 { + if setupRequired { token, _, err := setup.Rotate() if err != nil { slog.Error("setup token init failed", "err", err) @@ -694,6 +694,34 @@ func browserLoginURL(cfg config.Config) *url.URL { return loginURL } +// prepareFirstAdministrator applies FANOUT_OWNER_EMAIL and reports whether the +// control database still has no users, in which case the caller opens the +// one-time setup URL. The owner is created only in an empty database; once +// any user exists the setting never creates, promotes or reactivates anyone. +func prepareFirstAdministrator(ownerEmail string, users *auth.UserStore) (bool, error) { + if ownerEmail != "" { + owner, outcome, err := users.DesignateOwner(ownerEmail) + if err != nil { + return false, fmt.Errorf("designate owner from FANOUT_OWNER_EMAIL: %w", err) + } + switch outcome { + case auth.OwnerCreated: + slog.Info("auth: owner created as the first administrator from FANOUT_OWNER_EMAIL; no setup URL is issued", "email", owner.Email) + case auth.OwnerPresent: + if owner.Role != auth.RoleAdmin || owner.Status != auth.UserStatusActive { + slog.Warn("auth: FANOUT_OWNER_EMAIL names an existing account that is not an active administrator; it was left unchanged", "email", owner.Email, "role", owner.Role, "status", owner.Status) + } + case auth.OwnerRefused: + slog.Warn("auth: FANOUT_OWNER_EMAIL ignored; the control database already has users and none has this email, so no owner was created. Unset it, or have an administrator add the account", "email", strings.ToLower(strings.TrimSpace(ownerEmail))) + } + } + count, err := users.CountUsers() + if err != nil { + return false, err + } + return count == 0, nil +} + func printSetupBanner(httpAddr, token string) { lines := []string{ "============================================================", diff --git a/cmd/fanout/main_test.go b/cmd/fanout/main_test.go index ce518c6f3..22a0a2278 100644 --- a/cmd/fanout/main_test.go +++ b/cmd/fanout/main_test.go @@ -217,6 +217,85 @@ func TestCreateLoginLink(t *testing.T) { } } +func TestPrepareFirstAdministratorWithoutOwnerEmailKeepsSetup(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 TestPrepareFirstAdministratorCreatesOwnerWhoCanUseLoginLink(t *testing.T) { + cfg := config.Config{ + AuthMode: "local", + AuthCodeSecret: "0123456789abcdef0123456789abcdef", + DataDir: t.TempDir(), + Addr: ":7520", + OwnerEmail: "Owner@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.OwnerEmail, users) + if err != nil || setupRequired { + t.Fatalf("prepareFirstAdministrator = (%v, %v), want (false, nil)", setupRequired, err) + } + owner, err := users.GetByEmail("owner@example.com") + if err != nil || owner.Role != auth.RoleAdmin || owner.Status != auth.UserStatusActive { + t.Fatalf("owner = %+v err = %v, want active admin", owner, err) + } + // A restart with the same setting is a no-op, and still issues no setup URL. + setupRequired, err = prepareFirstAdministrator(cfg.OwnerEmail, 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, "owner@example.com", &output); err != nil { + t.Fatalf("createLoginLink for owner: %v", err) + } + if !strings.Contains(output.String(), "login_token=") { + t.Fatalf("login link output = %q", output.String()) + } +} + +func TestPrepareFirstAdministratorRefusesSecondOwner(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) + } + setupRequired, err := prepareFirstAdministrator("owner@example.com", users) + if err != nil || setupRequired { + t.Fatalf("prepareFirstAdministrator = (%v, %v), want (false, nil)", setupRequired, err) + } + if _, err := users.GetByEmail("owner@example.com"); !errors.Is(err, auth.ErrUserNotFound) { + t.Fatalf("second owner lookup err = %v, want ErrUserNotFound", err) + } +} + func TestHealthcheckURL(t *testing.T) { for _, tc := range []struct{ addr, cert, want string }{ {"", "", "http://127.0.0.1:7520/healthz"}, diff --git a/docs/authentication.md b/docs/authentication.md index 81e58cce3..d0b0f2a3f 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -40,6 +40,23 @@ 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. +### Owner email instead of a setup URL + +Set `FANOUT_OWNER_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: owner_email`, and prints no banner. The address is validated when +configuration loads. + +- 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 owner issues the first one from + **Connect telemetry → Ingest token** or `POST /api/settings/ingest/token/rotate`. + Ingest stays closed until then. + ### Before you complete setup Local mode requires only a 32-character `FANOUT_AUTH_CODE_SECRET`. SMTP is diff --git a/internal/api/settings_test.go b/internal/api/settings_test.go index 3751d2a20..16daac6e6 100644 --- a/internal/api/settings_test.go +++ b/internal/api/settings_test.go @@ -61,6 +61,57 @@ func TestRotateIngestToken_PersistsHashReturnsPlaintext(t *testing.T) { } } +// An owner created from FANOUT_OWNER_EMAIL never runs interactive setup, so +// the first ingest token comes from the rotate action on an empty setting. +func TestRotateIngestToken_IssuesFirstTokenForOwner(t *testing.T) { + s, store := newConfigServer(t, config.Config{Addr: ":7520"}) + owner, _, err := s.users.DesignateOwner("owner@example.com") + if err != nil { + t.Fatalf("DesignateOwner: %v", err) + } + cookie := s.login(t, owner) + read := func() ingestResponse { + t.Helper() + rec := httptest.NewRecorder() + s.e.ServeHTTP(rec, sessionRequest(http.MethodGet, "/api/settings/ingest", nil, cookie)) + if rec.Code != http.StatusOK { + t.Fatalf("GET status = %d %s", rec.Code, rec.Body.String()) + } + var resp ingestResponse + if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil { + t.Fatalf("Unmarshal: %v", err) + } + return resp + } + if read().TokenRequired { + t.Fatal("owner database already has an ingest token") + } + rec := httptest.NewRecorder() + req := sessionRequest(http.MethodPost, "/api/settings/ingest/token/rotate", nil, cookie) + s.e.ServeHTTP(rec, req) + if rec.Code != http.StatusOK { + t.Fatalf("rotate status = %d %s", rec.Code, rec.Body.String()) + } + var resp ingestResponse + if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil { + t.Fatalf("Unmarshal: %v", err) + } + current, err := store.GetIngest(req.Context()) + if err != nil || !resp.TokenRequired || !settings.CheckIngestToken(resp.IngestToken, current.TokenHash) { + t.Fatalf("response=%+v current=%+v err=%v", resp, current, err) + } + if !read().TokenRequired { + t.Fatal("token_required is false after the first token was issued") + } + var events int + if err := s.db.DB.QueryRow(`SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'ingest_key.rotated' AND actor_user_id = ?`, owner.ID).Scan(&events); err != nil { + t.Fatalf("query audit: %v", err) + } + if events != 1 { + t.Fatalf("ingest audit events = %d, want 1", events) + } +} + func TestIngestSettingsCapabilities(t *testing.T) { s, _ := newConfigServer(t, config.Config{Addr: ":7520"}) viewer, _ := s.users.CreateWithAudit("viewer@example.com", "", "viewer", auth.AuditEvent{EventType: "user.created", Outcome: "success"}) diff --git a/internal/auth/owner.go b/internal/auth/owner.go new file mode 100644 index 000000000..510065922 --- /dev/null +++ b/internal/auth/owner.go @@ -0,0 +1,52 @@ +package auth + +import ( + "errors" +) + +// OwnerOutcome reports what DesignateOwner did with a configured owner email. +type OwnerOutcome int + +const ( + // OwnerCreated means the control database had no users and the owner was + // created as an active administrator. + OwnerCreated OwnerOutcome = iota + // OwnerPresent means users already existed and one of them has the owner + // email. The account is returned unchanged, whatever its role or status. + OwnerPresent + // OwnerRefused means users already existed and none has the owner email. + // Nothing was created: the setting designates only the first administrator. + OwnerRefused +) + +// DesignateOwner creates the first administrator from a configured owner +// email. It creates an account only when the control database holds no users, +// using the same transactional check as interactive setup, so it can never +// add a second administrator alongside an existing installation's accounts. +// When users already exist it reports whether the owner is among them and +// changes nothing. +func (s *UserStore) DesignateOwner(rawEmail string) (User, OwnerOutcome, error) { + email, err := NormalizeEmail(rawEmail) + if err != nil { + return User{}, OwnerRefused, err + } + user, err := s.CreateFirstAdminWithAudit(email, "", AuditEvent{ + EventType: "setup.completed", + Outcome: "success", + Metadata: map[string]any{"source": "owner_email"}, + }) + if err == nil { + return user, OwnerCreated, nil + } + if !errors.Is(err, ErrSetupComplete) { + return User{}, OwnerRefused, err + } + existing, err := s.GetByEmail(email) + if errors.Is(err, ErrUserNotFound) { + return User{}, OwnerRefused, nil + } + if err != nil { + return User{}, OwnerRefused, err + } + return existing, OwnerPresent, nil +} diff --git a/internal/auth/owner_test.go b/internal/auth/owner_test.go new file mode 100644 index 000000000..6fae8540e --- /dev/null +++ b/internal/auth/owner_test.go @@ -0,0 +1,97 @@ +package auth + +import ( + "context" + "testing" +) + +func TestDesignateOwnerCreatesActiveAdministratorInEmptyDatabase(t *testing.T) { + sqlite := newTestSQLite(t) + users := NewUserStore(sqlite.DB) + + user, outcome, err := users.DesignateOwner(" Owner@Example.com ") + if err != nil { + t.Fatalf("DesignateOwner: %v", err) + } + if outcome != OwnerCreated { + t.Fatalf("outcome = %v, want OwnerCreated", outcome) + } + if user.Email != "owner@example.com" || user.Role != RoleAdmin || user.Status != UserStatusActive { + t.Fatalf("owner = %+v, want active admin owner@example.com", user) + } + var source string + if err := sqlite.DB.QueryRowContext(context.Background(), + `SELECT json_extract(metadata_json, '$.source') FROM auth_audit_events WHERE event_type = 'setup.completed' AND target_id = ?`, user.ID, + ).Scan(&source); err != nil { + t.Fatalf("setup audit event: %v", err) + } + if source != "owner_email" { + t.Fatalf("audit source = %q, want owner_email", source) + } +} + +func TestDesignateOwnerIsIdempotentForTheSameOwner(t *testing.T) { + users := NewUserStore(newTestSQLite(t).DB) + created, _, err := users.DesignateOwner("owner@example.com") + if err != nil { + t.Fatalf("first DesignateOwner: %v", err) + } + again, outcome, err := users.DesignateOwner("OWNER@example.com") + if err != nil { + t.Fatalf("second DesignateOwner: %v", err) + } + if outcome != OwnerPresent || again.ID != created.ID { + t.Fatalf("outcome = %v user = %+v, want OwnerPresent for %s", outcome, again, created.ID) + } + if count, _ := users.CountUsers(); count != 1 { + t.Fatalf("users = %d, want 1", count) + } +} + +func TestDesignateOwnerRefusesASecondOwner(t *testing.T) { + users := NewUserStore(newTestSQLite(t).DB) + if _, err := users.CreateFirstAdminWithAudit("admin@example.com", "", AuditEvent{EventType: "setup.completed", Outcome: "success"}); err != nil { + t.Fatalf("CreateFirstAdmin: %v", err) + } + _, outcome, err := users.DesignateOwner("owner@example.com") + if err != nil { + t.Fatalf("DesignateOwner: %v", err) + } + if outcome != OwnerRefused { + t.Fatalf("outcome = %v, want OwnerRefused", outcome) + } + if _, err := users.GetByEmail("owner@example.com"); err != ErrUserNotFound { + t.Fatalf("GetByEmail(owner) err = %v, want ErrUserNotFound", err) + } + if count, _ := users.CountUsers(); count != 1 { + t.Fatalf("users = %d, want 1", count) + } +} + +func TestDesignateOwnerLeavesAnExistingAccountUnchanged(t *testing.T) { + users := NewUserStore(newTestSQLite(t).DB) + if _, err := users.CreateFirstAdminWithAudit("admin@example.com", "", AuditEvent{EventType: "setup.completed", Outcome: "success"}); err != nil { + t.Fatalf("CreateFirstAdmin: %v", err) + } + viewer, err := users.CreateWithAudit("owner@example.com", "", RoleViewer, AuditEvent{EventType: "user.created", Outcome: "success"}) + if err != nil { + t.Fatalf("Create viewer: %v", err) + } + user, outcome, err := users.DesignateOwner("owner@example.com") + if err != nil { + t.Fatalf("DesignateOwner: %v", err) + } + if outcome != OwnerPresent || user.ID != viewer.ID || user.Role != RoleViewer { + t.Fatalf("outcome = %v user = %+v, want unchanged viewer", outcome, user) + } +} + +func TestDesignateOwnerRejectsInvalidEmail(t *testing.T) { + users := NewUserStore(newTestSQLite(t).DB) + if _, _, err := users.DesignateOwner("not-an-email"); err == nil { + t.Fatal("expected invalid email error") + } + if count, _ := users.CountUsers(); count != 0 { + t.Fatalf("users = %d, want 0", count) + } +} diff --git a/internal/config/config.go b/internal/config/config.go index 8bf176645..42709455d 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -167,6 +167,9 @@ type Config struct { AuthCodeSecret string `group:"auth" env:"FANOUT_AUTH_CODE_SECRET" secret:"true"` // SelfSignup allows verified email addresses to create viewer accounts; requires local auth and SMTP. SelfSignup bool `group:"auth" env:"FANOUT_SELF_SIGNUP" default:"false"` + // OwnerEmail 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. + OwnerEmail string `group:"auth" env:"FANOUT_OWNER_EMAIL"` // SessionIdleTTL expires inactive sessions; use a Go duration of at least 5m. SessionIdleTTL time.Duration `group:"auth" env:"FANOUT_SESSION_IDLE_TTL" default:"12h"` // SessionAbsoluteTTL limits total session lifetime; it must be at least FANOUT_SESSION_IDLE_TTL. @@ -320,6 +323,11 @@ func (c Config) Validate() error { return fmt.Errorf("FANOUT_AUTH_CODE_SECRET must be at least 32 characters") } } + if c.OwnerEmail != "" { + if _, err := appauth.NormalizeEmail(c.OwnerEmail); err != nil { + return fmt.Errorf("FANOUT_OWNER_EMAIL must be a valid email address") + } + } if anySet(c.SMTPHost, c.SMTPUser, c.SMTPPass, c.SMTPFrom) { if !c.SMTPConfigured() { return fmt.Errorf("FANOUT_SMTP_HOST, FANOUT_SMTP_USERNAME, FANOUT_SMTP_PASSWORD, and FANOUT_SMTP_FROM must all be set when SMTP is configured") diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 5523f32bc..625a4f382 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -58,6 +58,20 @@ func TestLoadTreatsEmptyEnvironmentValuesAsAbsent(t *testing.T) { } } +func TestLoadOwnerEmail(t *testing.T) { + cfg, err := Load(LoadOptions{Environ: append(validEnvironment(), "FANOUT_OWNER_EMAIL=Owner@Example.com")}) + if err != nil { + t.Fatal(err) + } + if cfg.OwnerEmail != "Owner@Example.com" { + t.Fatalf("OwnerEmail = %q", cfg.OwnerEmail) + } + _, err = Load(LoadOptions{Environ: append(validEnvironment(), "FANOUT_OWNER_EMAIL=owner.example.com")}) + if err == nil || !strings.Contains(err.Error(), "FANOUT_OWNER_EMAIL must be a valid email address") { + t.Fatalf("invalid owner email error = %v", err) + } +} + func TestConfigurationSchemaUsesUnitBearingDurations(t *testing.T) { specs, err := configFieldSpecs() if err != nil { @@ -273,6 +287,9 @@ func TestValidate(t *testing.T) { {"AI provider invalid", func(c *Config) { c.AIProvider = "unknown" }}, {"auth code secret empty", func(c *Config) { c.AuthCodeSecret = "" }}, {"auth code secret short", func(c *Config) { c.AuthCodeSecret = "short" }}, + {"owner email invalid", func(c *Config) { c.OwnerEmail = "owner" }}, + {"owner email blank", func(c *Config) { c.OwnerEmail = " " }}, + {"owner email with display name", func(c *Config) { c.OwnerEmail = "Owner " }}, {"self-signup without SMTP", func(c *Config) { c.SelfSignup = true; c.SMTPHost = "" }}, {"local self-signup in OIDC mode", func(c *Config) { c.SelfSignup = true diff --git a/internal/ingest/auth.go b/internal/ingest/auth.go index e279840d3..a0b44e1ce 100644 --- a/internal/ingest/auth.go +++ b/internal/ingest/auth.go @@ -82,9 +82,10 @@ func (a *ingestAuthorizer) authorizeToken(ctx context.Context, token string) err return fmt.Errorf("%w: %v", errIngestAuthUnavailable, err) } if ingestCfg.TokenHash == "" { - // Pre-setup (no admin yet) — no token exists to check against. Reject - // all requests until setup completes; collectors must wait. - slog.Warn("ingest: rejecting request — no ingest token configured (setup not complete)") + // No token has been issued yet: interactive setup issues the first one, + // and an owner created from FANOUT_OWNER_EMAIL issues it from Settings. + // Reject all requests until then; collectors must wait. + slog.Warn("ingest: rejecting request — no ingest token configured; an administrator must issue one") return errIngestNotInitialized } if token == "" || !settings.CheckIngestToken(token, ingestCfg.TokenHash) { diff --git a/internal/settings/ingest.go b/internal/settings/ingest.go index ab5a9b53e..e787dd222 100644 --- a/internal/settings/ingest.go +++ b/internal/settings/ingest.go @@ -14,8 +14,9 @@ import ( const ingestKey = "ingest" // Ingest holds the ingest-auth configuration. TokenHash is set during -// first-admin setup and rotatable from the Settings page; when unset -// (pre-setup), the authorizer rejects all OTLP requests. Collectors +// interactive first-admin setup, or issued and rotated from the Settings page +// (the only path for an owner created from FANOUT_OWNER_EMAIL); while unset, +// the authorizer rejects all OTLP requests. Collectors // present the token via `Authorization: Bearer`. type Ingest struct { TokenHash string `json:"token_hash"` diff --git a/site/src/content/docs/docs/get-started/first-boot.mdx b/site/src/content/docs/docs/get-started/first-boot.mdx index 9a0c21b4b..3d1354c8e 100644 --- a/site/src/content/docs/docs/get-started/first-boot.mdx +++ b/site/src/content/docs/docs/get-started/first-boot.mdx @@ -1,7 +1,7 @@ --- title: First boot description: What Fanout checks before it opens a listener, and how to claim the first administrator account. -summary: Configuration validation, the one-time setup URL, and the ingest token you are shown once. +summary: Configuration validation, the one-time setup URL or a configured owner, and the ingest token you are shown once. read_when: - The process refuses to start and you want to know what it validated. - You have a running instance and need to create the first administrator. @@ -57,6 +57,41 @@ The setup URL is an administrator credential. Restrict access to process logs until it is consumed or expires. Treat a leaked setup URL as a compromised installation and rebuild with a fresh data directory before repeating setup. +## Designating the owner instead + +Set `FANOUT_OWNER_EMAIL` to skip the setup URL. When the control database holds +no users at startup, Fanout creates that address as an active administrator and +prints no setup banner, so no administrator credential reaches the logs: + +```sh +docker run --name fanout --restart unless-stopped -p 7520:7520 \ + -v fanout-data:/var/lib/fanout/data \ + -e FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32) \ + -e FANOUT_OWNER_EMAIL=admin@example.com \ + labstack/fanout:latest +``` + +Fanout validates the address when it loads configuration and stops with an +error if it is malformed. The setting only designates the first administrator: + +- Once any user exists, it creates nothing. Restarting with the same address is + a no-op. A different address is refused with a warning naming it, and no + account is created; an administrator adds further accounts from the console. +- It never promotes, reactivates or edits an existing account. If the address + belongs to an account that is not an active administrator, Fanout warns and + leaves the account unchanged. + +The owner signs in like any other user: with an email code when SMTP is +configured, or with `fanout login-link` as shown below. In OIDC mode the owner +signs in through the provider, and Fanout links the first sign-in to the account +by its email address, subject to the usual allowed group and domain checks. + +No setup request runs, so no ingest token is issued at first boot and ingest +rejects every exporter until the owner issues one. After signing in, open +**Connect telemetry → Ingest token** in the account menu and choose +**Issue token**, or call `POST /api/settings/ingest/token/rotate`. Save the token +when it is shown. + ## Signing in afterwards Local mode has no passwords. Once SMTP is configured, active users receive diff --git a/site/src/content/docs/docs/guides/troubleshooting.mdx b/site/src/content/docs/docs/guides/troubleshooting.mdx index b55a9224f..f3b9212e4 100644 --- a/site/src/content/docs/docs/guides/troubleshooting.mdx +++ b/site/src/content/docs/docs/guides/troubleshooting.mdx @@ -102,9 +102,11 @@ permission error. Work down this list in order: -1. **Has setup finished?** Before the first administrator exists there is no - ingest token to check against, and ingest rejects everything. A collector - started ahead of setup fails until you complete it. +1. **Has a token been issued?** Before the first ingest token exists there is + nothing to check against, and ingest rejects everything. Interactive setup + issues the first token; an owner created from `FANOUT_OWNER_EMAIL` issues it + from **Connect telemetry → Ingest token**. A collector started earlier fails + until then. 2. **Is it the right credential, in the right header?** The ingest token is `foi_`-prefixed and goes in `Authorization: Bearer`. Browser sessions and MCP tokens are not ingest credentials. diff --git a/site/src/content/docs/docs/reference/configuration/auth.mdx b/site/src/content/docs/docs/reference/configuration/auth.mdx index a069e50ef..5f51fd24c 100644 --- a/site/src/content/docs/docs/reference/configuration/auth.mdx +++ b/site/src/content/docs/docs/reference/configuration/auth.mdx @@ -31,6 +31,7 @@ Vendor credentials and endpoints keep the vendor's documented names. | `FANOUT_OIDC_EMAIL_VERIFICATION` | string | `required` | | `FANOUT_OIDC_ISSUER_URL` | string | — | | `FANOUT_OIDC_OPERATOR_GROUPS` | string | — | +| `FANOUT_OWNER_EMAIL` | string | — | | `FANOUT_SELF_SIGNUP` | boolean | `false` | | `FANOUT_SESSION_ABSOLUTE_TTL` | duration | `168h` | | `FANOUT_SESSION_IDLE_TTL` | duration | `12h` | @@ -89,6 +90,10 @@ Selects the identity provider issuer; required in OIDC mode. Lists identity-provider groups mapped to operator, separated by commas. +### `FANOUT_OWNER_EMAIL` + +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. + ### `FANOUT_SELF_SIGNUP` Allows verified email addresses to create viewer accounts; requires local auth and SMTP. From 57f5ca0a47bde6b35de038ac0c4ef0c6006bd5bc Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sat, 7 Nov 2026 11:19:30 -0800 Subject: [PATCH 2/3] fix(auth): harden owner designation per review Until the owner first signs in, whoever first proves control of the address claims the administrator account, so the docs now say to use an address you control, sign in promptly, and check the identity.linked audit event in OIDC mode. Self-signup docs now say it opens once the first administrator exists, which the owner setting satisfies at boot. DesignateOwner returns a new OwnerUnknown zero value with every error and reports the normalized address on refusal, so startup logs it without re-normalizing. New tests cover the OIDC callback linking a designated owner by verified email while keeping it an administrator under a demoting group mapping, and the refusal warning text. --- cmd/fanout/main.go | 2 +- cmd/fanout/main_test.go | 10 +- docs/authentication.md | 13 +- internal/api/oidc_test.go | 158 +++++++++++++----- internal/auth/owner.go | 16 +- internal/auth/owner_test.go | 10 +- .../docs/docs/concepts/authentication.mdx | 3 +- .../docs/docs/get-started/first-boot.mdx | 10 +- 8 files changed, 167 insertions(+), 55 deletions(-) diff --git a/cmd/fanout/main.go b/cmd/fanout/main.go index 6e77bde77..0a6f28574 100644 --- a/cmd/fanout/main.go +++ b/cmd/fanout/main.go @@ -712,7 +712,7 @@ func prepareFirstAdministrator(ownerEmail string, users *auth.UserStore) (bool, slog.Warn("auth: FANOUT_OWNER_EMAIL names an existing account that is not an active administrator; it was left unchanged", "email", owner.Email, "role", owner.Role, "status", owner.Status) } case auth.OwnerRefused: - slog.Warn("auth: FANOUT_OWNER_EMAIL ignored; the control database already has users and none has this email, so no owner was created. Unset it, or have an administrator add the account", "email", strings.ToLower(strings.TrimSpace(ownerEmail))) + slog.Warn("auth: FANOUT_OWNER_EMAIL ignored; the control database already has users and none has this email, so no owner was created. Unset it, or have an administrator add the account", "email", owner.Email) } } count, err := users.CountUsers() diff --git a/cmd/fanout/main_test.go b/cmd/fanout/main_test.go index 22a0a2278..75014749e 100644 --- a/cmd/fanout/main_test.go +++ b/cmd/fanout/main_test.go @@ -12,6 +12,7 @@ import ( "errors" "flag" "io" + "log/slog" "math/big" "net" "net/http" @@ -287,13 +288,20 @@ func TestPrepareFirstAdministratorRefusesSecondOwner(t *testing.T) { if _, err := users.CreateFirstAdminWithAudit("admin@example.com", "", auth.AuditEvent{EventType: "setup.completed", Outcome: "success"}); err != nil { t.Fatalf("CreateFirstAdmin: %v", err) } - setupRequired, err := prepareFirstAdministrator("owner@example.com", users) + var logs bytes.Buffer + previous := slog.Default() + slog.SetDefault(slog.New(slog.NewTextHandler(&logs, nil))) + setupRequired, err := prepareFirstAdministrator(" Owner@Example.com", users) + slog.SetDefault(previous) if err != nil || setupRequired { t.Fatalf("prepareFirstAdministrator = (%v, %v), want (false, nil)", setupRequired, err) } if _, err := users.GetByEmail("owner@example.com"); !errors.Is(err, auth.ErrUserNotFound) { t.Fatalf("second owner lookup err = %v, want ErrUserNotFound", err) } + if out := logs.String(); !strings.Contains(out, "level=WARN") || !strings.Contains(out, "FANOUT_OWNER_EMAIL ignored") || !strings.Contains(out, "email=owner@example.com") { + t.Fatalf("refusal log = %q, want a warning naming owner@example.com", out) + } } func TestHealthcheckURL(t *testing.T) { diff --git a/docs/authentication.md b/docs/authentication.md index d0b0f2a3f..ad4f2cbfd 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -57,6 +57,14 @@ configuration loads. **Connect telemetry → Ingest token** or `POST /api/settings/ingest/token/rotate`. Ingest stays closed until then. +> [!WARNING] +> Until the owner first 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 owner'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 @@ -79,7 +87,10 @@ 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 completes setup. +Self-signup remains unavailable until the first administrator exists. An owner +created from `FANOUT_OWNER_EMAIL` counts, so with that setting self-signup opens +at first boot, before the owner has signed in. It still creates only viewers and +cannot claim the owner's address, which already belongs to an account. 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. diff --git a/internal/api/oidc_test.go b/internal/api/oidc_test.go index a0ffecee2..1ab91b2e9 100644 --- a/internal/api/oidc_test.go +++ b/internal/api/oidc_test.go @@ -131,20 +131,32 @@ func TestSafeReturnTo(t *testing.T) { } } -func TestOIDCFlowValidatesPKCENonceAndCreatesSession(t *testing.T) { +// testOIDCProvider is a minimal OpenID provider for driving the real start and +// callback handlers. It issues one RS256 ID token per token exchange for the +// configured email and groups, bound to the nonce from the last start. +type testOIDCProvider struct { + issuer string + email string + groups []string + nonce string + challenge string + pkceVerified bool +} + +func newTestOIDCProvider(t *testing.T, email string) *testOIDCProvider { + t.Helper() key, err := rsa.GenerateKey(rand.Reader, 2048) if err != nil { t.Fatalf("generate signing key: %v", err) } - var issuer, issuedNonce, expectedChallenge string - var pkceVerified bool + p := &testOIDCProvider{email: email} idp := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "application/json") switch r.URL.Path { case "/.well-known/openid-configuration": _ = json.NewEncoder(w).Encode(map[string]any{ - "issuer": issuer, "authorization_endpoint": issuer + "/authorize", "token_endpoint": issuer + "/token", - "jwks_uri": issuer + "/keys", "response_types_supported": []string{"code"}, + "issuer": p.issuer, "authorization_endpoint": p.issuer + "/authorize", "token_endpoint": p.issuer + "/token", + "jwks_uri": p.issuer + "/keys", "response_types_supported": []string{"code"}, "subject_types_supported": []string{"public"}, "id_token_signing_alg_values_supported": []string{"RS256"}, "token_endpoint_auth_methods_supported": []string{"client_secret_basic"}, }) @@ -162,11 +174,14 @@ func TestOIDCFlowValidatesPKCENonceAndCreatesSession(t *testing.T) { } verifier := r.Form.Get("code_verifier") digest := sha256.Sum256([]byte(verifier)) - pkceVerified = verifier != "" && base64.RawURLEncoding.EncodeToString(digest[:]) == expectedChallenge + p.pkceVerified = verifier != "" && base64.RawURLEncoding.EncodeToString(digest[:]) == p.challenge claims := jwt.MapClaims{ - "iss": issuer, "sub": "subject-1", "aud": "fanout-client", + "iss": p.issuer, "sub": "subject-1", "aud": "fanout-client", "exp": time.Now().Add(time.Minute).Unix(), "iat": time.Now().Add(-time.Second).Unix(), - "nonce": issuedNonce, "email": "admin@example.com", "email_verified": true, + "nonce": p.nonce, "email": p.email, "email_verified": true, + } + if p.groups != nil { + claims["groups"] = p.groups } idToken := jwt.NewWithClaims(jwt.SigningMethodRS256, claims) idToken.Header["kid"] = "test-key" @@ -183,33 +198,17 @@ func TestOIDCFlowValidatesPKCENonceAndCreatesSession(t *testing.T) { http.NotFound(w, r) } })) - defer idp.Close() - issuer = idp.URL - - db, err := appstore.NewSQLite(":memory:") - if err != nil { - t.Fatalf("NewSQLite: %v", err) - } - defer db.Close() - users := appauth.NewUserStore(db.DB) - user, err := users.CreateWithAudit("admin@example.com", "", "admin", appauth.AuditEvent{EventType: "user.created", Outcome: "success"}) - if err != nil { - t.Fatalf("create user: %v", err) - } - identities := appauth.NewIdentityStore(db.DB) - sessions := appauth.NewBrowserSessions(db.DB, 12*time.Hour, 7*24*time.Hour, false) - e := echo.New() - e.Use(echo.WrapMiddleware(sessions.Middleware)) - cfg := config.Config{ - AuthMode: "oidc", OIDCIssuerURL: issuer, OIDCClientID: "fanout-client", OIDCClientSecret: "client-secret", - PublicURL: "https://fanout.example.com", OIDCEmailVerification: "required", OIDCDefaultRole: "viewer", - } - if err := RegisterOIDCRoutes(context.Background(), e, cfg, users, identities, sessions, appauth.NewAuditStore(db.DB)); err != nil { - t.Fatalf("RegisterOIDCRoutes: %v", err) - } + t.Cleanup(idp.Close) + p.issuer = idp.URL + return p +} +// login runs /api/auth/oidc/start and then the callback with the issued state +// and pre-auth cookie, returning the callback response. +func (p *testOIDCProvider) login(t *testing.T, e *echo.Echo, returnTo string) *httptest.ResponseRecorder { + t.Helper() startRecorder := httptest.NewRecorder() - e.ServeHTTP(startRecorder, httptest.NewRequest(http.MethodGet, "/api/auth/oidc/start?return_to=/dashboards", nil)) + e.ServeHTTP(startRecorder, httptest.NewRequest(http.MethodGet, "/api/auth/oidc/start?return_to="+url.QueryEscape(returnTo), nil)) if startRecorder.Code != http.StatusFound { t.Fatalf("OIDC start status = %d, want 302: %s", startRecorder.Code, startRecorder.Body.String()) } @@ -218,27 +217,60 @@ func TestOIDCFlowValidatesPKCENonceAndCreatesSession(t *testing.T) { t.Fatalf("parse authorization redirect: %v", err) } state := authorizeURL.Query().Get("state") - issuedNonce = authorizeURL.Query().Get("nonce") - expectedChallenge = authorizeURL.Query().Get("code_challenge") - if state == "" || issuedNonce == "" || expectedChallenge == "" || authorizeURL.Query().Get("code_challenge_method") != "S256" { + p.nonce = authorizeURL.Query().Get("nonce") + p.challenge = authorizeURL.Query().Get("code_challenge") + if state == "" || p.nonce == "" || p.challenge == "" || authorizeURL.Query().Get("code_challenge_method") != "S256" { t.Fatalf("incomplete authorization redirect: %s", authorizeURL.String()) } cookies := startRecorder.Result().Cookies() if len(cookies) != 1 { t.Fatalf("pre-auth cookies = %d, want 1", len(cookies)) } - callback := httptest.NewRequest(http.MethodGet, "/api/auth/oidc/callback?code=authorization-code&state="+url.QueryEscape(state), nil) callback.AddCookie(cookies[0]) callbackRecorder := httptest.NewRecorder() e.ServeHTTP(callbackRecorder, callback) + return callbackRecorder +} + +func newOIDCCallbackServer(t *testing.T, cfg config.Config, db *appstore.SQLite) (*echo.Echo, *appauth.IdentityStore) { + t.Helper() + identities := appauth.NewIdentityStore(db.DB) + sessions := appauth.NewBrowserSessions(db.DB, 12*time.Hour, 7*24*time.Hour, false) + e := echo.New() + e.Use(echo.WrapMiddleware(sessions.Middleware)) + if err := RegisterOIDCRoutes(context.Background(), e, cfg, appauth.NewUserStore(db.DB), identities, sessions, appauth.NewAuditStore(db.DB)); err != nil { + t.Fatalf("RegisterOIDCRoutes: %v", err) + } + return e, identities +} + +func TestOIDCFlowValidatesPKCENonceAndCreatesSession(t *testing.T) { + idp := newTestOIDCProvider(t, "admin@example.com") + db, err := appstore.NewSQLite(":memory:") + if err != nil { + t.Fatalf("NewSQLite: %v", err) + } + defer db.Close() + users := appauth.NewUserStore(db.DB) + user, err := users.CreateWithAudit("admin@example.com", "", "admin", appauth.AuditEvent{EventType: "user.created", Outcome: "success"}) + if err != nil { + t.Fatalf("create user: %v", err) + } + cfg := config.Config{ + AuthMode: "oidc", OIDCIssuerURL: idp.issuer, OIDCClientID: "fanout-client", OIDCClientSecret: "client-secret", + PublicURL: "https://fanout.example.com", OIDCEmailVerification: "required", OIDCDefaultRole: "viewer", + } + e, identities := newOIDCCallbackServer(t, cfg, db) + + callbackRecorder := idp.login(t, e, "/dashboards") if callbackRecorder.Code != http.StatusFound || callbackRecorder.Header().Get("Location") != "/dashboards" { t.Fatalf("OIDC callback = %d location %q: %s", callbackRecorder.Code, callbackRecorder.Header().Get("Location"), callbackRecorder.Body.String()) } - if !pkceVerified { + if !idp.pkceVerified { t.Fatal("token exchange did not present the PKCE verifier from the pre-auth session") } - identity, err := identities.Find(t.Context(), issuer, "subject-1") + identity, err := identities.Find(t.Context(), idp.issuer, "subject-1") if err != nil || identity.UserID != user.ID { t.Fatalf("linked identity = %+v, err %v", identity, err) } @@ -251,6 +283,54 @@ func TestOIDCFlowValidatesPKCENonceAndCreatesSession(t *testing.T) { } } +// An owner designated by FANOUT_OWNER_EMAIL has no linked identity until the +// first OIDC sign-in. That sign-in must link by verified email, audit the +// link, and keep the owner an administrator even when the group mapping would +// demote it, because the owner is the only active administrator. +func TestOIDCCallbackLinksDesignatedOwnerAndKeepsAdministrator(t *testing.T) { + idp := newTestOIDCProvider(t, "Owner@Example.com") + idp.groups = []string{"staff"} + db, err := appstore.NewSQLite(":memory:") + if err != nil { + t.Fatalf("NewSQLite: %v", err) + } + defer db.Close() + users := appauth.NewUserStore(db.DB) + owner, outcome, err := users.DesignateOwner("owner@example.com") + if err != nil || outcome != appauth.OwnerCreated { + t.Fatalf("DesignateOwner = (%v, %v)", outcome, err) + } + cfg := config.Config{ + AuthMode: "oidc", OIDCIssuerURL: idp.issuer, OIDCClientID: "fanout-client", OIDCClientSecret: "client-secret", + PublicURL: "https://fanout.example.com", OIDCEmailVerification: "required", OIDCDefaultRole: "viewer", + OIDCAdminGroups: "fanout-admins", OIDCOperatorGroups: "fanout-operators", + } + e, identities := newOIDCCallbackServer(t, cfg, db) + + callbackRecorder := idp.login(t, e, "/") + if callbackRecorder.Code != http.StatusFound || callbackRecorder.Header().Get("Location") != "/" { + t.Fatalf("OIDC callback = %d location %q: %s", callbackRecorder.Code, callbackRecorder.Header().Get("Location"), callbackRecorder.Body.String()) + } + identity, err := identities.Find(t.Context(), idp.issuer, "subject-1") + if err != nil || identity.UserID != owner.ID { + t.Fatalf("linked identity = %+v, err %v; want owner %s", identity, err, owner.ID) + } + after, err := users.GetByID(owner.ID) + if err != nil || after.Role != appauth.RoleAdmin || after.Status != appauth.UserStatusActive { + t.Fatalf("owner after OIDC login = %+v err %v, want active admin", after, err) + } + var linked, roleChanges int + if err := db.DB.QueryRow(`SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'identity.linked' AND actor_user_id = ?`, owner.ID).Scan(&linked); err != nil { + t.Fatalf("count identity.linked: %v", err) + } + if err := db.DB.QueryRow(`SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'role.changed'`).Scan(&roleChanges); err != nil { + t.Fatalf("count role.changed: %v", err) + } + if linked != 1 || roleChanges != 0 { + t.Fatalf("identity.linked = %d role.changed = %d, want 1 and 0", linked, roleChanges) + } +} + func TestOIDCCallbackRejectsInvalidIdentityTokensAndProvisioning(t *testing.T) { cases := []struct { name string diff --git a/internal/auth/owner.go b/internal/auth/owner.go index 510065922..17a6f6a61 100644 --- a/internal/auth/owner.go +++ b/internal/auth/owner.go @@ -8,9 +8,12 @@ import ( type OwnerOutcome int const ( + // OwnerUnknown is the zero value, returned with every error: nothing is + // known about the owner and no outcome should be acted on. + OwnerUnknown OwnerOutcome = iota // OwnerCreated means the control database had no users and the owner was // created as an active administrator. - OwnerCreated OwnerOutcome = iota + OwnerCreated // OwnerPresent means users already existed and one of them has the owner // email. The account is returned unchanged, whatever its role or status. OwnerPresent @@ -24,11 +27,12 @@ const ( // using the same transactional check as interactive setup, so it can never // add a second administrator alongside an existing installation's accounts. // When users already exist it reports whether the owner is among them and -// changes nothing. +// changes nothing. OwnerRefused returns the normalized email in User.Email so +// callers can report it; no such account exists. func (s *UserStore) DesignateOwner(rawEmail string) (User, OwnerOutcome, error) { email, err := NormalizeEmail(rawEmail) if err != nil { - return User{}, OwnerRefused, err + return User{}, OwnerUnknown, err } user, err := s.CreateFirstAdminWithAudit(email, "", AuditEvent{ EventType: "setup.completed", @@ -39,14 +43,14 @@ func (s *UserStore) DesignateOwner(rawEmail string) (User, OwnerOutcome, error) return user, OwnerCreated, nil } if !errors.Is(err, ErrSetupComplete) { - return User{}, OwnerRefused, err + return User{}, OwnerUnknown, err } existing, err := s.GetByEmail(email) if errors.Is(err, ErrUserNotFound) { - return User{}, OwnerRefused, nil + return User{Email: email}, OwnerRefused, nil } if err != nil { - return User{}, OwnerRefused, err + return User{}, OwnerUnknown, err } return existing, OwnerPresent, nil } diff --git a/internal/auth/owner_test.go b/internal/auth/owner_test.go index 6fae8540e..4cf3194a8 100644 --- a/internal/auth/owner_test.go +++ b/internal/auth/owner_test.go @@ -53,12 +53,12 @@ func TestDesignateOwnerRefusesASecondOwner(t *testing.T) { if _, err := users.CreateFirstAdminWithAudit("admin@example.com", "", AuditEvent{EventType: "setup.completed", Outcome: "success"}); err != nil { t.Fatalf("CreateFirstAdmin: %v", err) } - _, outcome, err := users.DesignateOwner("owner@example.com") + refused, outcome, err := users.DesignateOwner(" Owner@Example.com ") if err != nil { t.Fatalf("DesignateOwner: %v", err) } - if outcome != OwnerRefused { - t.Fatalf("outcome = %v, want OwnerRefused", outcome) + if outcome != OwnerRefused || refused.ID != "" || refused.Email != "owner@example.com" { + t.Fatalf("outcome = %v user = %+v, want OwnerRefused reporting owner@example.com", outcome, refused) } if _, err := users.GetByEmail("owner@example.com"); err != ErrUserNotFound { t.Fatalf("GetByEmail(owner) err = %v, want ErrUserNotFound", err) @@ -88,8 +88,8 @@ func TestDesignateOwnerLeavesAnExistingAccountUnchanged(t *testing.T) { func TestDesignateOwnerRejectsInvalidEmail(t *testing.T) { users := NewUserStore(newTestSQLite(t).DB) - if _, _, err := users.DesignateOwner("not-an-email"); err == nil { - t.Fatal("expected invalid email error") + if _, outcome, err := users.DesignateOwner("not-an-email"); err == nil || outcome != OwnerUnknown { + t.Fatalf("DesignateOwner = (%v, %v), want OwnerUnknown with an error", outcome, err) } if count, _ := users.CountUsers(); count != 0 { t.Fatalf("users = %d, want 0", count) diff --git a/site/src/content/docs/docs/concepts/authentication.mdx b/site/src/content/docs/docs/concepts/authentication.mdx index 0d9517660..02a6fd445 100644 --- a/site/src/content/docs/docs/concepts/authentication.mdx +++ b/site/src/content/docs/docs/concepts/authentication.mdx @@ -24,7 +24,8 @@ 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 +available only once the first administrator exists; an owner created from +`FANOUT_OWNER_EMAIL` counts, even before signing in. 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 diff --git a/site/src/content/docs/docs/get-started/first-boot.mdx b/site/src/content/docs/docs/get-started/first-boot.mdx index 3d1354c8e..f7e50d52f 100644 --- a/site/src/content/docs/docs/get-started/first-boot.mdx +++ b/site/src/content/docs/docs/get-started/first-boot.mdx @@ -76,7 +76,7 @@ error if it is malformed. The setting only designates the first administrator: - Once any user exists, it creates nothing. Restarting with the same address is a no-op. A different address is refused with a warning naming it, and no - account is created; an administrator adds further accounts from the console. + account is created; an administrator adds further accounts with `POST /api/users`. - It never promotes, reactivates or edits an existing account. If the address belongs to an account that is not an active administrator, Fanout warns and leaves the account unchanged. @@ -86,6 +86,14 @@ configured, or with `fanout login-link` as shown below. In OIDC mode the owner signs in through the provider, and Fanout links the first sign-in to the account by its email address, subject to the usual allowed group and domain checks. +:::caution[Claim the owner account promptly] +Until the owner first 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 owner's `identity.linked` audit event came from your own sign-in. +::: + No setup request runs, so no ingest token is issued at first boot and ingest rejects every exporter until the owner issues one. After signing in, open **Connect telemetry → Ingest token** in the account menu and choose From 7a0925ad9a5b3ee3aa5d34e5b6e8a4a043cc0a45 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sat, 7 Nov 2026 12:33:42 -0800 Subject: [PATCH 3/3] refactor(auth): rename owner setting to FANOUT_FIRST_ADMIN_EMAIL "Owner" is not a Fanout role, and the setting does exactly one thing: name the first administrator in an empty control database. The new name says so. The account it creates is a regular, permanent administrator; changing or removing the setting later has no effect, and the docs now state that plainly. Renames the config field (FirstAdminEmail), the store method (DesignateFirstAdmin) and its outcomes (FirstAdmin*), the source file, log text, the setup.completed audit source value (first_admin_email), test names, and the documentation wording. The setting has not been released, so no compatibility alias is kept. --- .env.example | 10 +- README.md | 2 +- cmd/fanout/main.go | 28 +++--- cmd/fanout/main_test.go | 40 ++++---- docs/authentication.md | 25 ++--- internal/api/oidc_test.go | 26 ++--- internal/api/settings_test.go | 14 +-- internal/auth/first_admin.go | 58 +++++++++++ internal/auth/first_admin_test.go | 97 +++++++++++++++++++ internal/auth/owner.go | 56 ----------- internal/auth/owner_test.go | 97 ------------------- internal/config/config.go | 10 +- internal/config/config_test.go | 20 ++-- internal/ingest/auth.go | 2 +- internal/settings/ingest.go | 2 +- .../docs/docs/concepts/authentication.mdx | 4 +- .../docs/docs/get-started/first-boot.mdx | 31 +++--- .../docs/docs/guides/troubleshooting.mdx | 6 +- .../docs/reference/configuration/auth.mdx | 10 +- 19 files changed, 273 insertions(+), 265 deletions(-) create mode 100644 internal/auth/first_admin.go create mode 100644 internal/auth/first_admin_test.go delete mode 100644 internal/auth/owner.go delete mode 100644 internal/auth/owner_test.go diff --git a/.env.example b/.env.example index e7bd97518..98144bf5a 100644 --- a/.env.example +++ b/.env.example @@ -85,6 +85,11 @@ # 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_INGEST_BATCH_SIZE; integer # Sets the group-commit row target; valid values are 1–50000. Individual requests remain atomic and can exceed this target. # Default: 50000 @@ -172,11 +177,6 @@ # Default: (empty) # FANOUT_OIDC_OPERATOR_GROUPS= -# FANOUT_OWNER_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_OWNER_EMAIL= - # FANOUT_PPROF_ENABLED; boolean # Exposes Go's net/http/pprof handlers at /debug/pprof/* for CPU/heap/mutex/goroutine profiling under load. Off by default; the routes require an admin browser session with operations:read. # Default: false diff --git a/README.md b/README.md index c69a900e5..62c2b08dd 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,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_OWNER_EMAIL` and issue the first ingest token after signing in; see +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 without SMTP, mint a 15-minute, single-use link against the running container's control database: diff --git a/cmd/fanout/main.go b/cmd/fanout/main.go index 0a6f28574..d7bab4280 100644 --- a/cmd/fanout/main.go +++ b/cmd/fanout/main.go @@ -195,7 +195,7 @@ func main() { auditStore := auth.NewAuditStore(sqlite.DB) setup := auth.NewSetup() - setupRequired, err := prepareFirstAdministrator(cfg.OwnerEmail, userStore) + setupRequired, err := prepareFirstAdministrator(cfg.FirstAdminEmail, userStore) if err != nil { slog.Error("auth status init failed", "err", err) os.Exit(1) @@ -694,25 +694,25 @@ func browserLoginURL(cfg config.Config) *url.URL { return loginURL } -// prepareFirstAdministrator applies FANOUT_OWNER_EMAIL and reports whether the +// 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 owner is created only in an empty database; once +// 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(ownerEmail string, users *auth.UserStore) (bool, error) { - if ownerEmail != "" { - owner, outcome, err := users.DesignateOwner(ownerEmail) +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 owner from FANOUT_OWNER_EMAIL: %w", err) + return false, fmt.Errorf("designate first administrator from FANOUT_FIRST_ADMIN_EMAIL: %w", err) } switch outcome { - case auth.OwnerCreated: - slog.Info("auth: owner created as the first administrator from FANOUT_OWNER_EMAIL; no setup URL is issued", "email", owner.Email) - case auth.OwnerPresent: - if owner.Role != auth.RoleAdmin || owner.Status != auth.UserStatusActive { - slog.Warn("auth: FANOUT_OWNER_EMAIL names an existing account that is not an active administrator; it was left unchanged", "email", owner.Email, "role", owner.Role, "status", owner.Status) + 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.OwnerRefused: - slog.Warn("auth: FANOUT_OWNER_EMAIL ignored; the control database already has users and none has this email, so no owner was created. Unset it, or have an administrator add the account", "email", owner.Email) + 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() diff --git a/cmd/fanout/main_test.go b/cmd/fanout/main_test.go index 75014749e..1aff13234 100644 --- a/cmd/fanout/main_test.go +++ b/cmd/fanout/main_test.go @@ -218,7 +218,7 @@ func TestCreateLoginLink(t *testing.T) { } } -func TestPrepareFirstAdministratorWithoutOwnerEmailKeepsSetup(t *testing.T) { +func TestPrepareFirstAdministratorWithoutFirstAdminEmailKeepsSetup(t *testing.T) { sqlite, err := store.NewSQLite(":memory:") if err != nil { t.Fatalf("NewSQLite: %v", err) @@ -234,13 +234,13 @@ func TestPrepareFirstAdministratorWithoutOwnerEmailKeepsSetup(t *testing.T) { } } -func TestPrepareFirstAdministratorCreatesOwnerWhoCanUseLoginLink(t *testing.T) { +func TestPrepareFirstAdministratorCreatesAdministratorWhoCanUseLoginLink(t *testing.T) { cfg := config.Config{ - AuthMode: "local", - AuthCodeSecret: "0123456789abcdef0123456789abcdef", - DataDir: t.TempDir(), - Addr: ":7520", - OwnerEmail: "Owner@Example.com", + 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) @@ -250,16 +250,16 @@ func TestPrepareFirstAdministratorCreatesOwnerWhoCanUseLoginLink(t *testing.T) { t.Fatalf("NewSQLite: %v", err) } users := auth.NewUserStore(sqlite.DB) - setupRequired, err := prepareFirstAdministrator(cfg.OwnerEmail, users) + setupRequired, err := prepareFirstAdministrator(cfg.FirstAdminEmail, users) if err != nil || setupRequired { t.Fatalf("prepareFirstAdministrator = (%v, %v), want (false, nil)", setupRequired, err) } - owner, err := users.GetByEmail("owner@example.com") - if err != nil || owner.Role != auth.RoleAdmin || owner.Status != auth.UserStatusActive { - t.Fatalf("owner = %+v err = %v, want active admin", owner, 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.OwnerEmail, users) + setupRequired, err = prepareFirstAdministrator(cfg.FirstAdminEmail, users) if err != nil || setupRequired { t.Fatalf("restart prepareFirstAdministrator = (%v, %v), want (false, nil)", setupRequired, err) } @@ -270,15 +270,15 @@ func TestPrepareFirstAdministratorCreatesOwnerWhoCanUseLoginLink(t *testing.T) { t.Fatalf("Close: %v", err) } var output bytes.Buffer - if err := createLoginLink(cfg, "owner@example.com", &output); err != nil { - t.Fatalf("createLoginLink for owner: %v", err) + 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 TestPrepareFirstAdministratorRefusesSecondOwner(t *testing.T) { +func TestPrepareFirstAdministratorRefusesDifferentAddress(t *testing.T) { sqlite, err := store.NewSQLite(":memory:") if err != nil { t.Fatalf("NewSQLite: %v", err) @@ -291,16 +291,16 @@ func TestPrepareFirstAdministratorRefusesSecondOwner(t *testing.T) { var logs bytes.Buffer previous := slog.Default() slog.SetDefault(slog.New(slog.NewTextHandler(&logs, nil))) - setupRequired, err := prepareFirstAdministrator(" Owner@Example.com", users) + 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("owner@example.com"); !errors.Is(err, auth.ErrUserNotFound) { - t.Fatalf("second owner lookup err = %v, want ErrUserNotFound", 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_OWNER_EMAIL ignored") || !strings.Contains(out, "email=owner@example.com") { - t.Fatalf("refusal log = %q, want a warning naming owner@example.com", out) + 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) } } diff --git a/docs/authentication.md b/docs/authentication.md index ad4f2cbfd..c145f8b8b 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -40,29 +40,31 @@ 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. -### Owner email instead of a setup URL +### First administrator email instead of a setup URL -Set `FANOUT_OWNER_EMAIL` to create the first administrator without 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: owner_email`, and prints no banner. The address is validated when -configuration loads. +`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 owner issues the first one from +- 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 owner first signs in, whoever first proves control of that address +> 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 owner's `identity.linked` audit event (in the control +> 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 @@ -87,10 +89,11 @@ 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 owner -created from `FANOUT_OWNER_EMAIL` counts, so with that setting self-signup opens -at first boot, before the owner has signed in. It still creates only viewers and -cannot claim the owner's address, which already belongs to an account. +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. 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. diff --git a/internal/api/oidc_test.go b/internal/api/oidc_test.go index 1ab91b2e9..13d429c1a 100644 --- a/internal/api/oidc_test.go +++ b/internal/api/oidc_test.go @@ -283,12 +283,12 @@ func TestOIDCFlowValidatesPKCENonceAndCreatesSession(t *testing.T) { } } -// An owner designated by FANOUT_OWNER_EMAIL has no linked identity until the +// An administrator designated by FANOUT_FIRST_ADMIN_EMAIL has no linked identity until the // first OIDC sign-in. That sign-in must link by verified email, audit the -// link, and keep the owner an administrator even when the group mapping would -// demote it, because the owner is the only active administrator. -func TestOIDCCallbackLinksDesignatedOwnerAndKeepsAdministrator(t *testing.T) { - idp := newTestOIDCProvider(t, "Owner@Example.com") +// link, and keep the account an administrator even when the group mapping would +// demote it, because it is the only active administrator. +func TestOIDCCallbackLinksDesignatedFirstAdministrator(t *testing.T) { + idp := newTestOIDCProvider(t, "First@Example.com") idp.groups = []string{"staff"} db, err := appstore.NewSQLite(":memory:") if err != nil { @@ -296,9 +296,9 @@ func TestOIDCCallbackLinksDesignatedOwnerAndKeepsAdministrator(t *testing.T) { } defer db.Close() users := appauth.NewUserStore(db.DB) - owner, outcome, err := users.DesignateOwner("owner@example.com") - if err != nil || outcome != appauth.OwnerCreated { - t.Fatalf("DesignateOwner = (%v, %v)", outcome, err) + firstAdmin, outcome, err := users.DesignateFirstAdmin("first@example.com") + if err != nil || outcome != appauth.FirstAdminCreated { + t.Fatalf("DesignateFirstAdmin = (%v, %v)", outcome, err) } cfg := config.Config{ AuthMode: "oidc", OIDCIssuerURL: idp.issuer, OIDCClientID: "fanout-client", OIDCClientSecret: "client-secret", @@ -312,15 +312,15 @@ func TestOIDCCallbackLinksDesignatedOwnerAndKeepsAdministrator(t *testing.T) { t.Fatalf("OIDC callback = %d location %q: %s", callbackRecorder.Code, callbackRecorder.Header().Get("Location"), callbackRecorder.Body.String()) } identity, err := identities.Find(t.Context(), idp.issuer, "subject-1") - if err != nil || identity.UserID != owner.ID { - t.Fatalf("linked identity = %+v, err %v; want owner %s", identity, err, owner.ID) + if err != nil || identity.UserID != firstAdmin.ID { + t.Fatalf("linked identity = %+v, err %v; want first administrator %s", identity, err, firstAdmin.ID) } - after, err := users.GetByID(owner.ID) + after, err := users.GetByID(firstAdmin.ID) if err != nil || after.Role != appauth.RoleAdmin || after.Status != appauth.UserStatusActive { - t.Fatalf("owner after OIDC login = %+v err %v, want active admin", after, err) + t.Fatalf("first administrator after OIDC login = %+v err %v, want active admin", after, err) } var linked, roleChanges int - if err := db.DB.QueryRow(`SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'identity.linked' AND actor_user_id = ?`, owner.ID).Scan(&linked); err != nil { + if err := db.DB.QueryRow(`SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'identity.linked' AND actor_user_id = ?`, firstAdmin.ID).Scan(&linked); err != nil { t.Fatalf("count identity.linked: %v", err) } if err := db.DB.QueryRow(`SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'role.changed'`).Scan(&roleChanges); err != nil { diff --git a/internal/api/settings_test.go b/internal/api/settings_test.go index 16daac6e6..36b6f27ba 100644 --- a/internal/api/settings_test.go +++ b/internal/api/settings_test.go @@ -61,15 +61,15 @@ func TestRotateIngestToken_PersistsHashReturnsPlaintext(t *testing.T) { } } -// An owner created from FANOUT_OWNER_EMAIL never runs interactive setup, so +// An administrator created from FANOUT_FIRST_ADMIN_EMAIL never runs interactive setup, so // the first ingest token comes from the rotate action on an empty setting. -func TestRotateIngestToken_IssuesFirstTokenForOwner(t *testing.T) { +func TestRotateIngestToken_IssuesFirstTokenForDesignatedAdministrator(t *testing.T) { s, store := newConfigServer(t, config.Config{Addr: ":7520"}) - owner, _, err := s.users.DesignateOwner("owner@example.com") + firstAdmin, _, err := s.users.DesignateFirstAdmin("first@example.com") if err != nil { - t.Fatalf("DesignateOwner: %v", err) + t.Fatalf("DesignateFirstAdmin: %v", err) } - cookie := s.login(t, owner) + cookie := s.login(t, firstAdmin) read := func() ingestResponse { t.Helper() rec := httptest.NewRecorder() @@ -84,7 +84,7 @@ func TestRotateIngestToken_IssuesFirstTokenForOwner(t *testing.T) { return resp } if read().TokenRequired { - t.Fatal("owner database already has an ingest token") + t.Fatal("designated administrator database already has an ingest token") } rec := httptest.NewRecorder() req := sessionRequest(http.MethodPost, "/api/settings/ingest/token/rotate", nil, cookie) @@ -104,7 +104,7 @@ func TestRotateIngestToken_IssuesFirstTokenForOwner(t *testing.T) { t.Fatal("token_required is false after the first token was issued") } var events int - if err := s.db.DB.QueryRow(`SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'ingest_key.rotated' AND actor_user_id = ?`, owner.ID).Scan(&events); err != nil { + if err := s.db.DB.QueryRow(`SELECT COUNT(*) FROM auth_audit_events WHERE event_type = 'ingest_key.rotated' AND actor_user_id = ?`, firstAdmin.ID).Scan(&events); err != nil { t.Fatalf("query audit: %v", err) } if events != 1 { diff --git a/internal/auth/first_admin.go b/internal/auth/first_admin.go new file mode 100644 index 000000000..bbc318505 --- /dev/null +++ b/internal/auth/first_admin.go @@ -0,0 +1,58 @@ +package auth + +import ( + "errors" +) + +// FirstAdminOutcome reports what DesignateFirstAdmin did with a configured +// first administrator email. +type FirstAdminOutcome int + +const ( + // FirstAdminUnknown is the zero value, returned with every error: nothing + // is known about the account and no outcome should be acted on. + FirstAdminUnknown FirstAdminOutcome = iota + // FirstAdminCreated means the control database had no users and the + // address was created as an active administrator. + FirstAdminCreated + // FirstAdminPresent means users already existed and one of them has the + // configured email. The account is returned unchanged, whatever its role or status. + FirstAdminPresent + // FirstAdminRefused means users already existed and none has the + // configured email. + // Nothing was created: the setting designates only the first administrator. + FirstAdminRefused +) + +// DesignateFirstAdmin creates the first administrator from a configured +// email. It creates an account only when the control database holds no users, +// using the same transactional check as interactive setup, so it can never +// add a second administrator alongside an existing installation's accounts. +// When users already exist it reports whether the address is among them and +// changes nothing. FirstAdminRefused returns the normalized email in +// User.Email so callers can report it; no such account exists. +func (s *UserStore) DesignateFirstAdmin(rawEmail string) (User, FirstAdminOutcome, error) { + email, err := NormalizeEmail(rawEmail) + if err != nil { + return User{}, FirstAdminUnknown, err + } + user, err := s.CreateFirstAdminWithAudit(email, "", AuditEvent{ + EventType: "setup.completed", + Outcome: "success", + Metadata: map[string]any{"source": "first_admin_email"}, + }) + if err == nil { + return user, FirstAdminCreated, nil + } + if !errors.Is(err, ErrSetupComplete) { + return User{}, FirstAdminUnknown, err + } + existing, err := s.GetByEmail(email) + if errors.Is(err, ErrUserNotFound) { + return User{Email: email}, FirstAdminRefused, nil + } + if err != nil { + return User{}, FirstAdminUnknown, err + } + return existing, FirstAdminPresent, nil +} diff --git a/internal/auth/first_admin_test.go b/internal/auth/first_admin_test.go new file mode 100644 index 000000000..9ab6ec294 --- /dev/null +++ b/internal/auth/first_admin_test.go @@ -0,0 +1,97 @@ +package auth + +import ( + "context" + "testing" +) + +func TestDesignateFirstAdminCreatesActiveAdministratorInEmptyDatabase(t *testing.T) { + sqlite := newTestSQLite(t) + users := NewUserStore(sqlite.DB) + + user, outcome, err := users.DesignateFirstAdmin(" First@Example.com ") + if err != nil { + t.Fatalf("DesignateFirstAdmin: %v", err) + } + if outcome != FirstAdminCreated { + t.Fatalf("outcome = %v, want FirstAdminCreated", outcome) + } + if user.Email != "first@example.com" || user.Role != RoleAdmin || user.Status != UserStatusActive { + t.Fatalf("firstAdmin = %+v, want active admin first@example.com", user) + } + var source string + if err := sqlite.DB.QueryRowContext(context.Background(), + `SELECT json_extract(metadata_json, '$.source') FROM auth_audit_events WHERE event_type = 'setup.completed' AND target_id = ?`, user.ID, + ).Scan(&source); err != nil { + t.Fatalf("setup audit event: %v", err) + } + if source != "first_admin_email" { + t.Fatalf("audit source = %q, want first_admin_email", source) + } +} + +func TestDesignateFirstAdminIsIdempotentForTheSameAddress(t *testing.T) { + users := NewUserStore(newTestSQLite(t).DB) + created, _, err := users.DesignateFirstAdmin("first@example.com") + if err != nil { + t.Fatalf("first DesignateFirstAdmin: %v", err) + } + again, outcome, err := users.DesignateFirstAdmin("FIRST@example.com") + if err != nil { + t.Fatalf("second DesignateFirstAdmin: %v", err) + } + if outcome != FirstAdminPresent || again.ID != created.ID { + t.Fatalf("outcome = %v user = %+v, want FirstAdminPresent for %s", outcome, again, created.ID) + } + if count, _ := users.CountUsers(); count != 1 { + t.Fatalf("users = %d, want 1", count) + } +} + +func TestDesignateFirstAdminRefusesADifferentAddress(t *testing.T) { + users := NewUserStore(newTestSQLite(t).DB) + if _, err := users.CreateFirstAdminWithAudit("admin@example.com", "", AuditEvent{EventType: "setup.completed", Outcome: "success"}); err != nil { + t.Fatalf("CreateFirstAdmin: %v", err) + } + refused, outcome, err := users.DesignateFirstAdmin(" First@Example.com ") + if err != nil { + t.Fatalf("DesignateFirstAdmin: %v", err) + } + if outcome != FirstAdminRefused || refused.ID != "" || refused.Email != "first@example.com" { + t.Fatalf("outcome = %v user = %+v, want FirstAdminRefused reporting first@example.com", outcome, refused) + } + if _, err := users.GetByEmail("first@example.com"); err != ErrUserNotFound { + t.Fatalf("GetByEmail(firstAdmin) err = %v, want ErrUserNotFound", err) + } + if count, _ := users.CountUsers(); count != 1 { + t.Fatalf("users = %d, want 1", count) + } +} + +func TestDesignateFirstAdminLeavesAnExistingAccountUnchanged(t *testing.T) { + users := NewUserStore(newTestSQLite(t).DB) + if _, err := users.CreateFirstAdminWithAudit("admin@example.com", "", AuditEvent{EventType: "setup.completed", Outcome: "success"}); err != nil { + t.Fatalf("CreateFirstAdmin: %v", err) + } + viewer, err := users.CreateWithAudit("first@example.com", "", RoleViewer, AuditEvent{EventType: "user.created", Outcome: "success"}) + if err != nil { + t.Fatalf("Create viewer: %v", err) + } + user, outcome, err := users.DesignateFirstAdmin("first@example.com") + if err != nil { + t.Fatalf("DesignateFirstAdmin: %v", err) + } + if outcome != FirstAdminPresent || user.ID != viewer.ID || user.Role != RoleViewer { + t.Fatalf("outcome = %v user = %+v, want unchanged viewer", outcome, user) + } +} + +func TestDesignateFirstAdminRejectsInvalidEmail(t *testing.T) { + users := NewUserStore(newTestSQLite(t).DB) + if _, outcome, err := users.DesignateFirstAdmin("not-an-email"); err == nil || outcome != FirstAdminUnknown { + t.Fatalf("DesignateFirstAdmin = (%v, %v), want FirstAdminUnknown with an error", outcome, err) + } + if count, _ := users.CountUsers(); count != 0 { + t.Fatalf("users = %d, want 0", count) + } +} diff --git a/internal/auth/owner.go b/internal/auth/owner.go deleted file mode 100644 index 17a6f6a61..000000000 --- a/internal/auth/owner.go +++ /dev/null @@ -1,56 +0,0 @@ -package auth - -import ( - "errors" -) - -// OwnerOutcome reports what DesignateOwner did with a configured owner email. -type OwnerOutcome int - -const ( - // OwnerUnknown is the zero value, returned with every error: nothing is - // known about the owner and no outcome should be acted on. - OwnerUnknown OwnerOutcome = iota - // OwnerCreated means the control database had no users and the owner was - // created as an active administrator. - OwnerCreated - // OwnerPresent means users already existed and one of them has the owner - // email. The account is returned unchanged, whatever its role or status. - OwnerPresent - // OwnerRefused means users already existed and none has the owner email. - // Nothing was created: the setting designates only the first administrator. - OwnerRefused -) - -// DesignateOwner creates the first administrator from a configured owner -// email. It creates an account only when the control database holds no users, -// using the same transactional check as interactive setup, so it can never -// add a second administrator alongside an existing installation's accounts. -// When users already exist it reports whether the owner is among them and -// changes nothing. OwnerRefused returns the normalized email in User.Email so -// callers can report it; no such account exists. -func (s *UserStore) DesignateOwner(rawEmail string) (User, OwnerOutcome, error) { - email, err := NormalizeEmail(rawEmail) - if err != nil { - return User{}, OwnerUnknown, err - } - user, err := s.CreateFirstAdminWithAudit(email, "", AuditEvent{ - EventType: "setup.completed", - Outcome: "success", - Metadata: map[string]any{"source": "owner_email"}, - }) - if err == nil { - return user, OwnerCreated, nil - } - if !errors.Is(err, ErrSetupComplete) { - return User{}, OwnerUnknown, err - } - existing, err := s.GetByEmail(email) - if errors.Is(err, ErrUserNotFound) { - return User{Email: email}, OwnerRefused, nil - } - if err != nil { - return User{}, OwnerUnknown, err - } - return existing, OwnerPresent, nil -} diff --git a/internal/auth/owner_test.go b/internal/auth/owner_test.go deleted file mode 100644 index 4cf3194a8..000000000 --- a/internal/auth/owner_test.go +++ /dev/null @@ -1,97 +0,0 @@ -package auth - -import ( - "context" - "testing" -) - -func TestDesignateOwnerCreatesActiveAdministratorInEmptyDatabase(t *testing.T) { - sqlite := newTestSQLite(t) - users := NewUserStore(sqlite.DB) - - user, outcome, err := users.DesignateOwner(" Owner@Example.com ") - if err != nil { - t.Fatalf("DesignateOwner: %v", err) - } - if outcome != OwnerCreated { - t.Fatalf("outcome = %v, want OwnerCreated", outcome) - } - if user.Email != "owner@example.com" || user.Role != RoleAdmin || user.Status != UserStatusActive { - t.Fatalf("owner = %+v, want active admin owner@example.com", user) - } - var source string - if err := sqlite.DB.QueryRowContext(context.Background(), - `SELECT json_extract(metadata_json, '$.source') FROM auth_audit_events WHERE event_type = 'setup.completed' AND target_id = ?`, user.ID, - ).Scan(&source); err != nil { - t.Fatalf("setup audit event: %v", err) - } - if source != "owner_email" { - t.Fatalf("audit source = %q, want owner_email", source) - } -} - -func TestDesignateOwnerIsIdempotentForTheSameOwner(t *testing.T) { - users := NewUserStore(newTestSQLite(t).DB) - created, _, err := users.DesignateOwner("owner@example.com") - if err != nil { - t.Fatalf("first DesignateOwner: %v", err) - } - again, outcome, err := users.DesignateOwner("OWNER@example.com") - if err != nil { - t.Fatalf("second DesignateOwner: %v", err) - } - if outcome != OwnerPresent || again.ID != created.ID { - t.Fatalf("outcome = %v user = %+v, want OwnerPresent for %s", outcome, again, created.ID) - } - if count, _ := users.CountUsers(); count != 1 { - t.Fatalf("users = %d, want 1", count) - } -} - -func TestDesignateOwnerRefusesASecondOwner(t *testing.T) { - users := NewUserStore(newTestSQLite(t).DB) - if _, err := users.CreateFirstAdminWithAudit("admin@example.com", "", AuditEvent{EventType: "setup.completed", Outcome: "success"}); err != nil { - t.Fatalf("CreateFirstAdmin: %v", err) - } - refused, outcome, err := users.DesignateOwner(" Owner@Example.com ") - if err != nil { - t.Fatalf("DesignateOwner: %v", err) - } - if outcome != OwnerRefused || refused.ID != "" || refused.Email != "owner@example.com" { - t.Fatalf("outcome = %v user = %+v, want OwnerRefused reporting owner@example.com", outcome, refused) - } - if _, err := users.GetByEmail("owner@example.com"); err != ErrUserNotFound { - t.Fatalf("GetByEmail(owner) err = %v, want ErrUserNotFound", err) - } - if count, _ := users.CountUsers(); count != 1 { - t.Fatalf("users = %d, want 1", count) - } -} - -func TestDesignateOwnerLeavesAnExistingAccountUnchanged(t *testing.T) { - users := NewUserStore(newTestSQLite(t).DB) - if _, err := users.CreateFirstAdminWithAudit("admin@example.com", "", AuditEvent{EventType: "setup.completed", Outcome: "success"}); err != nil { - t.Fatalf("CreateFirstAdmin: %v", err) - } - viewer, err := users.CreateWithAudit("owner@example.com", "", RoleViewer, AuditEvent{EventType: "user.created", Outcome: "success"}) - if err != nil { - t.Fatalf("Create viewer: %v", err) - } - user, outcome, err := users.DesignateOwner("owner@example.com") - if err != nil { - t.Fatalf("DesignateOwner: %v", err) - } - if outcome != OwnerPresent || user.ID != viewer.ID || user.Role != RoleViewer { - t.Fatalf("outcome = %v user = %+v, want unchanged viewer", outcome, user) - } -} - -func TestDesignateOwnerRejectsInvalidEmail(t *testing.T) { - users := NewUserStore(newTestSQLite(t).DB) - if _, outcome, err := users.DesignateOwner("not-an-email"); err == nil || outcome != OwnerUnknown { - t.Fatalf("DesignateOwner = (%v, %v), want OwnerUnknown with an error", outcome, err) - } - if count, _ := users.CountUsers(); count != 0 { - t.Fatalf("users = %d, want 0", count) - } -} diff --git a/internal/config/config.go b/internal/config/config.go index 42709455d..df8eac552 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -167,9 +167,9 @@ type Config struct { AuthCodeSecret string `group:"auth" env:"FANOUT_AUTH_CODE_SECRET" secret:"true"` // SelfSignup allows verified email addresses to create viewer accounts; requires local auth and SMTP. SelfSignup bool `group:"auth" env:"FANOUT_SELF_SIGNUP" default:"false"` - // OwnerEmail creates this address as the first active administrator when the control + // FirstAdminEmail 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. - OwnerEmail string `group:"auth" env:"FANOUT_OWNER_EMAIL"` + FirstAdminEmail string `group:"auth" env:"FANOUT_FIRST_ADMIN_EMAIL"` // SessionIdleTTL expires inactive sessions; use a Go duration of at least 5m. SessionIdleTTL time.Duration `group:"auth" env:"FANOUT_SESSION_IDLE_TTL" default:"12h"` // SessionAbsoluteTTL limits total session lifetime; it must be at least FANOUT_SESSION_IDLE_TTL. @@ -323,9 +323,9 @@ func (c Config) Validate() error { return fmt.Errorf("FANOUT_AUTH_CODE_SECRET must be at least 32 characters") } } - if c.OwnerEmail != "" { - if _, err := appauth.NormalizeEmail(c.OwnerEmail); err != nil { - return fmt.Errorf("FANOUT_OWNER_EMAIL must be a valid email address") + if c.FirstAdminEmail != "" { + if _, err := appauth.NormalizeEmail(c.FirstAdminEmail); err != nil { + return fmt.Errorf("FANOUT_FIRST_ADMIN_EMAIL must be a valid email address") } } if anySet(c.SMTPHost, c.SMTPUser, c.SMTPPass, c.SMTPFrom) { diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 625a4f382..96981f55e 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -58,17 +58,17 @@ func TestLoadTreatsEmptyEnvironmentValuesAsAbsent(t *testing.T) { } } -func TestLoadOwnerEmail(t *testing.T) { - cfg, err := Load(LoadOptions{Environ: append(validEnvironment(), "FANOUT_OWNER_EMAIL=Owner@Example.com")}) +func TestLoadFirstAdminEmail(t *testing.T) { + cfg, err := Load(LoadOptions{Environ: append(validEnvironment(), "FANOUT_FIRST_ADMIN_EMAIL=First@Example.com")}) if err != nil { t.Fatal(err) } - if cfg.OwnerEmail != "Owner@Example.com" { - t.Fatalf("OwnerEmail = %q", cfg.OwnerEmail) + if cfg.FirstAdminEmail != "First@Example.com" { + t.Fatalf("FirstAdminEmail = %q", cfg.FirstAdminEmail) } - _, err = Load(LoadOptions{Environ: append(validEnvironment(), "FANOUT_OWNER_EMAIL=owner.example.com")}) - if err == nil || !strings.Contains(err.Error(), "FANOUT_OWNER_EMAIL must be a valid email address") { - t.Fatalf("invalid owner email error = %v", err) + _, err = Load(LoadOptions{Environ: append(validEnvironment(), "FANOUT_FIRST_ADMIN_EMAIL=first.example.com")}) + if err == nil || !strings.Contains(err.Error(), "FANOUT_FIRST_ADMIN_EMAIL must be a valid email address") { + t.Fatalf("invalid first administrator email error = %v", err) } } @@ -287,9 +287,9 @@ func TestValidate(t *testing.T) { {"AI provider invalid", func(c *Config) { c.AIProvider = "unknown" }}, {"auth code secret empty", func(c *Config) { c.AuthCodeSecret = "" }}, {"auth code secret short", func(c *Config) { c.AuthCodeSecret = "short" }}, - {"owner email invalid", func(c *Config) { c.OwnerEmail = "owner" }}, - {"owner email blank", func(c *Config) { c.OwnerEmail = " " }}, - {"owner email with display name", func(c *Config) { c.OwnerEmail = "Owner " }}, + {"first admin email invalid", func(c *Config) { c.FirstAdminEmail = "first" }}, + {"first admin email blank", func(c *Config) { c.FirstAdminEmail = " " }}, + {"first admin email with display name", func(c *Config) { c.FirstAdminEmail = "First " }}, {"self-signup without SMTP", func(c *Config) { c.SelfSignup = true; c.SMTPHost = "" }}, {"local self-signup in OIDC mode", func(c *Config) { c.SelfSignup = true diff --git a/internal/ingest/auth.go b/internal/ingest/auth.go index a0b44e1ce..8c0ec18e6 100644 --- a/internal/ingest/auth.go +++ b/internal/ingest/auth.go @@ -83,7 +83,7 @@ func (a *ingestAuthorizer) authorizeToken(ctx context.Context, token string) err } if ingestCfg.TokenHash == "" { // No token has been issued yet: interactive setup issues the first one, - // and an owner created from FANOUT_OWNER_EMAIL issues it from Settings. + // and an administrator created from FANOUT_FIRST_ADMIN_EMAIL issues it from Settings. // Reject all requests until then; collectors must wait. slog.Warn("ingest: rejecting request — no ingest token configured; an administrator must issue one") return errIngestNotInitialized diff --git a/internal/settings/ingest.go b/internal/settings/ingest.go index e787dd222..13a839969 100644 --- a/internal/settings/ingest.go +++ b/internal/settings/ingest.go @@ -15,7 +15,7 @@ const ingestKey = "ingest" // Ingest holds the ingest-auth configuration. TokenHash is set during // interactive first-admin setup, or issued and rotated from the Settings page -// (the only path for an owner created from FANOUT_OWNER_EMAIL); while unset, +// (the only path for an administrator created from FANOUT_FIRST_ADMIN_EMAIL); while unset, // the authorizer rejects all OTLP requests. Collectors // present the token via `Authorization: Bearer`. type Ingest struct { diff --git a/site/src/content/docs/docs/concepts/authentication.mdx b/site/src/content/docs/docs/concepts/authentication.mdx index 02a6fd445..010ea403f 100644 --- a/site/src/content/docs/docs/concepts/authentication.mdx +++ b/site/src/content/docs/docs/concepts/authentication.mdx @@ -24,8 +24,8 @@ 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 once the first administrator exists; an owner created from -`FANOUT_OWNER_EMAIL` counts, even before signing in. Viewers can read +available only once the first administrator exists; an administrator created +from `FANOUT_FIRST_ADMIN_EMAIL` counts, even before signing in. 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 diff --git a/site/src/content/docs/docs/get-started/first-boot.mdx b/site/src/content/docs/docs/get-started/first-boot.mdx index f7e50d52f..b9c1295b4 100644 --- a/site/src/content/docs/docs/get-started/first-boot.mdx +++ b/site/src/content/docs/docs/get-started/first-boot.mdx @@ -1,7 +1,7 @@ --- title: First boot description: What Fanout checks before it opens a listener, and how to claim the first administrator account. -summary: Configuration validation, the one-time setup URL or a configured owner, and the ingest token you are shown once. +summary: Configuration validation, the one-time setup URL or a configured first administrator, and the ingest token you are shown once. read_when: - The process refuses to start and you want to know what it validated. - You have a running instance and need to create the first administrator. @@ -57,22 +57,25 @@ The setup URL is an administrator credential. Restrict access to process logs until it is consumed or expires. Treat a leaked setup URL as a compromised installation and rebuild with a fresh data directory before repeating setup. -## Designating the owner instead +## Naming the first administrator instead -Set `FANOUT_OWNER_EMAIL` to skip the setup URL. When the control database holds -no users at startup, Fanout creates that address as an active administrator and -prints no setup banner, so no administrator credential reaches the logs: +Set `FANOUT_FIRST_ADMIN_EMAIL` to skip the setup URL. When the control database +holds no users at startup, Fanout creates that address as an active +administrator and prints no setup banner, so no administrator credential reaches +the logs: ```sh docker run --name fanout --restart unless-stopped -p 7520:7520 \ -v fanout-data:/var/lib/fanout/data \ -e FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32) \ - -e FANOUT_OWNER_EMAIL=admin@example.com \ + -e FANOUT_FIRST_ADMIN_EMAIL=admin@example.com \ labstack/fanout:latest ``` Fanout validates the address when it loads configuration and stops with an -error if it is malformed. The setting only designates the first administrator: +error if it is malformed. The setting takes effect only on first start with an +empty database. The account it creates is a regular, permanent administrator, +and changing or removing the setting later has no effect on it: - Once any user exists, it creates nothing. Restarting with the same address is a no-op. A different address is refused with a warning naming it, and no @@ -81,21 +84,21 @@ error if it is malformed. The setting only designates the first administrator: belongs to an account that is not an active administrator, Fanout warns and leaves the account unchanged. -The owner signs in like any other user: with an email code when SMTP is -configured, or with `fanout login-link` as shown below. In OIDC mode the owner -signs in through the provider, and Fanout links the first sign-in to the account +The first administrator signs in like any other user: with an email code when +SMTP is configured, or with `fanout login-link` as shown below. In OIDC mode +they sign in through the provider, and Fanout links the first sign-in to the account by its email address, subject to the usual allowed group and domain checks. -:::caution[Claim the owner account promptly] -Until the owner first signs in, whoever first proves control of that address +:::caution[Claim the administrator account promptly] +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 owner's `identity.linked` audit event came from your own sign-in. +that the account's `identity.linked` audit event came from your own sign-in. ::: No setup request runs, so no ingest token is issued at first boot and ingest -rejects every exporter until the owner issues one. After signing in, open +rejects every exporter until the first administrator issues one. After signing in, open **Connect telemetry → Ingest token** in the account menu and choose **Issue token**, or call `POST /api/settings/ingest/token/rotate`. Save the token when it is shown. diff --git a/site/src/content/docs/docs/guides/troubleshooting.mdx b/site/src/content/docs/docs/guides/troubleshooting.mdx index f3b9212e4..e0630951f 100644 --- a/site/src/content/docs/docs/guides/troubleshooting.mdx +++ b/site/src/content/docs/docs/guides/troubleshooting.mdx @@ -104,9 +104,9 @@ Work down this list in order: 1. **Has a token been issued?** Before the first ingest token exists there is nothing to check against, and ingest rejects everything. Interactive setup - issues the first token; an owner created from `FANOUT_OWNER_EMAIL` issues it - from **Connect telemetry → Ingest token**. A collector started earlier fails - until then. + issues the first token; an administrator created from + `FANOUT_FIRST_ADMIN_EMAIL` issues it from **Connect telemetry → Ingest + token**. A collector started earlier fails until then. 2. **Is it the right credential, in the right header?** The ingest token is `foi_`-prefixed and goes in `Authorization: Bearer`. Browser sessions and MCP tokens are not ingest credentials. diff --git a/site/src/content/docs/docs/reference/configuration/auth.mdx b/site/src/content/docs/docs/reference/configuration/auth.mdx index 5f51fd24c..92d90b0f3 100644 --- a/site/src/content/docs/docs/reference/configuration/auth.mdx +++ b/site/src/content/docs/docs/reference/configuration/auth.mdx @@ -20,6 +20,7 @@ Vendor credentials and endpoints keep the vendor's documented names. |---|---|---| | `FANOUT_AUTH_CODE_SECRET` or `FANOUT_AUTH_CODE_SECRET_FILE` | string · secret | — | | `FANOUT_AUTH_MODE` | string | `local` | +| `FANOUT_FIRST_ADMIN_EMAIL` | string | — | | `FANOUT_OIDC_ADMIN_GROUPS` | string | — | | `FANOUT_OIDC_ALLOWED_DOMAINS` | string | — | | `FANOUT_OIDC_ALLOWED_GROUPS` | string | — | @@ -31,7 +32,6 @@ Vendor credentials and endpoints keep the vendor's documented names. | `FANOUT_OIDC_EMAIL_VERIFICATION` | string | `required` | | `FANOUT_OIDC_ISSUER_URL` | string | — | | `FANOUT_OIDC_OPERATOR_GROUPS` | string | — | -| `FANOUT_OWNER_EMAIL` | string | — | | `FANOUT_SELF_SIGNUP` | boolean | `false` | | `FANOUT_SESSION_ABSOLUTE_TTL` | duration | `168h` | | `FANOUT_SESSION_IDLE_TTL` | duration | `12h` | @@ -46,6 +46,10 @@ Signs local sign-in codes; required in local mode with at least 32 characters. Selects local sign-in or oidc; each mode validates its prerequisites. +### `FANOUT_FIRST_ADMIN_EMAIL` + +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. + ### `FANOUT_OIDC_ADMIN_GROUPS` Lists identity-provider groups mapped to admin, separated by commas. @@ -90,10 +94,6 @@ Selects the identity provider issuer; required in OIDC mode. Lists identity-provider groups mapped to operator, separated by commas. -### `FANOUT_OWNER_EMAIL` - -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. - ### `FANOUT_SELF_SIGNUP` Allows verified email addresses to create viewer accounts; requires local auth and SMTP.