Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

fix(gateway): close the null-issuer collision, use savepoints for the OIDC race retry, and stop silently guessing on duplicate emails (CHOO-2624)

Wojciech Wojtyniakf228b2ac35cc
diff --git a/core/switch_core/config.py b/core/switch_core/config.py
index 103fd4b8f..4c09c9b07 100644
--- a/core/switch_core/config.py
+++ b/core/switch_core/config.py
@@ -60,9 +60,16 @@ class SwitchConfig(BaseSettings):
#
# This only controls whether an unverified login is accepted at all — for
# a brand-new identity, or one already linked to an account. It never lets
- # an unverified email link a new identity into a *different*, pre-existing
- # account: that always requires the IdP to assert `email_verified=true`,
- # regardless of this setting. See UserStore.get_or_create_oidc_user.
+ # an unverified email link a *new* identity into a *different*,
+ # pre-existing account: that always requires the IdP to assert
+ # `email_verified=true`, regardless of this setting. See
+ # UserStore.get_or_create_oidc_user.
+ #
+ # Exception: a legacy identity linked before issuers were tracked at all
+ # resolves, and has its issuer backfilled, purely by matching its stored
+ # subject — it never consults email, `email_verified`, or this setting.
+ # That is not new here; it is the same subject-only match this login has
+ # always done for such a row. See OidcIdentity's docstring in models.py.
gateway_oidc_require_email_verified: bool = True
# Lets the password login path be disabled (OIDC-only) without code changes.
gateway_password_login_enabled: bool = True
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index e4c169895..dda48abda 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -71,15 +71,34 @@ class OidcIdentity(Base):
predates the issuer being tracked at all (``oidc_sub`` stored alone); the
application never writes a NULL issuer itself. Such a row still matches on
``sub`` alone and has its issuer backfilled on the next login, same as
- before this identity had its own table — ``sub`` is unique per issuer, so
- matching on it alone is safe in practice given a deployment registers one
- issuer.
+ before this identity had its own table. ``UNIQUE(iss, sub)`` does not
+ constrain these rows at all — Postgres treats every NULL as distinct from
+ every other NULL — so ``ix_oidc_identities_sub_null_iss`` separately
+ enforces at most one NULL-issuer row per ``sub``; without it two different
+ users could each hold one for the same ``sub``, and which one a login
+ resolved to would depend on row order, silently annexing one account and
+ orphaning the other.
+
+ Matching a legacy row on ``sub`` alone, with no issuer or email in the
+ comparison at all, is only safe because a deployment has exactly one
+ configured issuer (``gateway_oidc_issuer_url``) today. The moment a second
+ issuer exists — a later multi-tenancy phase — two different real-world
+ identities could share the same subject string, and a legacy row would
+ resolve to whichever one asserts it first regardless of which issuer
+ actually owns it. Re-verify or purge sub-only rows before a deployment is
+ ever configured with more than one issuer.
"""
__tablename__ = "oidc_identities"
__table_args__ = (
UniqueConstraint("iss", "sub", name="uq_oidc_identities_iss_sub"),
Index("ix_oidc_identities_sub", "sub"),
+ Index(
+ "ix_oidc_identities_sub_null_iss",
+ "sub",
+ unique=True,
+ postgresql_where=text("iss IS NULL"),
+ ),
)
id: Mapped[str] = mapped_column(Text, primary_key=True, default=_uuid)
diff --git a/core/switch_core/db/stores/user_store.py b/core/switch_core/db/stores/user_store.py
index b4b8187b6..406c5bc51 100644
--- a/core/switch_core/db/stores/user_store.py
+++ b/core/switch_core/db/stores/user_store.py
@@ -23,6 +23,21 @@ class OidcIdentityConflictError(Exception):
account: an unverified email is attacker-controllable, so trusting it to
pick an account is an account-takeover vector. A verified email links
instead — see ``get_or_create_oidc_user``.
+
+ A rejected security decision, not a retry-able condition — distinct from
+ ``OidcIdentityRaceError``, so an operator watching for the latter is not
+ drowned in the former (or vice versa).
+ """
+
+
+class OidcIdentityRaceError(Exception):
+ """Two logins raced to provision or link the same identity or email twice
+ in a row.
+
+ Transient contention, not a security decision: the caller should retry
+ the login rather than treat this as an attack signal. Kept separate from
+ ``OidcIdentityConflictError`` so the two can be told apart in logs and
+ given different HTTP treatment at the callback.
"""
@@ -39,15 +54,32 @@ class UserStore:
reliably agree on the casing of the same mailbox, and accounts must
be the same account regardless. Backed by ``ix_users_email_lower``.
- Uses the first match rather than requiring exactly one: two rows
- differing only in case could already exist from before this method
- compared case-insensitively, and a login must not turn that into a
- 500.
+ ``users.email`` is still case-sensitively unique, so two rows
+ differing only in case can already exist from before this method
+ compared case-insensitively. A login must not turn that into a 500,
+ but silently guessing between two real accounts — one of which could
+ be an admin — is exactly the kind of quiet fallback CLAUDE.md rules
+ out: ordering is made deterministic (oldest account wins, as the
+ presumed original) and the ambiguity itself is logged loudly so it
+ gets noticed and cleaned up rather than repeating unnoticed on every
+ login.
"""
result = await session.execute(
- select(User).where(func.lower(User.email) == email.lower())
+ select(User)
+ .where(func.lower(User.email) == email.lower())
+ .order_by(User.created_at, User.id)
)
- return result.scalars().first()
+ users = result.scalars().all()
+ if len(users) > 1:
+ logger.error(
+ "Multiple users share email %r case-insensitively (ids: %s); "
+ "returning the oldest. This is pre-existing duplicate data, "
+ "not something this login caused — merge or rename the "
+ "extra account(s).",
+ email,
+ [u.id for u in users],
+ )
+ return users[0] if users else None
async def get_by_oidc_identity(
self, session: AsyncSession, *, iss: str, sub: str
@@ -57,6 +89,8 @@ class UserStore:
A row with no stored issuer predates CHOO-2624 tracking one at all; it
matches on ``sub`` alone and has its issuer backfilled here, same as
this identity did before it had its own table.
+ ``ix_oidc_identities_sub_null_iss`` guarantees at most one such row per
+ ``sub``, so this is a well-defined lookup and not a guess between rows.
"""
result = await session.execute(
select(User)
@@ -72,7 +106,7 @@ class UserStore:
OidcIdentity.iss.is_(None), OidcIdentity.sub == sub
)
)
- identity = legacy.scalars().first()
+ identity = legacy.scalar_one_or_none()
if identity is None:
return None
identity.iss = iss
@@ -100,15 +134,24 @@ class UserStore:
signed up with a password and later signs in with an IdP sharing that
email lands in the same account instead of a second one.
- An unverified email must never pick an existing account: that is an
- attacker-controllable claim, so a collision with a pre-existing
- account is refused rather than linked. A brand-new email — verified
- or not — provisions a fresh ``user`` (no password hash).
+ An unverified email must never pick an *existing, different* account:
+ that is an attacker-controllable claim, so a collision is refused
+ rather than linked. A brand-new email — verified or not — provisions
+ a fresh ``user`` (no password hash), stored lower-cased so accounts
+ this method creates don't add new case variants of their own; this
+ does not touch the casing of any pre-existing row. This guarantee
+ does not extend to a legacy identity already linked before issuers
+ were tracked (see ``get_by_oidc_identity``): that keeps resolving,
+ and backfilling its issuer, purely by matching ``sub`` — without
+ consulting email, ``email_verified``, or even the issuer on the
+ incoming claim — exactly as it did before this identity had its own
+ table.
Two logins racing to provision or link the same identity or the same
- new email hit a unique-constraint conflict rather than either one
- silently overwriting the other; this retries once against whichever
- row won, so the raced request resolves to that row instead of a 500.
+ new email hit a unique-constraint conflict inside a savepoint rather
+ than either one silently overwriting the other or losing the rest of
+ the caller's transaction; this retries once against whichever row
+ won, so the raced request resolves to that row instead of a 500.
"""
for attempt in range(1, _MAX_ATTEMPTS + 1):
user = await self.get_by_oidc_identity(session, iss=iss, sub=sub)
@@ -123,27 +166,32 @@ class UserStore:
"this identity's email is not verified."
)
try:
- await self._link_identity(session, user=existing, iss=iss, sub=sub)
+ async with session.begin_nested():
+ await self._link_identity(
+ session, user=existing, iss=iss, sub=sub
+ )
except IntegrityError:
- await self._recover_from_race(session, attempt)
+ self._raise_if_exhausted(attempt)
continue
return existing
- user = User(name=name, email=email, role="user", password_hash=None)
+ user = User(name=name, email=email.lower(), role="user", password_hash=None)
try:
- await self.create(session, user)
- await self._link_identity(session, user=user, iss=iss, sub=sub)
+ async with session.begin_nested():
+ await self.create(session, user)
+ await self._link_identity(session, user=user, iss=iss, sub=sub)
except IntegrityError:
- await self._recover_from_race(session, attempt)
+ self._raise_if_exhausted(attempt)
continue
return user
raise AssertionError("unreachable: the loop above always returns or raises")
- async def _recover_from_race(self, session: AsyncSession, attempt: int) -> None:
- await session.rollback()
+ def _raise_if_exhausted(self, attempt: int) -> None:
+ # The savepoint above already rolled back just the failed write, not
+ # the caller's whole transaction, so nothing to undo here.
if attempt == _MAX_ATTEMPTS:
- raise OidcIdentityConflictError(
+ raise OidcIdentityRaceError(
"OIDC identity resolution raced twice in a row; refusing to "
"guess a winner a third time."
)
@@ -151,13 +199,16 @@ class UserStore:
async def _link_identity(
self, session: AsyncSession, *, user: User, iss: str, sub: str
) -> None:
+ session.add(OidcIdentity(user_id=user.id, iss=iss, sub=sub))
+ await session.flush()
# The most security-relevant event this store performs: it decides
# which account an external identity provider can now sign in as.
+ # Logged only after the flush succeeds, so a racer that loses to a
+ # concurrent write (see get_or_create_oidc_user) never logs a link
+ # that didn't happen.
logger.warning(
"Linking OIDC identity (iss=%r, sub=%r) to user %s", iss, sub, user.id
)
- session.add(OidcIdentity(user_id=user.id, iss=iss, sub=sub))
- await session.flush()
async def get_all(self, session: AsyncSession) -> list[User]:
result = await session.execute(select(User))
diff --git a/core/switch_core/gateway/oidc_routes.py b/core/switch_core/gateway/oidc_routes.py
index 0ac2e3ed0..9cbde51c5 100644
--- a/core/switch_core/gateway/oidc_routes.py
+++ b/core/switch_core/gateway/oidc_routes.py
@@ -9,7 +9,11 @@ from sqlalchemy.ext.asyncio import AsyncSession
from starlette.responses import RedirectResponse
from switch_core.config import SwitchConfig
-from switch_core.db.stores.user_store import OidcIdentityConflictError, UserStore
+from switch_core.db.stores.user_store import (
+ OidcIdentityConflictError,
+ OidcIdentityRaceError,
+ UserStore,
+)
from switch_core.gateway.auth import set_session_cookie
from switch_core.gateway.dependencies import get_config, get_session, get_user_store
@@ -128,6 +132,17 @@ async def oidc_callback(
except OidcIdentityConflictError as exc:
logger.warning("OIDC identity conflict: %s", exc)
raise HTTPException(status_code=409, detail=str(exc)) from exc
+ except OidcIdentityRaceError as exc:
+ # Transient contention, not a rejected security decision (see the
+ # exception's docstring) — 503 so an operator's dashboards can tell
+ # this apart from the 409s above rather than lumping a retry storm in
+ # with attack signal.
+ logger.warning("OIDC identity resolution raced: %s", exc)
+ raise HTTPException(
+ status_code=503,
+ detail="Login is temporarily contended, please try again",
+ headers={"Retry-After": "1"},
+ ) from exc
await session.commit()
# Verify-at-login only: we don't persist the IdP tokens. Land the browser
diff --git a/core/switch_core/migrations/versions/04f27f37e474_oidc_identities_table.py b/core/switch_core/migrations/versions/04f27f37e474_oidc_identities_table.py
index 68fc2a05b..d7c9b621f 100644
--- a/core/switch_core/migrations/versions/04f27f37e474_oidc_identities_table.py
+++ b/core/switch_core/migrations/versions/04f27f37e474_oidc_identities_table.py
@@ -22,6 +22,16 @@ never emits ``email_verified``, e.g. Okta's org authorization server for
directory users) keeps logging that account in rather than being newly locked
out or forked into a second account by a changed email.
+``UNIQUE(iss, sub)`` does not constrain a NULL issuer at all — Postgres never
+considers two NULLs equal — so a separate partial unique index enforces at
+most one such row per subject; without it, two different users sharing a
+legacy subject would both migrate cleanly and a login would then resolve to
+whichever one the lookup happened to see first. Two users cannot share a
+legacy subject in practice (each was some real person's login), so this
+refuses to proceed rather than guess which one is right if it ever finds one:
+that is a data problem for a human to resolve by hand, not one this migration
+should paper over by silently picking a side.
+
The email column also gains a case-insensitive index: linking now matches an
existing account by email, and a compare that ignored case here would defeat
the very guarantee this migration exists to add.
@@ -39,6 +49,30 @@ depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
+ connection = op.get_bind()
+
+ duplicates = connection.execute(
+ sa.text(
+ """
+ SELECT metadata->>'oidc_sub' AS sub, count(*) AS n
+ FROM users
+ WHERE metadata ? 'oidc_sub' AND NOT (metadata ? 'oidc_iss')
+ GROUP BY metadata->>'oidc_sub'
+ HAVING count(*) > 1
+ """
+ )
+ ).fetchall()
+ if duplicates:
+ raise RuntimeError(
+ "Refusing to migrate: more than one user shares the same legacy "
+ "oidc_sub with no recorded issuer, which cannot be told apart by "
+ "subject alone: "
+ + ", ".join(f"{row.sub!r} ({row.n} users)" for row in duplicates)
+ + ". Resolve by hand — decide which account actually owns each "
+ "subject and clear oidc_sub from users.metadata for the "
+ "other(s) — then re-run this migration."
+ )
+
op.create_table(
"oidc_identities",
sa.Column("id", sa.Text(), primary_key=True),
@@ -54,9 +88,15 @@ def upgrade() -> None:
sa.UniqueConstraint("iss", "sub", name="uq_oidc_identities_iss_sub"),
)
op.create_index("ix_oidc_identities_sub", "oidc_identities", ["sub"])
+ op.create_index(
+ "ix_oidc_identities_sub_null_iss",
+ "oidc_identities",
+ ["sub"],
+ unique=True,
+ postgresql_where=sa.text("iss IS NULL"),
+ )
op.create_index("ix_users_email_lower", "users", [sa.text("lower(email)")])
- connection = op.get_bind()
connection.execute(
sa.text(
"""
@@ -79,10 +119,13 @@ def downgrade() -> None:
"""Best effort, not a full inverse.
A user linked to more than one identity — impossible under the old
- single-slot ``metadata`` pair this recreates — keeps only one of them,
- picked by whichever row this UPDATE visits last for that user. That loss
- is inherent to the old shape, not a defect in this statement: there is
- nowhere to put a second identity once ``oidc_identities`` is gone.
+ single-slot ``metadata`` pair this recreates — keeps only one of them.
+ When an UPDATE ... FROM matches a target row against more than one source
+ row, PostgreSQL applies exactly one of them and which one is unspecified
+ — not a documented "last write wins" order, just whichever the query
+ plan happens to produce. That loss is inherent to the old shape, not a
+ defect in this statement: there is nowhere to put a second identity once
+ ``oidc_identities`` is gone.
"""
connection = op.get_bind()
connection.execute(
@@ -110,5 +153,6 @@ def downgrade() -> None:
)
)
op.drop_index("ix_users_email_lower", table_name="users")
+ op.drop_index("ix_oidc_identities_sub_null_iss", table_name="oidc_identities")
op.drop_index("ix_oidc_identities_sub", table_name="oidc_identities")
op.drop_table("oidc_identities")
diff --git a/core/tests/switch_core/db/stores/test_user_store_oidc.py b/core/tests/switch_core/db/stores/test_user_store_oidc.py
index f20db655a..39dd8ad3a 100644
--- a/core/tests/switch_core/db/stores/test_user_store_oidc.py
+++ b/core/tests/switch_core/db/stores/test_user_store_oidc.py
@@ -8,7 +8,11 @@ from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from switch_core.db.models import OidcIdentity, User
-from switch_core.db.stores.user_store import OidcIdentityConflictError, UserStore
+from switch_core.db.stores.user_store import (
+ OidcIdentityConflictError,
+ OidcIdentityRaceError,
+ UserStore,
+)
_ISS = "https://idp.example.com"
@@ -35,6 +39,25 @@ class TestGetOrCreateOidcUser:
again = await store.get_by_oidc_identity(session, iss=_ISS, sub="okta|9")
assert again is not None and again.id == user.id
+ async def test_new_user_email_is_stored_lowercase(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ # An account this method creates should not add a new case variant of
+ # its own, even though the lookup that precedes creation is already
+ # case-insensitive and would have caught a collision either way.
+ store = UserStore()
+ async with session_factory() as session:
+ user = await store.get_or_create_oidc_user(
+ session,
+ iss=_ISS,
+ name="New",
+ sub="okta|10",
+ email_verified=True,
+ )
+ await session.commit()
+ assert user.email == "[email protected]"
+
async def test_same_identity_is_returned_and_keeps_role(
self, session_factory: async_sessionmaker[AsyncSession]
) -> None:
@@ -127,6 +150,36 @@ class TestGetOrCreateOidcUser:
assert linked.id == existing.id
+ async def test_pre_existing_case_duplicate_emails_resolve_deterministically_and_log(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ caplog: pytest.LogCaptureFixture,
+ ) -> None:
+ # users.email is still case-sensitively unique, so two rows differing
+ # only by case can exist from before get_by_email compared
+ # case-insensitively (or from a path that bypasses this store
+ # entirely). A login must not crash on that, but silently guessing
+ # between two real accounts is exactly the quiet fallback CLAUDE.md
+ # rules out: the choice must be deterministic and disclosed.
+ store = UserStore()
+ async with session_factory() as session:
+ older = User(name="Old", email="[email protected]", role="admin")
+ newer = User(name="New", email="[email protected]", role="user")
+ await store.create(session, older)
+ await store.create(session, newer)
+ await session.commit()
+
+ with caplog.at_level(
+ logging.ERROR, logger="switch_core.db.stores.user_store"
+ ):
+ found = await store.get_by_email(session, "[email protected]")
+
+ assert found is not None and found.id == older.id
+ assert any(
+ older.id in record.message and newer.id in record.message
+ for record in caplog.records
+ )
+
async def test_two_subjects_same_issuer_can_both_link_to_one_account(
self, session_factory: async_sessionmaker[AsyncSession]
) -> None:
@@ -337,6 +390,65 @@ class TestGetOrCreateOidcUser:
with pytest.raises(IntegrityError):
await session.commit()
+ async def test_null_issuer_sub_unique_constraint_is_enforced_at_the_db_level(
+ self, session_factory: async_sessionmaker[AsyncSession]
+ ) -> None:
+ # UNIQUE(iss, sub) does not constrain a NULL issuer at all — Postgres
+ # never treats two NULLs as equal — so this must be a separate,
+ # partial index; without it, two different users could each hold a
+ # legacy identity for the same subject and a lookup would resolve to
+ # whichever one it saw first.
+ store = UserStore()
+ async with session_factory() as session:
+ first = User(name="A", email="[email protected]", role="user")
+ second = User(name="B", email="[email protected]", role="admin")
+ await store.create(session, first)
+ await store.create(session, second)
+ session.add(OidcIdentity(user_id=first.id, iss=None, sub="dup-legacy"))
+ await session.commit()
+
+ session.add(OidcIdentity(user_id=second.id, iss=None, sub="dup-legacy"))
+ with pytest.raises(IntegrityError):
+ await session.commit()
+
+ async def test_race_exhausted_twice_raises_a_distinct_contention_error(
+ self,
+ session_factory: async_sessionmaker[AsyncSession],
+ monkeypatch: pytest.MonkeyPatch,
+ ) -> None:
+ # A single retry is meant for one raced write, not a store that keeps
+ # lying about what exists; a second collision must raise loudly under
+ # its own error type rather than being retried forever or mistaken
+ # for the security-rejection OidcIdentityConflictError.
+ store = UserStore()
+ async with session_factory() as winner_session:
+ await store.get_or_create_oidc_user(
+ winner_session,
+ iss=_ISS,
+ name="Winner",
+ sub="okta|always-races",
+ email_verified=True,
+ )
+ await winner_session.commit()
+
+ async with session_factory() as session:
+
+ async def always_misses(sess: AsyncSession, *, iss: str, sub: str):
+ return None
+
+ monkeypatch.setattr(store, "get_by_oidc_identity", always_misses)
+
+ with pytest.raises(OidcIdentityRaceError):
+ await store.get_or_create_oidc_user(
+ session,
+ iss=_ISS,
+ name="Loser",
+ sub="okta|always-races",
+ email_verified=True,
+ )
+
async def test_concurrent_creation_of_the_same_identity_resolves_to_the_winner(
self,
session_factory: async_sessionmaker[AsyncSession],
diff --git a/core/tests/switch_core/test_migration_oidc_identities_backfill.py b/core/tests/switch_core/test_migration_oidc_identities_backfill.py
index 53b2f2a1f..785c3bfa7 100644
--- a/core/tests/switch_core/test_migration_oidc_identities_backfill.py
+++ b/core/tests/switch_core/test_migration_oidc_identities_backfill.py
@@ -122,3 +122,44 @@ async def test_backfill_migrates_full_pairs_and_legacy_rows_and_leaves_others_al
# A row untouched by OIDC (no oidc_sub key, NULL metadata outright) is
# left exactly as it was.
assert by_id["password"] is None
+
+
+async def test_backfill_refuses_when_two_users_share_a_legacy_subject(
+ backfill_url: str,
+) -> None:
+ # Two users with the same oidc_sub and no recorded issuer can't be told
+ # apart by subject alone; UNIQUE(sub) WHERE iss IS NULL would reject the
+ # second INSERT anyway, but the pre-flight check exists to fail with a
+ # message a human can act on instead of a bare constraint violation.
+ engine = create_async_engine(backfill_url)
+ try:
+ async with engine.begin() as connection:
+ await connection.run_sync(_upgrade_to(_PRE_MIGRATION_REVISION))
+
+ async with engine.begin() as connection:
+ await connection.execute(
+ text(
+ """
+ INSERT INTO users (id, name, email, role, password_hash, metadata)
+ VALUES
+ ('claimant-a', 'A', '[email protected]', 'admin', NULL,
+ '{"oidc_sub": "okta|shared"}'),
+ ('claimant-b', 'B', '[email protected]', 'user', NULL,
+ '{"oidc_sub": "okta|shared"}')
+ """
+ )
+ )
+
+ with pytest.raises(RuntimeError, match="okta\\|shared"):
+ async with engine.begin() as connection:
+ await connection.run_sync(_upgrade_to(_MIGRATION_UNDER_TEST))
+
+ async with engine.connect() as connection:
+ table_exists = await connection.execute(
+ text(
+ "SELECT to_regclass('public.oidc_identities') IS NOT NULL AS exists"
+ )
+ )
+ assert table_exists.scalar() is False
+ finally:
+ await engine.dispose()