Proposal: refactor the user and authentication system

[lunny]

Summary

The user and authentication code has grown into several overlapping representations of the same
concept. Identity data lives in user, login_source, external_login_user and user_open_id
at the same time, user carries both a "which source authenticates me" pointer and a duplicated
copy of that source's type, and the OAuth2 provider tables sit in the same package as the
OAuth2 consumer login source. As a result, simple questions ("is this user local?", "what is this
user's external identity?", "may this user change their password?") are answered differently in
different places.

This proposal covers the current state, the concrete problems with code references, a target design,
and — as a first-class part of the design rather than an afterthought — the legacy-data migration
contract that guarantees no user is ever locked out and no data is ever lost.

Baseline for all code references: c186cc4b8d.

Non-negotiable guarantees

Any step of this refactor that does not satisfy all five is not acceptable.

• G1 — no lockout. Every account that can sign in before an upgrade signs in afterwards, with the
  same credential or the same provider, without any user-visible action.
• G2 — expand / migrate / contract. No column or table is dropped in the release that switches
  the read path. Every risky step spans at least two releases: release N writes both the old and the
  new location, release N+1 reads the new one, release N+2 drops the old one.
• G3 — rollback safety. Because release N keeps writing the old columns, downgrading the binary
  within the same minor line still works. Rollback stops being possible only at the contract release,
  which is called out explicitly in the release notes.
• G4 — idempotent migrations. Every backfill is restartable and safe to re-run
  (INSERT ... WHERE NOT EXISTS semantics), so an interrupted upgrade can simply be retried.
• G5 — nothing is discarded. Rows that cannot be mapped unambiguously are parked in a side
  table and reported to the administrator; they are never deleted and never silently rewritten.

Current state

Persistence

Table	Struct	Purpose
login_source	auth.Source, models/auth/source.go:109	IdP configuration, with a polymorphic cfg TEXT column
user	user.User, models/user/user.go:82	Account, plus login_type/login_source/login_name and the local password columns (models/user/user.go:92)
external_login_user	models/user/external_login_user.go:46	Linked external identity, PK (external_id, login_source_id), plus profile snapshot and OAuth tokens
user_open_id	models/user/openid.go:18	Yet another external identity representation
oauth2_application / oauth2_grant / oauth2_authorization_code	models/auth/oauth2.go	Gitea as an OAuth2 provider — unrelated to login sources, but in the same package
access_token, auth_token, two_factor, webauthn_credential, session	models/auth/*.go	Tokens, remember-me, second factors, sessions

Runtime abstractions

Two unrelated notions of "authentication" live in services/auth:

• PasswordAuthenticator (services/auth/interface.go:34) — credential verification, implemented by
  the db, ldap, smtp and pam source configs.
• Method (services/auth/interface.go:26) — per-request authentication, implemented by
  session, basic, oauth2 (provider tokens), reverseproxy, httpsign, sspi.

Source configs are registered from the service layer into a registry owned by the model layer
(models/auth/source.go:99, RegisterTypeConfig) and deserialised through an XORM BeforeSet hook
(models/auth/source.go:132).

Interactive sign-in

services/auth/signin.go:26 (UserSignIn) resolves the account by name or e-mail, then:

1. if a local user row exists, authenticates only against user.login_source
   (services/auth/signin.go:74);
2. otherwise loops over every active source implementing PasswordAuthenticator and tries the
   submitted credentials against each (services/auth/signin.go:104).

Browser flows (OAuth2, OpenID, 2FA, WebAuthn, account linking) are orchestrated across
routers/web/auth/{auth,oauth,linkaccount,openid,2fa,webauthn}.go by passing state through
individual session keys, cleared in one place at services/auth/session.go:57.

Problems

P1 — user.login_type duplicates login_source.type.
Both must be written together (services/user/update.go:198), and lookups use the redundant triple
(login_type, login_source, login_name) (models/user/user.go:1309). If the two diverge, the
sign-in path's behaviour is undefined, and no DB constraint keeps them consistent.

P2 — login_source = 0 is a ghost source.
auth.GetSourceByID(ctx, 0) fabricates an in-memory Source with IsActive = true
(models/auth/source.go:290), with a FIXME stating that disabling built-in password authentication
is not possible. Both NoType and Plain are registered to the same DB source
(services/auth/source/db/source.go:35), so "local" is expressible in two different ways and
IsLocal() has to be written as LoginType <= auth.Plain (models/user/user.go:238).

P3 — user.login_name is semantically polymorphic.
It is an LDAP uid/DN, an SMTP e-mail address, or an OAuth2 subject
(routers/web/auth/oauth.go:510), yet the admin UI renders one generic input for all of them
(templates/admin/user/edit.tmpl:56). For OAuth2 users the same identity is stored twice: in
user.login_name and in external_login_user.external_id.

P4 — "one primary source" and "many linked identities" coexist as two models.
A user has exactly one login_source, but may also have any number of external_login_user and
user_open_id rows. Feature gating therefore falls back to the coarse LoginType > auth.Plain
check, whose own comment says the external-login table should be consulted instead
(models/user/user.go:1456).

P5 — auth.Type conflates three dimensions.
Protocol (LDAP/SMTP/PAM/OAuth2), binding mode (LDAP vs DLDAP are the same protocol with
different bind strategies) and trigger style (SSPI is request-header authentication and does not
implement PasswordAuthenticator at all, yet it is stored as a login source) share one enum
(models/auth/source.go:29).

P6 — inverted layering around source configuration.
models/auth owns the Config interface and the type registry while every implementation lives in
services/auth/source/*. The consequences are the XORM BeforeSet reflection hook
(models/auth/source.go:132), a MustSourceCfg helper that panics on type mismatch
(models/auth/source.go:183), and models/user importing models/auth solely for one enum
(models/user/user.go:99).

P7 — auto-provisioning logic is duplicated per source.
Each source creates users itself: services/auth/source/ldap/source_authenticate.go:87,
services/auth/source/pam/source_authenticate.go:58,
services/auth/source/smtp/source_authenticate.go:74, plus
services/auth/source/ldap/source_sync.go:120 for the sync path. There is no single place to express
activation, e-mail conflict, visibility or group-mapping policy.

P8 — the all-sources fallback loop is unconditional.
For any unknown username the submitted password is replayed against every active password source in
order (services/auth/signin.go:104). This enables account enumeration against upstream systems, can
trigger upstream lockouts, and adds latency proportional to the number of configured sources. It
cannot be turned off.

P9 — sign-in orchestration is an implicit state machine.
twofaUid, twofaRemember, webauthnAssertion, linkAccount, linkAccountData,
openidPendingURI, openid_verified_uri, openid_signin_remember, openid_determined_email,
openid_determined_username are individual session keys shared between six router files and cleaned
up in one hand-maintained list (services/auth/session.go:57). Forgetting one is a security bug
rather than a compile error. The admin form even encodes the source as the string "<type>-<id>" and
parses it back by hand (routers/web/admin/users.go:141).

P10 — models/auth mixes unrelated domains.
Login sources, personal access tokens, remember-me tokens, TOTP, WebAuthn, sessions and the OAuth2
provider implementation all live in one package, which makes the dependency graph and the naming
(Source ⇄ login_source, models/auth ⇄ services/auth) hard to reason about.

P11 — the local/external dichotomy that the code is built on does not exist.
user.passwd is the local password of a local account, and login_source only says who verifies a
submitted password — it does not make the account "non-local". The code contradicts itself on this:

• The OAuth2 source's Authenticate delegates straight back to the DB authenticator
  (services/auth/source/oauth2/source_authenticate.go:15), so an OAuth2 user's password is verified
  locally. An OAuth2 account is simultaneously a local password account and an externally linked
  account — which is exactly why UpdateAuth permits password changes for IsLocal() || IsOAuth2()
  (services/user/update.go:212).
• Yet IsLocal() is LoginType <= auth.Plain (models/user/user.go:238), so it returns false for
  those same OAuth2 users, and IsFeatureDisabledWithLoginType gates on LoginType > auth.Plain
  (models/user/user.go:1460). With EXTERNAL_USER_DISABLE_FEATURES = manage_credentials an OAuth2
  user is therefore denied management of the very password they sign in with
  (routers/web/user/setting/account.go:54).
• Meanwhile SMTP and PAM auto-registration copies the remote password into the local account
  (services/auth/source/smtp/source_authenticate.go:73,
  services/auth/source/pam/source_authenticate.go:57), hashed by CreateUser
  (models/user/user.go:757). Those users do have a local password hash — one that is never used
  for verification and never refreshed. LDAP, by contrast, stores none
  (services/auth/source/ldap/source_authenticate.go:82-90). This is a separate defect from the
  OAuth2 case and is addressed by Step 1b below.

To be precise about OAuth2, since the two cases are easy to conflate: OAuth2 has no upstream
password, so nothing is copied. A password on an OAuth2 account is a genuinely local one, chosen on
the link-register form (routers/web/auth/linkaccount.go:234) and deliberately left empty when
external-only registration is configured (routers/web/auth/linkaccount.go:213-219, whose comment
already asks for a DB-level marker for "second-factor-only" accounts — which is what user_credential
provides).

So IsLocal() means neither "is a local account" (all of them are), nor "has a local password"
(SMTP/PAM users have one), nor "password is verified locally" (OAuth2 is, and returns false). Every
"is this user local" branch in the codebase is built on this one overloaded predicate.

Scale of the coupling: ~135 non-test references to LoginType / .LoginSource / LoginName across
~40 files, including templates, API structs (modules/structs/user.go:22,
modules/structs/admin_user.go:12) and conversion code (services/convert/user.go:79).

Legacy data shapes the migration must handle

Audited against the current code; every one of these is reachable today and is the reason the
migration plan below looks the way it does.

• D1 — "local" has two encodings. login_type is 0 (NoType) on old rows and 1 (Plain) on
  newer ones, which is exactly why IsLocal() is LoginType <= auth.Plain
  (models/user/user.go:238). Both must map to the same local source.
• D2 — local users can carry a stale login_name. UpdateAuth writes LoginName whenever the
  form provides it (services/user/update.go:207) and the admin form keeps the field around
  (templates/admin/user/new.tmpl:51). A local user with a leftover login_name must not produce
  an external identity row.
• D3 — accounts bound to a source can still have a local password, and for OAuth2 it is the one
  actually used. The OAuth2 source verifies passwords through the DB authenticator
  (services/auth/source/oauth2/source_authenticate.go:15) and password updates are permitted for
  IsLocal() || IsOAuth2() (services/user/update.go:212). Credential backfill therefore cannot be
  restricted to login_source = 0, or OAuth2 users lose the password they sign in with.
• D3b — SMTP and PAM users carry a copy of their remote password, and this is a defect, not just
  legacy shape. Auto-registration stores the submitted upstream password
  (services/auth/source/smtp/source_authenticate.go:73,
  services/auth/source/pam/source_authenticate.go:57), hashed by CreateUser
  (models/user/user.go:757); it is then never used for verification and never refreshed. Three
  consequences: a hash of a third-party credential sits in Gitea's database for the lifetime of the
  account, so a DB leak exposes the user's corporate SMTP/PAM password rather than a Gitea-only one;
  IsPasswordSet() reports true, which drives UI branching (templates/user/settings/account.tmpl:10);
  and if an administrator later moves such an account to the local source, the user's old remote
  password silently becomes a valid Gitea password. LDAP already does the right thing and stores
  nothing. These copies are therefore purged rather than migrated — see Step 1b.
• D4 — there is no unique index on (login_type, login_source, login_name). Duplicates and empty
  login_name values are possible in the wild, and a naive UNIQUE(source_id, subject) index would
  either fail to build or force row deletion. Precedent for handling this:
  modelmigration/fixtures/Test_AddUniqueIndexForProjectIssue.
• D5 — OAuth2 identities are stored twice. user.login_name (subject) and
  external_login_user.external_id (routers/web/auth/oauth.go:510 and :519). Installations
  upgraded from before external linking may have only the former. Backfill must deduplicate on
  (source_id, subject) and prefer the external_login_user row, which additionally carries the
  profile snapshot and tokens.
• D6 — OpenID has no login source at all. user_open_id (models/user/openid.go:18) is keyed
  only by a globally unique URI and has a Show flag controlling profile visibility. Consolidating
  it requires a synthetic OpenID source row and a home for Show, which is user-visible data.
• D7 — dangling login_source references. DeleteSource refuses to remove a source in use
  (services/auth/source.go:16), but hand-edited databases and pre-guard installations can still have
  users pointing at a missing row. Today those users cannot sign in; the migration must park them
  rather than fabricate a source.
• D8 — login_name is collation-sensitive. For SMTP it is an e-mail address, for LDAP a uid or a
  DN. Deduplication must be collation-aware and the value preserved byte-for-byte, because it is the
  upstream bind identifier — silently lowercasing it can break LDAP binds.
• D9 — login_name is not only an auth field. The Actions bot encodes a task ID into it
  (models/user/user_system.go:59-61, parsed back at :69) with LoginSource = -1. These are
  in-memory rows, not DB rows, but the struct field cannot simply disappear; this needs its own small
  preparatory PR moving the task ID to a dedicated field.
• D10 — user.Passwd participates in the activation/reset signature.
  makeTimeLimitCodeHashData includes u.Passwd (models/user/user.go:919). Moving the password to
  user_credential must keep feeding the identical value into that hash, or every outstanding
  activation and password-reset link breaks.
• D11 — login_name is a public API and admin-search surface. models/user/search.go:122 filters
  by it and modules/structs/user.go:22 / modules/structs/admin_user.go:12 expose login_name and
  source_id. These must keep working after identities move.

Target design

Principles

1. Every user row is a local account. A source never classifies the account; it only states who
   verifies a submitted password and which external identity the account is linked to.
2. Three orthogonal concepts, never conflated: a credential (a secret stored locally), a
   password verifier (who checks a submitted password), and an identity (who the user is
   according to some source). An account may hold any combination of the three, except that an
   account whose password_verifier_source_id is not the local source may not acquire a local
   credential at all — the schema refuses it, rather than an operator merely never setting one.
3. A source is described by its capabilities (interfaces it implements), not by an enum value.
4. Provisioning policy is decided in exactly one service, from a source-agnostic identity struct.
5. Multi-step browser sign-in is one explicit state machine, not a bag of session keys.
6. Gitea never stores a credential that belongs to another system. A remote source holds the
   authoritative copy; a local copy is liability without benefit.

Schema

• user — account attributes only; the login_* and password columns eventually go away.
• auth_source (today login_source, table name preserved) — IdP configuration. The built-in local
  source becomes a real row so it can be deactivated like any other source.
• user_identity — replaces user.login_*, external_login_user and user_open_id:
  id, user_id (index), source_id, subject (unique with source_id, enforced only from the
  contract release), login_name, is_primary, created_unix, updated_unix.
• user_identity_profile / user_identity_token — the profile snapshot and the access/refresh token
  material currently crammed into external_login_user, separated because they have different
  lifetimes and different sensitivity.
• user_credential — local secrets: user_id, kind, hash_algo, salt, secret, must_change,
  updated_unix. Enables password-less accounts and password history without further schema churn.
• user.password_verifier_source_id — an explicit statement of who verifies a submitted password,
  replacing the implicit meaning of login_source (P11). Pointing at the local source means "check
  user_credential", which is what OAuth2 accounts do today via the DB fallback; pointing at an LDAP,
  SMTP or PAM source means "ask that source". Identity links and the local credential become
  independent of it, so "local account with an OAuth2 identity" stops being a contradiction.
• user_identity_unmapped — the parking table required by G5.
• models/oauth2provider — the provider tables, explicitly separated from login sources.

Old → new mapping (the "no data loss" contract)

Legacy column / table	New home	Notes
user.login_source	user_identity.source_id with is_primary = true	local users point at the real local auth_source row
user.login_type	derived from auth_source.type	redundant by construction (P1); nothing is lost
user.login_name	user_identity.login_name, and subject for OAuth2/OpenID	preserved byte-for-byte (D8)
user.passwd, salt, passwd_hash_algo, must_change_password	user_credential	copied verbatim for local and OAuth2 accounts (a live, locally chosen password — D3). The SMTP/PAM copies of remote passwords are deliberately purged in Step 1b instead of migrated (D3b)
user.login_source (as "who verifies my password")	user.password_verifier_source_id	OAuth2 rows map to the local source, matching today's DB fallback (P11)
external_login_user.external_id	user_identity.subject	deduplicated against user.login_name (D5)
external_login_user.{email,name,first_name,last_name,nick_name,description,avatar_url,location,raw_data}	user_identity_profile	full snapshot retained
external_login_user.{access_token,access_token_secret,refresh_token,expires_at}	user_identity_token	token refresh keeps working (services/auth/source/oauth2/source_sync.go)
external_login_user.provider	derived from the source; retained during migration for lookups
user_open_id.uri	user_identity.subject under a synthetic OpenID source	D6
user_open_id.show	user_identity.show_on_profile	user-visible, must survive
login_source.*	unchanged table, renamed struct/package	third-party SQL keeps working
oauth2_*	unchanged tables, moved package
access_token, auth_token, two_factor, webauthn_credential, session	unchanged	package move only; sessions are not invalidated

External addressing contract

External account management (provisioning, deprovisioning, re-linking after an instance rebuild) needs
to address an account by something other than an autoincrement row id. The design commits to the
following, so downstream work does not have to keep a parallel mapping table of its own.

• subject is immutable and never reused, per source that can promise it. When an upstream
  identifier and an upstream login name are different values, a rename upstream updates
  user_identity.login_name only; subject is written once at link time and never rewritten. This is
  a real guarantee for OAuth2/OpenID Connect (sub) and for OpenID URIs.
• It is not a global guarantee. For LDAP, SMTP and PAM the migrated subject is the same string
  as login_name (a uid, a DN or an e-mail), which upstream may legitimately change. Stability is
  therefore a source capability, declared by the source alongside its other capabilities
  (Principle 3), not a property of the column. Sources that can offer a stable identifier
  (e.g. LDAP entryUUID / objectGUID) may later opt in without a schema change; that is not part of
  this proposal.
• The stable external handle for a source is its name, not its id. login_source.name is already
  UNIQUE (models/auth/source.go:122) and is already the OIDC provider name. Any external addressing
  is therefore (source name, subject); source_id stays an internal foreign key. A source recreated
  on a rebuilt instance under the same name keeps addressing the same humans, which is the manual
  UPDATE user SET login_source = ... remap operators do today.
• user_identity.user_id may be zero, meaning an identity that is not bound to an account yet.
  Backfill never produces such a row — every migrated identity comes from an existing account — and no
  sign-in path accepts one; it exists so that "create the identity, bind the account later" is
  representable. If a later discussion decides against it, the column simply stays non-zero everywhere
  and nothing else in the design changes.

Interfaces

// A source-agnostic result produced by every authentication path.
type ExternalIdentity struct {
    SourceID    int64
    Subject     string   // stable upstream identifier
    LoginName   string   // upstream login/bind name, for display and re-bind
    Email       string
    DisplayName string
    Groups      []string
    SSHKeys     []string
    Profile     *IdentityProfile
    Tokens      *IdentityTokens
    Raw         map[string]any
}

type CredentialVerifier interface { // db, ldap, dldap, smtp, pam
    VerifyPassword(ctx context.Context, subject, password string) (*ExternalIdentity, error)
}

type RedirectFlowProvider interface { // oauth2 / oidc, openid
    AuthURL(ctx context.Context, state string) (string, error)
    Callback(ctx context.Context, r *http.Request) (*ExternalIdentity, error)
}

type RequestAuthenticator interface { // sspi, reverseproxy, httpsign — no longer auth sources
    VerifyRequest(ctx context.Context, r *http.Request) (*ExternalIdentity, error)
}

type UserSynchronizer interface {
    Sync(ctx context.Context, updateExisting bool) error
}

A single provisioning service consumes *ExternalIdentity and decides create / update / link /
reject, replacing the per-source CreateUser calls (P7).

Flow orchestration

One state object, one session key:

type LoginFlow struct {
    Stage     LoginStage // Identified -> SecondFactor -> LinkPending -> Completed
    UserID    int64
    SourceID  int64
    Remember  bool
    Method    string
    Pending   *ExternalIdentity // identity awaiting link/registration
    ReturnTo  string
    ExpiresAt int64
}

Clearing the flow becomes a single delete, and adding a step (mandatory password change, device
confirmation) becomes a new stage instead of another ad-hoc key.

Migration roadmap

Each step is a self-contained PR, ordered so the tree is releasable after every one of them, per
docs/guidelines-refactoring.md. Every step states its DB change, its compatibility behaviour, its
rollback story and its exit criterion.

Step 0 — free login_name from its non-auth use (D9)

• Move the Actions task ID out of LoginName into a dedicated field on the in-memory user
  (models/user/user_system.go:58-71), keeping GetActionsUserTaskID behaviour identical.
• DB: none. Compatibility: none affected, these rows are never persisted.
• Rollback: trivial, code-only.
• Done when: LoginName has no meaning outside authentication.

Step 1 — guard rails and pre-flight diagnostics

• New doctor check gitea doctor check --run auth-consistency, runnable before any schema work,
  reporting per class: login_type != login_source.type, duplicate (login_source, login_name),
  dangling login_source (D7), OAuth2 users without an external_login_user row (D5), and — most
  importantly — accounts that would end up with neither a credential nor an identity, i.e. the exact
  lockout candidates. --fix handles the mechanically repairable classes.
• Migration that repairs user.login_type != login_source.type and normalises login_type for
  login_source = 0 (D1).
• Test fixtures for one user per row of the lockout matrix below; every later step reuses them.
• DB: data repair only, no schema change. Rollback: safe.
• Done when: the invariant is asserted by tests on every write path and the doctor check is green on
  the fixture set.

Step 1a — make the credential state visible, especially to administrators

Tracked separately in #38906. Visibility before mutation: today
nothing in the UI says whether an account holds a local password. The admin detail page shows only the
auth source (templates/admin/user/view_details.tmpl:17-19) and the user list has no such column or
filter, yet "auth source = Local" and "has a local password" are different things (P11, D3, D3b).

• New predicates HasLocalPassword() and PasswordVerifiedLocally() in models/user, replacing
  inference from IsLocal().
• Admin detail rows for "Local password" and "Password verified by"; for an OAuth2 account the latter
  correctly reads "Local".
• A has_local_password status filter in the admin user list
  (models/user/search.go:53-57, routers/web/admin/users.go:75), following the is_2fa_enabled
  precedent, so affected accounts can be enumerated before Step 1b runs.
• The user's own account page names the source that manages their password instead of the generic
  settings.password_change_disabled (templates/user/settings/account.tmpl:31).
• Once user_credential and password_verifier_source_id exist (Steps 4/12), the same predicates
  gate acquisition: every path that can create or reset a local secret refuses when the verifier is
  not the local source, so "this account has no local secret and may not get one" becomes a property
  the schema enforces instead of a convention an operator audits.
• No schema change, no behaviour change, and it is a prerequisite for Step 1b so the purge is auditable
  rather than a silent flip of IsPasswordSet().

Step 1b — stop storing remote credentials locally, and purge the existing copies

Tracked separately in #38905, because it stands on its own:
it needs no schema redesign and does not depend on any other step here (D3b, principle 6).

• Order matters, because makeTimeLimitCodeHashData includes u.Passwd (D10):
  1. Replace u.Passwd in the activation/reset signature with a credential version marker
     (updated_unix of the credential, or a dedicated counter). This preserves the property the
     current code wants — a reset link stops working once the password changes — without coupling the
     signature to the secret itself. One-time cost: links already in flight at upgrade time become
     invalid, which is acceptable for links whose lifetime is measured in minutes.
  2. Stop setting Passwd in SMTP and PAM auto-registration
     (services/auth/source/smtp/source_authenticate.go:73,
     services/auth/source/pam/source_authenticate.go:57), matching what LDAP already does.
  3. Migration that clears passwd, salt and passwd_hash_algo for accounts whose password is
     verified by a remote source (LDAP/SMTP/PAM), leaving OAuth2 and local accounts untouched.
• No lockout (G1): these accounts are authenticated by their source, never by the local hash
  (services/auth/signin.go:74), and they are already excluded from the reset and change-password
  paths (routers/web/auth/password.go:75, templates/user/settings/account.tmpl:7). Nothing that
  works today stops working.
• One intentional behaviour change, to be called out in the release notes: after this step,
  switching such an account to the local source no longer silently re-enables the user's old remote
  password; an administrator has to set a password explicitly.
• Not a G5 violation: the purged value is a copy of a secret owned by another system, which Gitea
  has no legitimate use for. The rows themselves are untouched.
• Done when: no source writes a remote credential into user, and the doctor check from Step 1
  reports zero remote-verified accounts with a local password hash.

Step 2 — funnel all field access through accessors

• Add user.AuthSourceID(), user.SetAuthSource(*auth.Source), user.SubjectName(),
  user.IsLocalAccount() in models/user; replace the ~135 direct reads/writes so the struct fields
  become effectively package-private.
• DB: none. Behaviour: none. Rollback: code-only.
• Done when: no package outside models/user touches LoginType, LoginSource or LoginName
  directly.

Step 3 — make the local source a real row (P2)

• Migration inserts an auth_source row for built-in password authentication and repoints local
  users at it; the old login_source = 0 value keeps working through the accessors during the
  transition.
• Delete the id == 0 special case (models/auth/source.go:290); NoType is retired from the user
  side. IsActive = false on that row now disables built-in password login, resolving the FIXME.
• DB: one inserted row plus an ID rewrite. Rollback: the reverse update is mechanical and shipped as a
  documented SQL snippet.
• Done when: no code path constructs a Source value that is not backed by a row.

Step 4 — create user_identity and backfill (expand phase)

• Create user_identity, user_identity_profile, user_identity_token, user_identity_unmapped.
• Backfill from three inputs in this order: external_login_user (richest), then non-local
  user.login_* where no identity exists yet (D5), then user_open_id under a synthetic OpenID
  source (D6). Local users get an identity on the local source; a stale login_name on a local user is
  copied to login_name but never promoted to subject (D2).
• Deduplicate on (source_id, subject) without creating the unique index yet (D4); ambiguous rows
  go to user_identity_unmapped with a reason code and are surfaced in the admin UI (G5).
• Migration logs a per-class summary (migrated, deduplicated, parked) and is idempotent (G4).
• Reads still come from the old locations; writes go to both (dual write).
• Rollback: the new tables are additive and simply ignored by an older binary (G3).
• Done when: a consistency test proves old and new reads agree for every fixture, and the doctor check
  reports zero unexplained parked rows on the fixture set.

Step 5 — switch reads to user_identity (migrate phase, release N+1)

• Move identity lookups (routers/web/auth/oauth.go:510 and :519, the OpenID lookup,
  services/externalaccount) to the new table.
• Replace the LoginType > auth.Plain feature gate (models/user/user.go:1456) with a query on the
  user's primary identity, which is what the existing comment asks for.
• Dual write continues, so external_login_user and user_open_id stay correct for a downgrade.
• Done when: every read path is on user_identity and the integration suite signs in successfully as
  each fixture user.

Step 6 — stop writing user.login_type (keep the column)

• Derive the type from the source everywhere; rewrite GetIndividualUserByLoginSource to key on
  (source_id, login_name).
• Keep the API surface: login_name and source_id stay in modules/structs, the admin API keeps
  accepting login_type-shaped input by resolving it to a source ID, and models/user/search.go:122
  keeps filtering by login_name (D11).
• Replace the "<type>-<id>" form encoding (routers/web/admin/users.go:141) with a plain source-ID
  select.
• DB: the column stays, unread. Rollback: still safe.
• Done when: API responses are byte-identical for the Step 1 fixtures.

Step 7 — fix the layering of source configuration (P6)

• Move the Config registry out of models/auth into services/auth/source; replace the BeforeSet
  hook with an explicit LoadSourceCfg(*Source) error called by the finders, and MustSourceCfg
  panics with typed errors.
• Split auth.Type into a protocol enum plus capability interfaces; DLDAP becomes an LDAP config
  flag while keeping its stored numeric value for compatibility (open question 3).
• models/user no longer imports models/auth.
• DB: none. Done when: the model package has no knowledge of concrete source implementations.

Step 8 — unify provisioning (P7)

• Add services/auth/provision.go with ProvisionFromIdentity(ctx, *ExternalIdentity, policy)
  handling create, update, link-to-existing (by verified e-mail or username, gated by configuration),
  activation, group/team mapping and SSH key sync.
• Rewrite ldap, smtp, pam and the OAuth2 callback to return *ExternalIdentity and delegate,
  removing their local CreateUser calls; reuse the same entry point from SyncExternalUsers so the
  login and sync paths cannot drift.
• Behaviour must be pinned by tests first: current auto-registration semantics per source are
  captured as tests in Step 1's fixture set, then re-asserted here.
• Done when: CreateUser has one caller per user-facing flow (self sign-up, admin create,
  provisioning).

Step 9 — make the all-sources fallback explicit (P8)

• Add a setting to disable the fallback loop (services/auth/signin.go:104), defaulting to the
  current behaviour so upgrades do not change who can log in (G1); restrict it to sources that opt
  in, apply a per-source timeout and rate-limit by remote address.
• Done when: both settings are covered by tests and the default is behaviour-preserving.

Step 10 — split models/auth (P10)

• models/authsource (sources), models/token (access_token, auth_token, session),
  models/twofactor (TOTP + WebAuthn), models/oauth2provider (provider tables).
• Table names preserved; this is a package move plus import rewrite.
• Done when: each package has a single domain and no import cycle is introduced.

Step 11 — the sign-in state machine (P9)

• Introduce LoginFlow under one session key, replacing the ten ad-hoc keys and the manual cleanup
  list (services/auth/session.go:57); convert the six router files to stage transitions.
• Existing signed-in sessions are unaffected; only sign-in flows in progress across the restart are,
  which is already true today.
• Done when: ClearSessionKeysForSignIn is a single delete and every transition, including abandoned
  and expired flows, is tested.

Step 12 — contract phase (release N+2)

• Drop user.login_type, user.login_source, user.login_name; retire external_login_user and
  user_open_id; add UNIQUE(source_id, subject) once the reported duplicates are resolved (D4).
• Optionally extract user_credential, copying passwd/salt/passwd_hash_algo/
  must_change_password verbatim and keeping makeTimeLimitCodeHashData fed with the same value
  (D10). This also removes the oddity that password updates are gated on
  IsLocal() || IsOAuth2() (services/user/update.go:212) and makes password-less accounts a
  first-class state.
• Release notes state that downgrades past this point are not supported (G3).
• Done when: the doctor check reports zero parked rows and the unique index exists.

Release phasing

Release	Steps
N	0, 1, 1a, 1b, 2, 3, 4 (create + backfill + dual write), 7
N+1	5 (read switch), 6, 8, 9, 10, 11
N+2	12 (drops, unique index, optional user_credential)

Low-risk first slice

Steps 0–3 (including 1a and 1b) plus the registry part of 7 need no destructive schema change and already remove most of the
ambiguity. They are a reasonable first milestone even if the rest is deferred.

Lockout matrix

The concrete answer to "can a user end up unable to log in". Every row gets a fixture and an
end-to-end sign-in assertion through the real services/auth.UserSignIn, not a mock.

Account class	Legacy representation	After migration	Verification
Local, password set	login_type 0 or 1, login_source 0	primary identity on the local source; password columns untouched until Step 12	sign-in with the original password on migrated data
Local, no password	empty passwd	unchanged; still cannot password-sign-in, and we do not "repair" it	negative test
Local with stale login_name	D2	identity on the local source, login_name retained, subject not promoted	sign-in test
LDAP / DLDAP	login_type 2/5, login_name = uid or DN	identity with subject byte-identical	bind against a test LDAP using the migrated value
SMTP	login_type 3, login_name = e-mail	identity with the e-mail exactly as stored, no case folding	sign-in test
PAM	login_type 4	identity, verification path unchanged	sign-in test
OAuth2 with link row	user.login_* and external_login_user	identity built from the link row (tokens and profile preserved), credential kept, verifier = local source	callback test, token-refresh test, and password sign-in test
OAuth2 without link row	only user.login_*	identity synthesised from user.login_*, same verifier mapping	callback and password sign-in test on a pre-link fixture
SMTP / PAM with a copied remote password (D3b)	login_type 3/4 with non-empty passwd	local hash purged in Step 1b, no credential row, verifier = the source	upstream sign-in still succeeds; IsPasswordSet() becomes false; reset and change-password paths were already refused for these accounts
OpenID	user_open_id rows	identities under the synthetic OpenID source, Show preserved	sign-in test plus profile rendering test
SSPI	login_type 7 source rows	the source row is kept; SSPI stops being a password source and reads config from that row	request-auth test
Dangling source	login_source points nowhere	parked and reported; already unable to sign in today, so no regression	doctor output assertion
Duplicate (source, login_name)	D4	all rows kept, extras parked, unique index deferred	doctor output assertion
Bot / remote / reserved / organization	type != 0	untouched	existing tests
2FA, WebAuthn, PATs, remember-me, sessions	two_factor, webauthn_credential, access_token, auth_token, session	untouched, package move only	existing tests pass unchanged; sessions must not be invalidated

Test strategy

• Fixture-based migration tests per step, using the existing pattern
  (modelmigration/migrationtest.PrepareTestEnv, modelmigration/fixtures/Test_*), with
  Test_UnwrapLDAPSourceCfg as the closest precedent for source-config surgery.
• One shared "legacy install" fixture containing exactly one user per row of the lockout matrix,
  reused by every step so equivalence is proven against the same data set throughout.
• A dual-write consistency test in release N comparing old and new reads for every fixture; it is
  the gate for the Step 5 read switch.
• Upgrade-and-login runs for the two riskiest transitions (Step 4 backfill, Step 5 read switch).

Compatibility and risk

• API: login_name and source_id remain in modules/structs; login_type in the admin API is
  resolved to a source ID rather than removed.
• External consumers: third-party dashboards query the login_source table by name, so the table
  name is kept even after the struct and package are renamed.
• Irreversible migrations: only the Step 12 contract phase is irreversible, and it is a separate
  release with explicit release notes.
• Behaviour: Step 9 is the only step that can change who is able to log in, and it ships
  behaviour-preserving by default.
• Timing: schema-affecting steps should land early in a milestone.

Non-goals

• No change to the OAuth2 provider protocol implementation, only its package location.
• No change to the supported source types or their configuration semantics.
• No change to how sessions or personal access tokens are validated, beyond package moves.
• Federated / UserTypeRemoteUser accounts (models/user/user.go:67) are out of scope, though
  user_identity should be a better fit for them than user.login_*.
• SCIM and external account management ([Thread] SSO Auth Tracking #23794) are out of scope. The addressing contract above is
  written so that they stay implementable on top of this schema, nothing more.
• Whether provisioning may accept an identity that arrives without an e-mail address
  (CreateUserOption.Email is Required, modules/structs/admin_user.go:23; OIDC self-registration
  refuses the same way, routers/web/auth/oauth.go:165) is an API policy question, not a schema one.
  Step 8 collapses that decision into a single service, so it can be revisited afterwards in one
  place instead of five.

Open questions

1. Duplicate (source, login_name) — recommendation is to keep every row, park the extras, defer
   the unique index and require an administrator to resolve. The alternative (pick one
   deterministically) silently changes who owns an upstream identity.
2. UserOpenID.Show — carry it on user_identity, or keep a thin profile-preferences table?
3. DLDAP — keep the stored type value forever, or migrate it into an LDAP config flag with a
   one-way migration?
4. Contract window — one minor release or two before the old columns and tables are dropped?
5. Auto-created SSPI / reverse-proxy accounts — should they get an identity row for their source,
   or remain credential-less local accounts as they are today?
6. SMTP/PAM password capture (D3b) — resolved: no. Gitea should not hold a copy of a credential
   owned by another system, so Step 1b stops the capture and purges the existing copies. What is still
   open is the replacement input for the activation/reset signature (credential updated_unix versus a
   dedicated counter).
7. Deactivating the local source (P2/P11) — once built-in password login can be switched off,
   does that also disable password verification for OAuth2 accounts, which currently delegate to the
   DB authenticator? My preference is yes, with the setting documented as "local password
   verification" rather than "local accounts". The stronger form is now a design point rather than a
   question: an account whose verifier is not the local source cannot acquire a local credential
   either (Principle 2, Step 1a).
8. Unbound identities — should user_identity.user_id = 0 be accepted, as the addressing contract
   proposes, or should an identity always be a property of an existing account? This only affects
   future provisioning work; migration and sign-in behave identically either way.
9. Stable subjects for LDAP/SMTP/PAM — worth declaring a per-source "subject is stable" capability
   now, even though every source migrated from login_name starts out without it?

Feedback is most useful on the target schema, the old → new mapping table, and the ordering of
Steps 4–6, which is where the points of no return live.

---

Assisted-by: Codet:claude-opus-4-6

[lunny]

Addendum: legacy data migration, zero lockout, zero data loss

The original write-up mentions migrations per step but does not state the contract. Since "no user
may lose access and no data may be lost" is a hard requirement, here is the explicit plan, based on
an audit of what legacy data actually looks like in the current schema.

1. Guarantees the refactor must satisfy

• G1 — no lockout. Every account that can sign in before an upgrade signs in afterwards with the
  same credential or the same provider, without any user-visible action.
• G2 — expand / migrate / contract. No column or table is dropped in the same release that
  switches the read path. Every risky step spans at least two releases:
  release N writes both old and new locations, release N+1 reads the new one, release N+2
  drops the old one.
• G3 — rollback safety. Because release N keeps writing the old columns, downgrading the
  binary within the same minor line still works. Rollback stops being possible only at the contract
  release, which is called out in the release notes.
• G4 — idempotent migrations. Every backfill is restartable and safe to re-run (INSERT ... WHERE NOT EXISTS semantics), so an interrupted upgrade can simply be retried.
• G5 — nothing is discarded. Rows that cannot be mapped unambiguously are parked in a side
  table and reported, never deleted and never silently rewritten.

2. Legacy data shapes that actually exist today

These are the cases the backfill has to handle; all of them are reachable with the current code.

• D1 — "local" has two encodings. login_type is 0 (NoType) on old rows and 1 (Plain) on
  newer ones, which is exactly why IsLocal() is written as LoginType <= auth.Plain
  (models/user/user.go:238). Both must map to the same local source.
• D2 — local users can carry a stale login_name. UpdateAuth writes LoginName whenever the
  form provides it (services/user/update.go:207), and the admin form keeps the field around
  (templates/admin/user/new.tmpl:51). A local user with a leftover login_name must not
  produce an external identity row.
• D3 — non-local users can have a local password. Password updates are permitted for
  IsLocal() || IsOAuth2() (services/user/update.go:212). So user_credential backfill cannot be
  restricted to local accounts, otherwise those users lose their password.
• D4 — there is no unique index on (login_type, login_source, login_name). Duplicates and empty
  login_name values are therefore possible in the wild, and a naive UNIQUE(source_id, subject)
  index would fail to build or, worse, force row deletion. Precedent for handling this:
  modelmigration/fixtures/Test_AddUniqueIndexForProjectIssue.
• D5 — OAuth2 identities are stored twice. user.login_name (subject) and
  external_login_user.external_id (routers/web/auth/oauth.go:510 and :519). Installations
  upgraded from before external linking may have only the former. Backfill must deduplicate on
  (source_id, subject) and prefer the external_login_user row, which additionally carries the
  profile snapshot and tokens.
• D6 — OpenID has no login source at all. user_open_id (models/user/openid.go:18) is keyed
  only by a globally unique URI and has a Show flag that controls profile visibility. The original
  Step 5/6 under-specified this: consolidating it requires a synthetic OpenID source row and a home
  for Show. It is user-visible data, so it must survive.
• D7 — dangling login_source references. DeleteSource refuses to remove a source in use
  (services/auth/source.go:16), but hand-edited databases and pre-guard installations can still
  have users pointing at a missing row. Today those users simply cannot sign in; the migration must
  park them rather than fabricate a source.
• D8 — login_name is collation-sensitive. For SMTP it is an e-mail address, for LDAP a uid or a
  DN. Deduplication must be collation-aware, and the value must be preserved byte-for-byte because it
  is used as the upstream bind identifier — silently lowercasing it can break LDAP binds.
• D9 — login_name is not only an auth field. The Actions bot encodes a task ID into it
  (models/user/user_system.go:59-61, parsed back at :69) with LoginSource = -1. These are
  in-memory rows, not DB rows, but the struct field cannot simply disappear. This needs its own
  small preparatory PR that moves the task ID to a dedicated field.
• D10 — user.Passwd participates in the activation/reset signature.
  makeTimeLimitCodeHashData includes u.Passwd (models/user/user.go:919). Moving the password to
  user_credential (Step 12) must keep feeding the identical value into that hash, otherwise every
  outstanding activation and password-reset link breaks.
• D11 — login_name is a public API and admin-search surface.
  models/user/search.go:122 filters by it, and modules/structs/user.go:22 /
  modules/structs/admin_user.go:12 expose login_name and source_id. These must keep working
  after identities move.

3. Revised sequencing

The steps stay the same, but each risky one is split into expand / verify / switch / contract phases
placed in different releases:

Release	Steps
N	1 (repair + invariants), 2 (accessors), 3 (real local source), preparatory Actions-task-ID PR (D9), 5 (create user_identity, backfill, dual write), 7 (registry layering, no data change)
N+1	6 (switch reads to user_identity), 4 (stop writing login_type, keep the column), 8 (unified provisioning), 9 (fallback-loop setting), 10 (package split)
N+2	contract: drop user.login_type / login_source / login_name, retire external_login_user and user_open_id, add UNIQUE(source_id, subject), then optionally 12 (user_credential)

Step 11 (sign-in state machine) touches no persisted data and can land at any point; only active
sign-in flows in progress during the restart are affected, which is already true today.

4. Pre-flight and post-flight verification

• A new doctor check, gitea doctor check --run auth-consistency, added in release N and runnable
  before the schema work lands. It reports, per class: login_type != login_source.type,
  duplicate (login_source, login_name), dangling login_source, OAuth2 users with no
  external_login_user row, and — most importantly — accounts that would end up with neither a
  credential nor an identity, i.e. the exact lockout candidates. --fix handles the mechanically
  repairable classes.
• The backfill migration logs a per-class summary (migrated, deduplicated, parked) so an
  operator can see what happened without querying the DB.
• Unmapped rows go to user_identity_unmapped with the original values and a reason code, surfaced
  in the admin UI so an administrator can resolve them, satisfying G5.
• UNIQUE(source_id, subject) is deliberately deferred to the contract release: uniqueness is only
  enforced once the reported duplicates have been resolved, so upgrading never fails on pre-existing
  data (D4).

5. Lockout matrix

This is the concrete answer to "can a user end up unable to log in". Every row gets a fixture and an
end-to-end sign-in assertion.

Account class	Legacy representation	After migration	Verification
Local, password set	login_type 0 or 1, login_source 0	primary identity on the local source; passwd/salt/passwd_hash_algo untouched until the contract release	sign-in with the original password on a migrated fixture
Local, no password	empty passwd	unchanged; still cannot password-sign-in, and we do not "repair" it	negative test
LDAP / DLDAP	login_type 2/5, login_name = uid or DN	identity with subject = the same string, byte-for-byte	bind against a test LDAP with the migrated value
SMTP	login_type 3, login_name = e-mail	identity with the e-mail as stored, no case folding	sign-in test
PAM	login_type 4	identity, unchanged verification path	sign-in test
OAuth2 with link row	user.login_* and external_login_user	one identity, built from the link row (keeps tokens/profile)	callback test, plus token-refresh test
OAuth2 without link row	only user.login_*	identity synthesized from user.login_*	callback test on a pre-link fixture
OpenID	user_open_id rows	identities under a synthetic OpenID source, Show preserved	sign-in test plus profile rendering test
SSPI	login_type 7 source rows	the source row is kept; SSPI simply stops being a password source and reads its config from that row	request-auth test
Dangling source	login_source points nowhere	parked and reported; already unable to sign in today, so no regression	doctor output assertion
Bot / remote / reserved / organization	type != 0	untouched	existing tests
2FA, WebAuthn, PATs, remember-me, sessions	two_factor, webauthn_credential, access_token, auth_token, session	untouched; Step 10 is a package move with table names preserved	existing tests must pass unchanged, and sessions must not be invalidated

6. Test strategy

• Fixture-based migration tests per step, using the existing pattern
  (modelmigration/migrationtest.PrepareTestEnv, modelmigration/fixtures/Test_*), with
  Test_UnwrapLDAPSourceCfg as the closest precedent for source-config surgery.
• One shared "legacy install" fixture containing exactly one user per row of the lockout matrix,
  reused by every step so equivalence is proven against the same data set throughout.
• A dual-write consistency test in release N that reads the old and the new location for every
  fixture and asserts they agree; it is the gate for the Step 6 read switch.
• Integration tests that exercise the real services/auth.UserSignIn (not a mock) against the
  migrated fixture, so the assertion is "this user can actually log in", not "the row looks right".
• An upgrade-and-login run for the two riskiest transitions (Step 5 backfill and Step 6 read switch).

7. Points that still need a decision

1. Duplicate (source, login_name) — my recommendation is to keep every row, mark the extras as
   parked, defer the unique index, and require an admin to resolve; the alternative (pick one
   deterministically) silently changes who owns an upstream identity.
2. UserOpenID.Show — carry it on user_identity, or keep a thin profile-preferences table?
3. Contract-release window — one minor release or two before the old columns and tables are
   dropped?
4. Auto-created SSPI / reverse-proxy accounts — should they get an identity row for their source,
   or remain credential-less local accounts as they are today?

---

Assisted-by: Codet:claude-opus-4-6

[lunny]

The description has been rewritten so the data-migration contract is part of the design instead of a
follow-up note. The addendum above is now folded in, and the changes are:

• Guarantees moved to the top as design constraints: no lockout, expand/migrate/contract,
  rollback safety, idempotent backfills, nothing discarded.
• New "old → new mapping" table covering every legacy column and table, so "no data loss" is
  verifiable field by field rather than asserted.
• New Step 0 freeing login_name from its non-authentication use by the Actions bot (D9), which
  has to happen before anything else touches that column.
• The identity consolidation is split into expand (Step 4: create + backfill + dual write) and
  migrate (Step 5: read switch) in different releases, with all destructive changes moved into a
  separate contract release (Step 12). The unique index on (source_id, subject) is deferred there
  too, so an upgrade can never fail on pre-existing duplicates.
• Step 9 (the all-sources fallback loop) now ships behaviour-preserving by default; it is the only
  step that could change who is able to log in.
• Release phasing table showing which step lands in which release.
• Lockout matrix and test strategy are in the body, with a per-class fixture set introduced in
  Step 1 and reused by every later step, asserted through the real UserSignIn rather than a mock.

---

Assisted-by: Codet:claude-opus-4-6

[lunny]

Correction: there is no local/external dichotomy

A review comment pointed out that user.passwd simply is the local account's password, and that a
non-zero login_source does not make the account "external" — it may well be both a local account
and an account of a login source. Verifying that against the code shows it is not just true, it is
true more strongly than the proposal assumed, and the description has been updated accordingly.

What the code actually does

• The OAuth2 source's Authenticate delegates straight back to the DB authenticator
  (services/auth/source/oauth2/source_authenticate.go:15). An OAuth2 account's password is verified
  locally; the source only supplies the identity. That is why UpdateAuth permits password changes
  for IsLocal() || IsOAuth2() (services/user/update.go:212).
• SMTP and PAM auto-registration writes the submitted upstream password into the account
  (services/auth/source/smtp/source_authenticate.go:73,
  services/auth/source/pam/source_authenticate.go:57), hashed by CreateUser
  (models/user/user.go:757). Those accounts have a local password hash that is never used for
  verification and never refreshed. LDAP stores none
  (services/auth/source/ldap/source_authenticate.go:82-90).

So IsLocal() (models/user/user.go:238) means none of the three things it is used for: not "is a
local account" (all are), not "has a local password" (SMTP/PAM do), not "password verified locally"
(OAuth2 is, yet returns false). With EXTERNAL_USER_DISABLE_FEATURES = manage_credentials an OAuth2
user is even denied management of the password they sign in with
(models/user/user.go:1460, routers/web/user/setting/account.go:54).

Changes to the proposal

• New P11 documenting the contradiction, since it is the root cause behind P2, P3 and P4 rather
  than a separate cosmetic issue.
• Principles rewritten: every user row is a local account, and credential (a locally stored
  secret), password verifier (who checks a submitted password) and identity (who the user is
  according to a source) are three orthogonal concepts. Any combination is legal.
• Schema gains an explicit user.password_verifier_source_id, replacing the implicit meaning of
  login_source. OAuth2 accounts map to the local verifier, which is what they already do at
  runtime, so "local account with an OAuth2 identity" stops being a contradiction. IsLocal() splits
  into HasLocalPassword(), PasswordVerifiedLocally() and HasExternalIdentity().
• New D3/D3b in the legacy-data list, and the mapping table now states that credentials are
  migrated verbatim for every account that has one — OAuth2 (live password) and SMTP/PAM (stale
  hash) included, since dropping either would violate G1 or G5.
• Lockout matrix updated: OAuth2 rows now require a password sign-in assertion, and SMTP/PAM accounts
  with a stale hash are their own row.
• Two new open questions: whether auto-registration should keep capturing SMTP/PAM passwords at all
  (it changes IsPasswordSet() and invalidates outstanding reset links), and whether deactivating the
  local source should also disable the OAuth2 password delegation.

---

Assisted-by: Codet:claude-opus-4-6

[lunny]

Clarification: SMTP/PAM do copy the remote password, OAuth2 does not

My earlier comment lumped OAuth2 together with SMTP/PAM, which was imprecise. The two cases are
different and only one of them is a defect. Verified against the code:

SMTP and PAM — confirmed, and it should not happen. On auto-registration the password the user
just typed (already verified against the remote server) is written into the local account and hashed
by CreateUser:

• services/auth/source/smtp/source_authenticate.go:69-76 — Passwd: password
• services/auth/source/pam/source_authenticate.go:53-60 — Passwd: password
• models/user/user.go:757 — CreateUser hashes whatever is in Passwd

It happens only on creation (if user != nil { return user, nil } short-circuits later logins), so
the value is never used for verification and never refreshed. LDAP already does the right thing and
stores nothing (services/auth/source/ldap/source_authenticate.go:82-90).

OAuth2 — no remote password exists, so nothing is copied. A password on an OAuth2 account is a
genuinely local one chosen on the link-register form
(routers/web/auth/linkaccount.go:234), and it is deliberately cleared when external-only
registration is configured (routers/web/auth/linkaccount.go:213-219). What I was actually pointing
at for OAuth2 is a different thing: its Authenticate delegates to the DB authenticator
(services/auth/source/oauth2/source_authenticate.go:15), so an OAuth2 account's password
verification is local. That is P11, not a stored-remote-credential problem.

Why the SMTP/PAM copy is worth removing — beyond being conceptually wrong:

1. A hash of a third-party credential sits in Gitea's DB for the account's lifetime. A DB leak then
   exposes the user's corporate SMTP or PAM password, not merely a Gitea-scoped one.
2. IsPasswordSet() returns true for these accounts, which drives UI branching
   (templates/user/settings/account.tmpl:10) even though the value is dead.
3. If an administrator later switches such an account to the local source, the user's old remote
   password silently becomes a valid Gitea password.

Added to the proposal as Step 1b, which stands on its own and does not depend on the rest of the
refactor. The ordering matters because makeTimeLimitCodeHashData currently includes u.Passwd
(models/user/user.go:919):

1. Replace u.Passwd in the activation/reset signature with a credential version marker, preserving
   the "a reset link dies when the password changes" property without hashing the secret itself.
2. Stop setting Passwd in SMTP and PAM auto-registration.
3. Migration clearing passwd, salt and passwd_hash_algo for accounts verified by a remote source,
   leaving local and OAuth2 accounts untouched.

No lockout: these accounts are verified by their source (services/auth/signin.go:74) and were already
refused by the reset and change-password paths (routers/web/auth/password.go:75,
templates/user/settings/account.tmpl:7). The one intentional behaviour change — switching such an
account to the local source no longer silently re-enables the old remote password — goes in the release
notes. Also added as principle 6: Gitea never stores a credential belonging to another system.

---

Assisted-by: Codet:claude-opus-4-6

[lunny]

Step 1b is now tracked on its own in #38905, since it needs no
schema redesign and does not depend on any other step of this proposal: SMTP and PAM auto-registration
copy the user's remote password into the local account
(services/auth/source/smtp/source_authenticate.go:73,
services/auth/source/pam/source_authenticate.go:57, hashed at models/user/user.go:757), where it is
never used for verification and never refreshed.

That issue carries the full evidence, the impact, the three-part fix in the order required by
makeTimeLimitCodeHashData (models/user/user.go:919), the no-lockout analysis and the test plan. The
step description in the body above now links to it.

---

Assisted-by: Codet:claude-opus-4-6

[lunny]

Added Step 1a, tracked in #38906, and made it a prerequisite
for Step 1b (#38905): visibility before mutation.

Right now nothing in the UI answers "does this account have a local password, and who verifies it?" The
admin detail page shows only the auth source (templates/admin/user/view_details.tmpl:17-19) and the
user list has no such column or filter (templates/admin/user/list.tmpl:62-76) — while "auth source =
Local" and "has a local password" are genuinely different things: LDAP accounts have none, SMTP/PAM
accounts hold a captured copy of the remote one, OAuth2 accounts may hold a live local one that the
OAuth2 source itself verifies via the DB authenticator, and local accounts may have none at all.

Step 1a therefore adds HasLocalPassword() / PasswordVerifiedLocally(), the two admin detail rows, a
has_local_password status filter in the user list (following the is_2fa_enabled precedent at
models/user/search.go:143-151), and a message on the user's own account page naming the source that
manages their password. No schema change, no behaviour change.

Ordering it before the purge means an administrator can enumerate the affected accounts beforehand and
cross-check the migration report afterwards, so IsPasswordSet() flipping to false reads as an
intended cleanup rather than data loss.

---

Assisted-by: Codet:claude-opus-4-6

[briantopping]

Four schema questions, from a deployment that runs Gitea with the identity of record deliberately
outside the forge. All four decide whether SCIM-style external account management is implementable
on top of this design — which #23794 has had as an unchecked item since 2023.

The ask

1. Is user_identity.subject guaranteed stable and never reused? If it may be a mutable handle —
   an email, a provider-side username — say so, because then it cannot be an addressing key.
2. Can an auth_source carry a stable identifier of its own (issuer, or configured name) rather
   than (source_id, subject) inheriting an autoincrement's lifetime?
3. May a user_identity row exist without, and outlive, its user row?
4. Could the primary email of an externally-authenticated account be a projection of the source
   with a defined refresh, rather than a value copied at creation? And, related: could provisioning
   accept an identity that arrives without one?

A fifth, smaller, on open question 7: yes to disabling password verification when the local source is
deactivated — and if it is not too much, an account whose password_verifier_source_id points at a
non-local source should be unable to acquire a local credential, not merely unable to use one.

Why: each one is what SCIM needs

#23794's stated goal is "to enable Gitea accounts to be fully managed from an external auth
provider, which is a requirement for most enterprise applications." Three of its open items are, I
think, blocked on schema rather than on effort. There is no SCIM implementation in the tree today —
rg -i scim returns nothing — and this proposal is the schema that would make one possible.

(1) — because SCIM addresses users by an external identifier. externalId in RFC 7643 is exactly
user_identity.subject. Its whole contract is that the value is stable for the life of the account
and never reassigned. Today that value has no single home: it is spread across user.login_name,
external_login_user and user_open_id, which is the duplication this proposal opens by describing.
If subject may change or recycle, a provisioning endpoint has to carry its own parallel mapping
table, which reintroduces exactly what is being removed.

(2) — because a provisioning integration is configured once and pointed at many deployments.
(source_id, subject) inherits whatever stability source_id has. If it is a local row id, then a
source re-created on a rebuilt instance produces a different pair for the same human. That is the
manual remap operators are already doing by hand in #16832 —
UPDATE user SET login_source = <new_id> WHERE login_source = <old_id> — relocated one table over
rather than resolved.

(3) — because SCIM creates before first sign-in and deactivates without deleting. Its common
case is not DELETE, it is active: false. Both are simpler if the identity row is not strictly a
property of an already-existing account. If the answer is no, that is a fine answer — it just decides
whether provisioning is "create the identity, bind an account later" or "create the account eagerly,"
and downstream work should not have to guess.

(4) — because #23794 asks for it directly:

Any other changes in user account from external auth tool should be mirrored in gitea, not just on
account creation

A value copied at registration is stale the moment the source changes, and nothing re-syncs it. The
pattern for fixing that already exists in the same code path: oauth2UpdateAvatarIfNeed
(routers/web/auth/oauth.go:319) re-fetches a provider-owned attribute on every login, behind
OAuth2Client.UPDATE_AVATAR. Email is not obviously harder — display already goes through
GetEmailForDisplay, and the bulk of the remaining reads are avatar hashing and mail delivery, both
at points where a fetch is affordable. The reverse lookups (GetUserByEmail and relatives) do need a
local index, but those resolve the user-declared user_email addresses used for commit matching,
which are a different concept from the address an IdP owns.

The creation half is our concrete blocker: our provider issues a token carrying identity and nothing
else, by design, so ExternalIdentity.Email arrives empty and every one of our users is created by
hand and then linked.

(5) — because #23794 asks for that too:

Remove ability to add/reset password, add/change email, (or any other options that should be
overwritten with SSO)

Open since 2023, and I think because there is currently no way to say "this account has no local
secret and may not acquire one" — only a convention of never setting one. user_credential plus an
explicit password_verifier_source_id makes it representable, which is the difference between a
property an operator audits and one the schema enforces. #38906 exists because that property is
currently invisible.

What this would not solve

• Token revocation — [Thread] SSO Auth Tracking #23794's remaining point, that "even if access is revoked from SSO, the user
  can continue to operate using their access tokens." A stable identity makes the check
  expressible; it does not implement it, and the per-request latency question is real.
• SCIM itself. This makes it implementable, not implemented. The endpoint, the PATCH semantics
  and the filtering are all still work, and none of it is in this proposal's scope.
• Rotation (Secret rotation / secret loss recovery #16832). Password-less accounts remove one class of instance-bound secret; 2FA rows
  and remaining source configs stay encrypted to SECRET_KEY.

None of the above is a request for scope. If the answers are "stable", "row id", "no" and "copied at
creation", that is a coherent design too — it just means external account management stays a
per-deployment problem, and it would be useful to have that written down.

EDIT: I'd contribute on aspects that make these requests tractable, such as a SCIM endpoint.

[briantopping]

Narrowing my question (4), and correcting myself on one point.

I asked whether the primary email of an externally-authenticated account could be a projection of the source with a defined refresh. That is more than is needed. The address is a routing concern rather than an identity attribute, and an operator who owns it has nothing stale to re-sync.

What remains is the second half: that provisioning accept an identity arriving without an email, or that the field be nullable when another transport is configured. Gitea already has transports other than SMTP — the /notifications API and system-level webhooks — so an installation consuming those has no deliverability requirement to satisfy, yet CreateUserOption still requires the field.

The correction: I said the creation half was our concrete blocker. CreateUserOption accepts login_name and source_id, so for accounts we provision we can write the external subject at creation and read it back through the ordinary user API. Self-registration through the OIDC source is the real gap — and I have not verified whether a login_name written that way survives a later account link.

(1), (2), (3) and (5) are unchanged.

[lunny]

@briantopping thanks — the four schema questions are the right ones to ask before the schema is
written rather than after. The description now answers them in a new "External addressing contract"
section, and I have verified each answer against the code rather than asserting it.

(1) subject stability — yes, but deliberately not as a blanket promise.
subject is written once at link time and never rewritten; an upstream rename updates
user_identity.login_name only. That is a real guarantee where the provider gives us a stable
identifier: OAuth2/OIDC sub and OpenID URIs. It is not true for LDAP, SMTP and PAM, where the
migrated subject is the same string as login_name — a uid, a DN or an e-mail — and upstream may
legitimately change it. Claiming otherwise would be a promise the data cannot keep. So stability is a
source capability declared alongside the other capabilities, not a property of the column. A
source that can offer something better (LDAP entryUUID / objectGUID) can opt in later with no
schema change. For your case that means externalId is addressable and stable, provided the source
is one that declares it.

(2) A stable source identifier — it already exists.
login_source.name is UNIQUE (models/auth/source.go:122) and is already the OIDC provider name.
The design now states that external addressing is (source name, subject) and that source_id is an
internal foreign key only. A source recreated on a rebuilt instance under the same name keeps
addressing the same humans, which is exactly the manual
UPDATE user SET login_source = <new_id> remap from #16832, resolved instead of relocated. This
costs nothing, so there was no reason to leave it implicit.

(3) Identity without, and outliving, a user row — yes.
user_identity.user_id may be zero, meaning "not bound to an account yet". Backfill never produces
such a row and no sign-in path accepts one; it exists so that "create the identity, bind the account
later" is representable. Recorded as open question 8 so it can still be argued down — but if it is,
migration and sign-in behave identically, so it is not load-bearing for this refactor.

(4) Email — agreed with your own narrowing, and it is out of scope here.
The projection-with-refresh half is more than is needed, as you say. The remaining half — provisioning
accepting an identity without an e-mail — is an API policy question, not a schema one:
CreateUserOption.Email is binding:"Required" (modules/structs/admin_user.go:23) and OIDC
self-registration refuses the same way (routers/web/auth/oauth.go:165, the
__giteaAutoRegMissingFields path that pushes you to the link page). This proposal does not change
it, but Step 8 collapses that decision into a single provisioning service, so it becomes one change in
one place afterwards. Listed under non-goals rather than quietly dropped.

Correcting your correction: you were right that CreateUserOption lets you write the subject at
creation, and you can stop worrying about the other half — LinkAccountToUser
(services/externalaccount/user.go:41) only inserts into external_login_user; it never touches
user.login_name or user.login_source. So a login_name written at provisioning time does survive
a later link. It survives as two copies of the same identity, which is precisely the duplication
described as D5 and which the backfill deduplicates on (source_id, subject), preferring the link row.

(5) Not merely unable to use a local credential, but unable to acquire one — adopted.
This is now a design point rather than open question 7: an account whose password_verifier_source_id
is not the local source may not acquire a local credential at all. Step 1a (#38906) gains the
acquisition-side gate, so every path that creates or resets a local secret refuses. That is the
difference between a convention and an enforced property, and it is what #23794's "remove ability to
add/reset password" has been missing.

SCIM itself stays out of scope and is now named as such in the non-goals: this schema should make it
implementable, and it should not be able to claim the schema as a blocker afterwards. If you do pick
up an endpoint later, the contract above is what you can rely on — and if any part of it is
insufficient for RFC 7643, better to find that out now.

---

Assisted-by: Codet:claude-opus-4-6

[briantopping]

Thank you — that answers everything I asked, and one thing I could not verify myself.

(source name, subject) is better than what I asked for: keying on the unique source name rather than the row id removes the rebuild problem at the root instead of moving it one table over. And making stability a declared source capability rather than a blanket promise is the more honest answer — a guarantee the LDAP path cannot keep would have been worse than none.

The LinkAccountToUser detail is what unblocks us, and I appreciate you checking it rather than assuming. We will treat a login_name written at provisioning time as a bridge rather than a foundation, and expect the backfill to prefer the link row.

Adopting (5) on the acquisition side is the part I would have argued for hardest — the difference between a convention and an enforced property is the whole point.

Nothing further needed from our side. If we do pick up a SCIM endpoint, this contract is enough to build against.