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: 1 addition & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,10 @@ All notable changes to this project are documented in this file. The format is b

### Added

- `users`: `oauth_microsoft_discovery_url` points Microsoft sign-in at a local IdP through its discovery document, honoured only when `SM_ENVIRONMENT` is explicitly development or testing (unset does not count; anywhere else it is ignored and `users.oauth.microsoft_discovery_ignored` is logged). `docs/examples/keycloak-entra-realm.json` is a Keycloak realm with Entra-shaped claims (`tid`, `oid`, `upn`) for clicking through the flow before an Entra app exists. `simple_module_test` gains `OidcTestIssuer` and the `oidc_test_issuer` fixture (RSA key, JWKS, discovery document, `sign(claims)`) for testing an OpenID Connect sign-in without an IdP (#879).
- `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).

### Changed
Expand Down
85 changes: 85 additions & 0 deletions docs/examples/keycloak-entra-realm.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
{
"realm": "smpy-entra",
"enabled": true,
"sslRequired": "none",
"clients": [
{
"clientId": "smpy-microsoft",
"name": "simple_module Microsoft sign-in (development)",
"enabled": true,
"protocol": "openid-connect",
"publicClient": false,
"secret": "dev-only-secret",
"standardFlowEnabled": true,
"directAccessGrantsEnabled": false,
"redirectUris": [
"http://localhost:8000/api/users/auth/microsoft/callback",
"http://127.0.0.1:8000/api/users/auth/microsoft/callback"
],
"webOrigins": [
"+"
],
"attributes": {
"pkce.code.challenge.method": "S256"
},
"protocolMappers": [
{
"name": "tid",
"protocol": "openid-connect",
"protocolMapper": "oidc-hardcoded-claim-mapper",
"config": {
"claim.name": "tid",
"claim.value": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b",
"jsonType.label": "String",
"id.token.claim": "true",
"access.token.claim": "false",
"userinfo.token.claim": "false"
}
},
{
"name": "oid",
"protocol": "openid-connect",
"protocolMapper": "oidc-usermodel-property-mapper",
"config": {
"user.attribute": "id",
"claim.name": "oid",
"jsonType.label": "String",
"id.token.claim": "true",
"access.token.claim": "false",
"userinfo.token.claim": "false"
}
},
{
"name": "upn",
"protocol": "openid-connect",
"protocolMapper": "oidc-usermodel-property-mapper",
"config": {
"user.attribute": "email",
"claim.name": "upn",
"jsonType.label": "String",
"id.token.claim": "true",
"access.token.claim": "false",
"userinfo.token.claim": "false"
}
}
]
}
],
"users": [
{
"username": "jane",
"enabled": true,
"email": "jane@corp.example",
"emailVerified": true,
"firstName": "Jane",
"lastName": "Doe",
"credentials": [
{
"type": "password",
"value": "jane",
"temporary": false
}
]
}
]
}
13 changes: 13 additions & 0 deletions docs/modules/users.md
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,7 @@ Everything else is DB-backed (initial values are pydantic defaults; edit under U
| `oauth_github_client_id` / `oauth_github_client_secret` | `""` — GitHub OAuth |
| `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_microsoft_discovery_url` | `""` — development/testing only: take Microsoft's endpoints from this discovery document, for a local IdP (see [Microsoft sign-in without Entra](#microsoft-sign-in-without-entra-development)) |
| `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 |
Expand Down Expand Up @@ -542,6 +543,18 @@ Microsoft uses OpenID Connect on the tenant's v2.0 endpoints (`https://login.mic
- The linked account id is the value Graph `/me` returned before: the `oid` claim for work and school accounts, and for a personal account the 16 hex digits `oid` carries after its zero prefix. Links made before this change keep matching.
- The email is the optional `upn` claim when the app registration adds it, else `preferred_username`: the UPN for a tenant member, the home address for a guest. With email as an alternate login ID turned on, `preferred_username` is the address the user typed, so add the `upn` optional claim (Token configuration → Add optional claim → ID → `upn`) to keep matching invites by UPN. The optional `email` claim is not used, and a phone-number username counts as no email.

### Microsoft sign-in without Entra (development)

To click through Microsoft sign-in before an Entra app exists, point the provider at a local IdP that emits Entra-shaped claims. Set `oauth_microsoft_discovery_url` to its discovery document. The setting is honoured only when `SM_ENVIRONMENT` is explicitly set to `development` or `testing` (an unset variable does not count; `make dev` does not set it, so export `SM_ENVIRONMENT=development` or keep it in `.env`, as `.env.example` does); anywhere else it is ignored and the settings load logs `users.oauth.microsoft_discovery_ignored`, so it can never send production sign-ins to another IdP. The document is fetched on the first sign-in, not at boot; its URL and every endpoint in it must be HTTPS or plain HTTP to a loopback address. Every ID-token rule above still applies, with the document's `issuer` in place of Entra's.

A Keycloak realm for this ships as `docs/examples/keycloak-entra-realm.json`. It holds a confidential client `smpy-microsoft` (secret `dev-only-secret`, PKCE S256, callback `http://localhost:8000/api/users/auth/microsoft/callback`) whose ID tokens carry a fixed `tid`, the Keycloak user id as `oid` and the email as `upn`, and a user `jane` / `jane` (`jane@corp.example`). With the shared dev-services Keycloak (`docker compose --profile identity up -d keycloak` in `../dev-services`, port 8081):

1. Import the realm: in the admin console (`admin` / `admin`) use **Create realm → Browse** and pick the file, or `POST` it to `/admin/realms`.
2. Configure the Users settings: `oauth_microsoft_client_id = smpy-microsoft`, `oauth_microsoft_client_secret = dev-only-secret`, `oauth_microsoft_tenant = 6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b` (the realm's `tid`) and `oauth_microsoft_discovery_url = http://127.0.0.1:8081/realms/smpy-entra/.well-known/openid-configuration`.
3. Run the app on port 8000 and sign in with **Microsoft** as `jane`. On another port, add its callback URL to the client's redirect URIs.

Add `oauth_microsoft_trust_tenant_upn`, `oauth_trusted_email_domains = {"microsoft": ["corp.example"]}` or `oauth_signup_providers = ["microsoft"]` to try the policies above.

### Signing in pre-approved staff with Microsoft

Microsoft email claims are tenant-controlled, so by default a Microsoft sign-in never proves an email ("nOAuth"). That keeps `common`/`organizations` safe, but it also means that with self-signup closed nobody can sign in with Microsoft: a verified local account or pending invite with the same address is refused with `OAUTH_USER_ALREADY_EXISTS`.
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/env-vars.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ This is the full reference. See [Configuration](/guide/configuration) for a narr
| Variable | Default | Notes |
|---|---|---|
| `SM_DATABASE_URL` | `sqlite+aiosqlite:///./app.db` | **Required in production.** Async URL: `postgresql+asyncpg://user:pw@host:5432/db` or `sqlite+aiosqlite:///./app.db`. Relative sqlite paths resolve against the project root (the `.env` location), not the process cwd — CLI tools run from `host/` hit the same file as the app. |
| `SM_ENVIRONMENT` | `development` | `development` and `testing` are the only non-prod values (placeholder-secret check is skipped for both). Any value other than `development` triggers strict module discovery. |
| `SM_ENVIRONMENT` | `development` | `development` and `testing` are the only non-prod values (placeholder-secret check is skipped for both). Any value other than `development` triggers strict module discovery. Unlike that default, `users` honours `oauth_microsoft_discovery_url` only when the variable is explicitly `development` or `testing` (unset does not count). |
| `SM_SECRET_KEY` | `change-me-in-production` | **Must** be overridden in production — session cookie signing key. |
| `SM_DEBUG` | `false` | Enables debug mode (tracebacks in HTTP responses). |
| `SM_LOG_LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/`ERROR`. |
Expand Down
11 changes: 11 additions & 0 deletions docs/superpowers/plans/2026-11-11-microsoft-dev-idp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Plan: Microsoft dev discovery override + test issuer (#879)

Design: `docs/superpowers/specs/2026-11-11-microsoft-dev-idp-design.md`. Sequential.

1. `simple_module_test.oidc_issuer`: `OidcTestIssuer` + `oidc_test_issuer` fixture; deps `PyJWT[crypto]`,
`cryptography`; tests in `framework/testing/tests/test_testing_oidc_issuer.py`.
2. `users/oauth/microsoft_dev.py` `MicrosoftDevOidc` (lazy async discovery, document issuer);
`oauth_microsoft_discovery_url` + `microsoft_discovery_url()` (dev/testing only, warning otherwise);
`build_clients` picks it. Tests: `tests/oauth/devidp/` full round trip via `httpx_mock`.
3. `docs/examples/keycloak-entra-realm.json`; docs (users.md, README, testing/fixtures.md), CHANGELOG;
manual run against the shared dev Keycloak.
52 changes: 52 additions & 0 deletions docs/superpowers/specs/2026-11-11-microsoft-dev-idp-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# Development discovery override and test fixtures for Microsoft sign-in (#879)

## Goal & scope

Since #876 the Microsoft provider is OIDC, but its endpoints are fixed to
`login.microsoftonline.com`, so nobody can click through Microsoft sign-in
locally or in CI without a real Entra tenant. Add a development-only discovery
override, a local Keycloak recipe that emits Entra-shaped claims, and reusable
test helpers for signed ID tokens.

Out of scope: production use of another IdP through the Microsoft provider
(the generic `oidc` provider is for that).

## Approach

- `oauth_microsoft_discovery_url: str = ""`. Honoured **only** when
`SM_ENVIRONMENT` is development or testing; otherwise ignored, with a
`users.oauth.microsoft_discovery_ignored` warning (not a boot failure, so an
admin edit cannot take the site down). Blank keeps today's fixed Entra
endpoints.
- With an override, `MicrosoftOidc` reads `authorization_endpoint`,
`token_endpoint`, `jwks_uri` and `issuer` from the discovery document,
fetched asynchronously on first use and cached (no fetch at boot or settings
reload), validated with the `oidc` module's rules (HTTPS outside
development, concrete issuer). The ID token's issuer must then equal the
document's issuer exactly; the `tid` rules stay (a GUID tenant still requires
a matching `tid`, so the Keycloak realm emits one).
- Test helpers in `simple_module_test` (framework, so no `users` import):
`OidcTestIssuer` with an RSA key, `jwks()`, `discovery(base_url)` and
`sign(claims)`, plus a `oidc_test_issuer` fixture. The users module's own
helper moves onto it.
- Recipe: `docs/modules/users.md` § "Microsoft sign-in without Entra" and a
realm export `docs/examples/keycloak-entra-realm.json` with protocol mappers
for `oid`, `tid`, `preferred_username`, `email`, `name`.

Rejected: a bundled fake IdP server in `simple_module_test` (more code to keep
than a realm file plus in-process fixtures); refusing boot in production
(an admin settings edit would then be able to stop the site).

## Testing

- Settings: override honoured in development/testing, ignored with a warning
in production.
- Flow: with the override and `pytest-httpx` serving discovery, JWKS and the
token endpoint from `OidcTestIssuer`, a full `/login` → `/callback` round trip
signs in; a token whose issuer differs from the document's is refused.
- Manual: the Keycloak recipe against `make dev` (documented, run once here).

## Risks

- Keycloak's `tid`/`oid` must be GUID-shaped; the realm sets them as hardcoded
or user-attribute mappers with GUID values.
3 changes: 3 additions & 0 deletions docs/testing/fixtures.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ The `simple_module_test` plugin provides app-level fixtures that every test dire
| `client` | function | `httpx.AsyncClient` | Anonymous HTTP calls to the app. |
| `authenticated_client` | function | `httpx.AsyncClient` | Admin-scoped HTTP calls — carries a signed session cookie. |
| `captured_mail` | function | `CapturedMail` | Asserting on outgoing mail: installs a recording sender (`.messages`, `.to(address)`) as the process mail sender. |
| `oidc_test_issuer` | function | `OidcTestIssuer` | Testing an OpenID Connect sign-in without an IdP: an RSA signing key with `jwks()`, `discovery()` and `sign(claims)`. |

All fixtures are **function-scoped** — each test gets its own. The SQLite database is in-memory; tearing down and re-creating is cheap. The first schema each process builds is kept as a template and copied into every later empty in-memory database with SQLite's backup API, so `CREATE TABLE` runs once per worker rather than once per test (`simple_module_test._sqlite_template`). A database that already has tables is never overwritten. Those engines also share one SQLAlchemy dialect and compiled-statement cache (`simple_module_test._compile_cache`), so SQL compiled in one test is reused by the next; the cache key carries no data, only statement structure. The patch applies to the whole pytest process; set `SM_TEST_SEPARATE_COMPILE_CACHES=1` to skip it.

Expand Down Expand Up @@ -212,6 +213,8 @@ async def test_webhook_delivery(httpx_mock, db_session):
assert httpx_mock.get_request().content == b'{"id": 1}'
```

For an OpenID Connect sign-in, serve an `OidcTestIssuer` (from `simple_module_test`, or the `oidc_test_issuer` fixture) through `httpx_mock`: its discovery document, its JWKS and a token response carrying `issuer.sign({...})`. `sign` fills `iss`, `iat` and `exp`; a claim set to `None` is left out. `modules/users/tests/oauth/devidp/` drives a whole Microsoft sign-in this way.

## Parametrization

Standard pytest:
Expand Down
1 change: 1 addition & 0 deletions framework/testing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ All fixtures below are auto-registered via the `pytest11` entry point — instal
- `client` — an `httpx.AsyncClient` bound to the test app.
- `authenticated_client` — same but with an admin user seeded and a forged session cookie attached. **Requires the `users` module** to be installed (it seeds the admin via `users.core.bootstrap`); apps scaffolded by `smpy` include it.
- `tenant_client` — factory: `async with tenant_client("member") as (client, tenant_id, user_id)` signs in a fresh user who is an `owner` / `admin` / `member` (default `owner`) of a new tenant — or of `tenant_id=` when given — with that tenant active. **Requires the `users` and `tenants` modules.**
- `oidc_test_issuer` — an in-process OpenID Connect issuer (`OidcTestIssuer`): an RSA signing key with `jwks()`, `discovery()` and `sign(claims)`, for testing an OIDC sign-in through `httpx_mock` without an IdP.

## Usage

Expand Down
3 changes: 3 additions & 0 deletions framework/testing/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,9 @@ classifiers = [
dependencies = [
"fastapi>=0.140,<0.163",
"httpx>=0.27,<0.29",
# OidcTestIssuer: sign ID tokens and publish a JWKS (#879).
"cryptography>=42",
"PyJWT[crypto]>=2.8,<3",
"pytest>=8.0,<10",
"pytest-asyncio>=0.24,<2",
"simple_module_core==0.0.45",
Expand Down
6 changes: 5 additions & 1 deletion framework/testing/simple_module_test/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,16 @@
module to be installed — it seeds an admin via ``users.core.bootstrap``.
``tenant_client`` (``users`` + ``tenants``) is a factory yielding a client signed
in as an ``owner``/``admin``/``member`` of a real tenant — see
``simple_module_test.tenant_client``.
``simple_module_test.tenant_client``. ``oidc_test_issuer`` is an in-process
OpenID Connect issuer (:class:`OidcTestIssuer`: signing key, JWKS, discovery
document and ``sign(claims)``) for testing an OIDC sign-in without an IdP.
"""

from simple_module_test.app_factory import build_test_app
from simple_module_test.fake_events import FakeEventBus, RecordedEvent
from simple_module_test.inertia import inertia_headers
from simple_module_test.inertia_page import InertiaPage, inertia_page
from simple_module_test.oidc_issuer import OidcTestIssuer
from simple_module_test.routes import effective_route_paths
from simple_module_test.session_cookie import forge_session_cookie
from simple_module_test.tenant_client import TenantClient
Expand All @@ -40,6 +43,7 @@
__all__ = [
"FakeEventBus",
"InertiaPage",
"OidcTestIssuer",
"RecordedEvent",
"TenantClient",
"build_test_app",
Expand Down
Loading
Loading