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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ All notable changes to this project are documented in this file. The format is b

### Added

- `users`: OAuth sign-ins store the IdP profile on the link: `users_oauth_account` gains `subject`, `username`, `display_name`, `extra` (Microsoft `oid`/`tid`) and `last_sign_in_at` (migration `e480d7dd348f`, users trunk), refreshed on every sign-in and listed under "Linked sign-ins" on the admin Edit user page. A new account takes `full_name` from the IdP's display name; `oauth_sync_profile` (off by default) updates it on later sign-ins. Google sign-in now also requests the People API `names` field for the display name. `OAuthProvider.get_identity` returns an `OAuthIdentity` instead of a tuple (#877).
- `users`: `oauth_trusted_email_domains` (e.g. `{"microsoft": ["iiasa.ac.at"]}`) makes addresses on listed domains count as verified for that provider, exact domain only. Allowed for `microsoft` (a member of a pinned tenant GUID; `upn`/`preferred_username`, or the `email` claim only with `xms_edov`; a token whose `upn` or `preferred_username` carries `#EXT#` is a guest and never trusted) and `oidc` (never over an explicit `email_verified: false`); Google and GitHub are refused because anyone can add an unverified address on any domain there (#878).

- `users`: `oauth_signup_providers` and `oauth_signup_default_role` provision accounts through SSO while local signup stays closed. A first sign-in through a listed provider creates the account when the provider proved the email, whatever `allow_signup` says; the account gets `oauth_signup_default_role`, or no role when it is blank (the default), even with signup open (not the self-signup `user` role), and `admin` is refused. A listed provider without email proof is refused even with signup open. Local registration and its links still follow `allow_signup`, and unlisted providers keep the old rule. The OAuth provider fields moved to `users.core.oauth_settings.OAuthSettings`, which `UsersSettings` inherits (#874).

- `users`: `oauth_microsoft_trust_tenant_upn` (off by default) lets a site that pins `oauth_microsoft_tenant` to one tenant GUID sign in pre-approved staff with Microsoft while self-signup stays closed. A member account's `userPrincipalName` then counts as a verified email, so the first Microsoft sign-in links to an invited or verified local account with that address instead of failing with `OAUTH_USER_ALREADY_EXISTS`. Guest UPNs (`#EXT#`) and empty identities stay unverified, the `mail` attribute is never used, and with `common`, `organizations`, `consumers` or a domain-name tenant the setting has no effect and logs `users.oauth.microsoft_trust_ignored`. Turning it on trusts the tenant's admins, who can set a member's UPN to any address in the tenant's domains (#873).
Expand Down
2 changes: 1 addition & 1 deletion docs/database/migrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ The history is **not** a single linear chain. It has several roots and several h

| Head | Owning module | Label Alembic reports |
|---|---|---|
| `f6c2d4e8b109` | file_storage (tenant browse index) | `api_tokens`, `background_tasks`, `file_storage`, `users` |
| `e480d7dd348f` | users (OAuth link profile, #877) | `api_tokens`, `background_tasks`, `file_storage`, `users` |
| `b8d4f2a6c901` | audit_log | `audit_log` |
| `f1a9c3d7b2e4` | tenants | `tenants` |
| `d263ea727663` | framework (`sm_lease`) | `leases` |
Expand Down
18 changes: 16 additions & 2 deletions docs/modules/users.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ permissions role pages. The edit page's *Recent activity* card reads the core

`UserAccessToken` (table `users_access_token`) — bearer API tokens, stored as SHA-256 digests (the secret is shown once at login); resolved by `UsersAuthProvider` on `Authorization: Bearer` requests (sessions remain the primary browser auth).

`OAuthAccount` (table `users_oauth_account`) — linked OAuth/OIDC accounts: `oauth_name`, `account_id`, `account_email`, `access_token`, `refresh_token`, `expires_at`.
`OAuthAccount` (table `users_oauth_account`) — linked OAuth/OIDC accounts: `oauth_name`, `account_id`, `account_email`, `access_token`, `refresh_token`, `expires_at`, plus the IdP profile refreshed on each sign-in (#877): `subject`, `username`, `display_name`, `extra`, `last_sign_in_at`.

`RefreshToken` (table `users_refresh_token`) — opaque refresh tokens for the bearer flow: `token` (PK, SHA-256 digest of the secret), `family_id` (rotation lineage; presenting an already-revoked token revokes the whole family), `user_id`, `created_at`, `expires_at`, `revoked_at`.

Expand Down Expand Up @@ -226,6 +226,8 @@ Everything else is DB-backed (initial values are pydantic defaults; edit under U
| `oauth_microsoft_client_id` / `oauth_microsoft_client_secret` / `oauth_microsoft_tenant` | `""` / `""` / `"common"` — Microsoft (Entra ID) |
| `oauth_microsoft_trust_tenant_upn` | `False` — treat a member's UPN (the `upn` claim, else `preferred_username`) as a verified email; only with a tenant GUID (see [Signing in pre-approved staff with Microsoft](#signing-in-pre-approved-staff-with-microsoft)) |
| `oauth_signup_providers` / `oauth_signup_default_role` | `[]` / `""` — providers that create accounts on first sign-in with `allow_signup` off, and the role those accounts get (see [Provisioning accounts through SSO](#provisioning-accounts-through-sso)) |
| `oauth_trusted_email_domains` | `{}` — per provider, domains whose addresses count as verified; `microsoft` and `oidc` only (see [Trusted email domains](#trusted-email-domains)) |
| `oauth_sync_profile` | `False` — update `full_name` from the IdP's display name on every sign-in, not only when the account is created |
| `oauth_oidc_client_id` / `oauth_oidc_client_secret` / `oauth_oidc_discovery_url` / `oauth_oidc_display_name` | `""` / `""` / `""` / `"OIDC"` — generic OIDC |

## Permissions
Expand Down Expand Up @@ -546,7 +548,7 @@ Microsoft email claims are tenant-controlled, so by default a Microsoft sign-in

For a site that admits one Entra directory, set `oauth_microsoft_tenant` to that tenant's GUID and turn on `oauth_microsoft_trust_tenant_upn`. A **member** account's UPN (the ID token's `upn` claim, else `preferred_username`) is on a domain the tenant verified, so it then counts as a verified email: it links to an invited or verified local account with that address, and an account it creates starts verified. The `mail` attribute and the `email` claim are never used.

- Guest and other external accounts (an `idp` claim naming another issuer, or a UPN containing `#EXT#`) and an empty username stay unverified.
- Guest and other external accounts (an `idp` claim naming another issuer, or a UPN containing `#EXT#`, even when another name claim such as `preferred_username` shows a listed-domain address) and an empty username stay unverified.
- With `common`, `organizations`, `consumers` (or its fixed GUID) or a domain-name tenant the setting has no effect, and the settings load logs a `users.oauth.microsoft_trust_ignored` warning.
- An unverified, un-invited local account with the same address is still refused (`OAUTH_ACCOUNT_NOT_VERIFIED`), and with `allow_signup=False` a Microsoft user who has no account is refused unless `microsoft` is in `oauth_signup_providers` (see below).
- A user whose UPN differs from the address they were invited with does not match the invite; invite them by their UPN.
Expand All @@ -560,6 +562,18 @@ With `allow_signup` off, an OAuth sign-in for an identity nobody holds is refuse
- `oauth_signup_default_role`: the role those accounts get, with `allow_signup` on too: a listed provider's accounts never get the `user` role that self-signup grants. Blank (the default) means none: the account signs in but holds no permissions until an admin grants a role. Every account the provider creates gets this role, so name one whose permissions you would give to anyone in that directory; `admin` is refused, and a name with no matching role is logged and grants nothing.
- Local registration (`POST /api/users/auth/register`, `/users/register`, the "Sign up" links) still follows `allow_signup` alone. Providers that are not listed keep the old rule: they create accounts only with `allow_signup` on, and those accounts get the `user` role.

### Trusted email domains

`oauth_trusted_email_domains` lets an operator vouch for addresses on domains their organisation owns, per provider, for example `{"microsoft": ["iiasa.ac.at"]}`. An address on a listed domain then counts as verified for that provider only, so it links to an invited or verified local account and can provision one (see above). Domains match exactly and case-insensitively after IDNA normalisation; subdomains are never implied.

- Only `microsoft` and `oidc` can be listed. Anyone can add an unverified address on any domain to a Google or GitHub account, so a domain cannot vouch for it there; those keys are refused.
- `microsoft` needs `oauth_microsoft_tenant` set to the tenant GUID (otherwise the domains are ignored and the settings load logs `users.oauth.trusted_domains_ignored`), and a member of that tenant: matching `tid` and no `idp` naming another issuer. The address is the `upn` claim or `preferred_username` on a listed domain; the user-editable `email` claim counts only when Entra marks its domain verified (the `xms_edov` optional claim).
- `oidc` trusts the address your IdP returns on a listed domain unless the IdP itself says `email_verified: false`. List a domain only if your IdP does not let users set their own email.

### Linked identities

Each sign-in refreshes the IdP profile on the account's `users_oauth_account` link: `subject` (`sub`), `username`, `display_name`, `extra` (Microsoft's `oid` and `tid`) and `last_sign_in_at`. The admin **Edit user** page lists them under "Linked sign-ins". A new account takes `full_name` from the IdP's display name; later sign-ins update it only with `oauth_sync_profile` on, and never clear it. Google's display name comes from the People API `names` field (the `profile` scope already requested). The account's email never changes on sign-in.

## Importing users from another system

`users` stores passwords through fastapi-users' default `PasswordHelper`, so you can import `hashed_password` values from another system and users keep their existing passwords (no reset needed). Accepted formats:
Expand Down
15 changes: 15 additions & 0 deletions docs/superpowers/plans/2026-11-11-oauth-profile-trusted-domains.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Plan: OAuth identity profile + trusted email domains (#877, #878)

Design: `docs/superpowers/specs/2026-11-11-oauth-profile-trusted-domains-design.md`. Sequential.

1. `users/oauth/identity.py`: `OAuthIdentity`, `normalize_domain`, `email_on_domains`. Unit tests.
2. Settings (`users/core/oauth_settings.py`): `oauth_trusted_email_domains` (validated, normalised),
`oauth_sync_profile`; warning when Microsoft domains are listed without a GUID tenant.
3. Providers return `OAuthIdentity` with subject/username/display_name/extra; generic providers apply
their trusted domains; Microsoft chooses `email` → `upn`/`preferred_username` on a listed domain and
needs the member checks. Update provider/flow tests.
4. `OAuthAccount` columns + migration (`--head users@head`); `users/oauth/profile.py` writes the
profile and `last_sign_in_at` after `oauth_callback`, sets/syncs `full_name`. Flow tests.
5. Admin Edit page: `linked_sign_ins` prop (`admin/queries.py`), `LinkedSignInsCard.tsx`, en.json keys,
gen-i18n; Vitest.
6. Docs (README, docs/modules/users.md), CHANGELOG; `make lint`, `make doctor`, users tests.
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# OAuth identity profile and trusted email domains (#877, #878)

## Goal & scope

**#877.** An OAuth sign-in keeps only `oauth_name`, `account_id`,
`account_email` and tokens. Store the IdP's profile so administrators can see
which identity an account belongs to and a provider that changes its key has
something to migrate from, and use the IdP's name for the account.

**#878.** Email trust is all-or-nothing per provider. Let an operator trust
addresses on domains their organisation owns, per provider, and nothing else.

Both change what a provider returns from `get_identity`, so they ship together.
Out of scope: changing the account email from the IdP (unique-email
collisions), #879's local IdP.

## Approach

`OAuthProvider.get_identity` returns an `OAuthIdentity` (frozen dataclass)
instead of a 3-tuple: `account_id`, `email`, `email_verified`, `subject`,
`username`, `display_name`, `extra` (small dict of provider-specific ids). The
callback applies trusted domains to it, runs the existing find-or-create, then
writes the profile onto the linked `OAuthAccount`.

Rejected: a separate `users_oauth_identity` table (the link row already is one
per identity), and a single global domain list (a domain trusted for Microsoft
must not become trusted for GitHub).

## Design

### Profile (#877)

- `OAuthAccount` gains nullable `subject` (320), `username` (320),
`display_name` (320), `extra` (JSON), `last_sign_in_at` (`AwareDateTime`).
One migration on the users trunk (`--head users@head`); no backfill.
- Each provider fills the profile from what it already fetches:
OIDC: `sub`, `preferred_username`, `name`; Google: `resourceName`, primary
address, `names[0].displayName`; GitHub: `id`, `login`, `name`; Microsoft:
`sub`, `upn`/`preferred_username`, `name`, `extra = {oid, tid}`.
- After `oauth_callback`, the callback updates the link row (same request
session, committed by the middleware) and stamps `last_sign_in_at`.
- `User.full_name`: set from `display_name` when the callback creates the
account; on later sign-ins only when the new `oauth_sync_profile` setting is
on (default off), and never to an empty value. The email is never changed.
- Admin **Edit user** page: a "Linked sign-ins" section listing provider,
username, subject and last sign-in per link (read-only). New `en.json` keys;
`make gen-i18n` and `make gen-api-types`.

### Trusted email domains (#878)

- `oauth_trusted_email_domains: dict[str, list[str]] = {}`, e.g.
`{"microsoft": ["iiasa.ac.at"]}`; keys validated against the provider names,
domains lowercased and IDNA-normalised, no wildcards.
- The email becomes verified only when its domain is listed **exactly** for
that provider (no subdomains) **and** the provider's own identity checks
pass. For Microsoft that means a GUID tenant equal to `tid`, no foreign
`idp`, no `#EXT#` (the #873 member checks without requiring the UPN trust
flag); for Microsoft the address is the `email` claim on a listed domain,
else `upn`/`preferred_username` on a listed domain. Other providers: the
address they returned.
- A domain listed for Microsoft while the tenant is not a GUID logs
`users.oauth.trusted_domains_ignored` and has no effect.

## Decisions made

- One PR for both issues (shared `OAuthIdentity`).
- `oauth_sync_profile` default off; `full_name` only, never the email.
- A listed domain is the operator's statement, so for Google, GitHub and OIDC
it makes the returned address verified even when the provider gave no
proof; Microsoft additionally needs the member checks, because its claims
are editable by the tenant.
- `extra` is limited to Microsoft's `oid`/`tid` for now.

## Testing

- Unit: each provider's `OAuthIdentity`; domain matching (case, IDNA,
subdomain refused, other provider's list ignored); Microsoft email choice.
- Flow: profile columns written on create and on later sign-in;
`last_sign_in_at` stamped; `full_name` set on create, synced only with the
setting; a listed domain links a verified local account; a guest on a
listed domain does not.
- Migration: `make doctor`, `alembic check` (CI), Postgres round trip (CI).
- Admin page: Vitest for the "Linked sign-ins" section; a browser check of the
Edit page with a seeded link.

## Risks

- `oauth_callback` (fastapi-users) owns the link-row write; the profile update
runs after it in the same session. If a future fastapi-users version changes
that, the update still works (it looks the row up by provider and account id).
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
"""users: store the IdP profile on the OAuth link (#877)

Revision ID: e480d7dd348f
Revises: f6c2d4e8b109
Create Date: 2026-11-11 20:53:38.720371
"""

from collections.abc import Sequence

import sqlalchemy as sa
from alembic import op
from simple_module_db.types import AwareDateTime

# revision identifiers, used by Alembic.
revision: str = "e480d7dd348f"
down_revision: str | None = "f6c2d4e8b109"
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None


def upgrade() -> None:
op.add_column("users_oauth_account", sa.Column("subject", sa.String(length=320), nullable=True))
op.add_column(
"users_oauth_account", sa.Column("username", sa.String(length=320), nullable=True)
)
op.add_column(
"users_oauth_account", sa.Column("display_name", sa.String(length=320), nullable=True)
)
op.add_column("users_oauth_account", sa.Column("extra", sa.JSON(), nullable=True))
op.add_column(
"users_oauth_account",
sa.Column("last_sign_in_at", AwareDateTime(), nullable=True),
)


def downgrade() -> None:
op.drop_column("users_oauth_account", "last_sign_in_at")
op.drop_column("users_oauth_account", "extra")
op.drop_column("users_oauth_account", "display_name")
op.drop_column("users_oauth_account", "username")
op.drop_column("users_oauth_account", "subject")
4 changes: 3 additions & 1 deletion host/tests/test_migration_graph.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@
"e731a1b2c3d4": "users", # unique lower(email) (#731)
"e805a1b2c3d4": "users", # browser session retirement
"f6c2d4e8b109": "file_storage", # tenant browse index
"e480d7dd348f": "users", # OAuth link profile (#877)
"51b2058d8afd": "api_tokens",
"168a2882f443": "keycloak",
"f6a3b9d2e8c4": "keycloak",
Expand All @@ -73,7 +74,7 @@
# head revision -> module owning the tables it creates or alters.
_HEADS = {
"b8d4f2a6c901": "audit_log",
"f6c2d4e8b109": "file_storage", # also carries ``api_tokens``, ``background_tasks``, ``users``
"e480d7dd348f": "users", # also carries ``api_tokens``, ``background_tasks``, ``file_storage``
"f1a9c3d7b2e4": "tenants",
"f6a3b9d2e8c4": "keycloak",
"c9d2e4f6a810": "oidc",
Expand Down Expand Up @@ -124,6 +125,7 @@
"e805a1b2c3d4": "api_tokens",
"c5d8e2f1a903": "api_tokens",
"f6c2d4e8b109": "api_tokens",
"e480d7dd348f": "api_tokens",
"a626b1c8d023": "api_tokens", # also inherits ``background_tasks``
"51b2058d8afd": "api_tokens", # ancestors of a labelled revision inherit its label too
}
Expand Down
7 changes: 7 additions & 0 deletions modules/users/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,13 @@ when they proved the email, while local registration keeps following
with signup open too (never the self-signup `user` role); blank (the default)
means none until an admin grants one, and `admin` is refused.

**Trusted email domains.** `oauth_trusted_email_domains` (e.g.
`{"microsoft": ["iiasa.ac.at"]}`) makes addresses on the listed domains count
as verified for that provider: `microsoft` (a member of a pinned tenant GUID)
and `oidc` only. `oauth_sync_profile` updates `full_name` from the IdP on every
sign-in; each link stores the IdP's subject, username and last sign-in, shown
on the admin Edit user page.

Each provider's callback URL is `<base-url>/api/users/auth/<provider>/callback`
(`google`, `github`, `microsoft`, `oidc`).

Expand Down
Loading