windmill/docs/auth-surface.md

Auth surface: facts that are easy to get wrong

Symbols, not line numbers, are cited: they drift less.

• Credential precedence (windmill-api-auth/src/auth.rs extract_token): Authorization: Bearer → token cookie → ?token= query param. A URL with ?token= is a credential on every route, but an existing cookie silently wins over it.
• AUTH_CACHE caches a token's identity for 120 s. Deleting a token row does not purge it: the DB trigger (migrations/20260316000001_token_hash_pk_swap.up.sql) notifies only for label = 'session' rows, and delete_token never calls invalidate_token_from_cache.
• Sessions are token rows with label='session' plus the HttpOnly token cookie, minted only by create_session_token (windmill-api-users/src/users.rs). GET /api/users/refresh_token mints one for any non-job token but returns plain text, no redirect.
• tokens/impersonate (superadmin) returns a multi-use token and sets no cookie.
• A token's label decides whether its expiry raises alerts. When delete_expired_items removes an expired token row, the monitor emails the owner and raises a critical alert (if enabled); rows registered by register_token_expiry_notification also get an "expiring soon" warning first. Neither happens when is_user_token (windmill-common/src/auth.rs) reserves the label, so a token the system mints for itself, whether from the backend or from the frontend through tokens/create, needs a reserved label. An ephemeral- prefix needs no other change (keep it clear of is_server_minted_label if minted through tokens/create); a new prefix also goes into the SQL and Svelte mirrors that function's doc lists.
• Every superadmin route refuses a job token: require_super_admin (windmill-api-auth/src/lib.rs) errors on authed.job_id.is_some(). A script that needs users/create, tokens/impersonate, set_login_type, … must use a dedicated superadmin user token stored as a secret, never $WM_TOKEN. Token scopes cannot narrow superadmin routes.
• login_type (password table) is a free-form VARCHAR(50). Password login and password reset require login_type = 'password'; set_password also accepts pending_oauth and turns the account into a password one in the same statement (an account created ahead of its owner gets its first credential that way, or through the OAuth claim below).
• Login links (login_link table, POST /users/login_links superadmin-only, GET /auth/login_link/{token} unauthenticated): single-use, ≤15 min, a session cookie and a 302 to a same-origin rd. require_login_type on the mint refuses (409) an account whose login_type has moved on — the way a caller re-entering an account it created stops being able to once the owner has a password or a provider.
• Pre-approved trial offer (cloud_trial_offer, cloud-only routes under /users/cloud_trial_offer): written by a superadmin at provisioning, consumed by {consumed: true} or by the portal's refusal; …/go is the one Windmill→portal hop that mints a portal login, over the same CUSTOMER_SERVICE_TOKEN trust the onboarding hook uses (users_ee.rs, the portal's admin token). It never expires on its own.
• OAuth login (oauth2_ee.rs login_externally, decision in existing_login_decision) matches an existing account by lowercased email only. Same provider → login; a pending_oauth account (see PENDING_OAUTH_LOGIN_TYPE) is claimed by the first login whose address the provider itself asserted and did not mark unverified — login_type becomes the client key and the hash is nulled; otherwise require_preexisting_user_for_oauth decides: on, every existing account is loggable-into by any provider; off, "exists but with a different login type". A new account gets login_type = <client key>.
• OAuth email trust: LoginUserInfo.email_verified is read leniently (bool or "true"/"false" strings) and is only consulted for the claim above; only GitHub is filtered to primary && verified; a missing email is fabricated from name as <name>@windmill.dev and reaches login_externally with email_asserted = false.
• GET /api/oauth/login/{client} is an unauthenticated 302 to the provider — a plain link from any page starts SSO.
• CLOUD_HOSTED is presence-tested (windmill-common/src/worker.rs): CLOUD_HOSTED=false still enables cloud mode. Of the routes above only the cloud trial offer and onboarding profile routes are cloud-gated; for the rest, cloud only adds quotas.
• CREATE_WORKSPACE_REQUIRE_SUPERADMIN defaults to true when unset; only the literal "true" enables it when set.