From 373397c01d634e2b0eb45c37b5e128df2b7b0ab6 Mon Sep 17 00:00:00 2001 From: Anto Subash Date: Wed, 11 Nov 2026 20:44:28 +0100 Subject: [PATCH 1/6] docs: microsoft-dev-idp design (#879) Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4 --- .../2026-11-11-microsoft-dev-idp-design.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 docs/superpowers/specs/2026-11-11-microsoft-dev-idp-design.md diff --git a/docs/superpowers/specs/2026-11-11-microsoft-dev-idp-design.md b/docs/superpowers/specs/2026-11-11-microsoft-dev-idp-design.md new file mode 100644 index 00000000..e3bf327b --- /dev/null +++ b/docs/superpowers/specs/2026-11-11-microsoft-dev-idp-design.md @@ -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. From 7f25aafcfcf1191013188aad40ccb30a67bfd6ad Mon Sep 17 00:00:00 2001 From: Anto Subash Date: Wed, 11 Nov 2026 21:32:17 +0100 Subject: [PATCH 2/6] feat(testing): OidcTestIssuer and oidc_test_issuer fixture (#879) An in-process OpenID Connect issuer (RSA key, JWKS, discovery document, sign(claims)) so modules can test an OIDC sign-in without an IdP. Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4 --- framework/testing/pyproject.toml | 3 + .../testing/simple_module_test/__init__.py | 6 +- .../testing/simple_module_test/oidc_issuer.py | 77 +++++++++++++++++++ .../testing/simple_module_test/plugin.py | 1 + .../testing/tests/test_testing_oidc_issuer.py | 28 +++++++ uv.lock | 4 + 6 files changed, 118 insertions(+), 1 deletion(-) create mode 100644 framework/testing/simple_module_test/oidc_issuer.py create mode 100644 framework/testing/tests/test_testing_oidc_issuer.py diff --git a/framework/testing/pyproject.toml b/framework/testing/pyproject.toml index 277d646d..1b58f496 100644 --- a/framework/testing/pyproject.toml +++ b/framework/testing/pyproject.toml @@ -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", diff --git a/framework/testing/simple_module_test/__init__.py b/framework/testing/simple_module_test/__init__.py index af1db74d..d9926351 100644 --- a/framework/testing/simple_module_test/__init__.py +++ b/framework/testing/simple_module_test/__init__.py @@ -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 @@ -40,6 +43,7 @@ __all__ = [ "FakeEventBus", "InertiaPage", + "OidcTestIssuer", "RecordedEvent", "TenantClient", "build_test_app", diff --git a/framework/testing/simple_module_test/oidc_issuer.py b/framework/testing/simple_module_test/oidc_issuer.py new file mode 100644 index 00000000..0482358b --- /dev/null +++ b/framework/testing/simple_module_test/oidc_issuer.py @@ -0,0 +1,77 @@ +"""An in-process OpenID Connect issuer for tests: a signing key, JWKS and discovery. + +Lets a module test an OIDC sign-in end to end without a real IdP (#879):: + + issuer = OidcTestIssuer("https://idp.test/tenant/v2.0") + httpx_mock.add_response(url=issuer.discovery_url, json=issuer.discovery()) + httpx_mock.add_response(url=issuer.jwks_url, json=issuer.jwks()) + id_token = issuer.sign({"aud": "client", "sub": "user-1", "nonce": nonce}) + +``sign`` fills ``iss``, ``iat`` and ``exp``; pass ``None`` for a claim to drop it. +""" + +from __future__ import annotations + +import json +import time +from typing import Any + +import jwt +import pytest +from cryptography.hazmat.primitives.asymmetric import rsa +from jwt.algorithms import RSAAlgorithm + + +class OidcTestIssuer: + """A fake IdP whose endpoints live under ``issuer`` and whose tokens verify.""" + + def __init__(self, issuer: str = "https://idp.test/realms/test", kid: str = "test-key") -> None: + self.issuer = issuer.rstrip("/") + self.kid = kid + self._key = rsa.generate_private_key(public_exponent=65537, key_size=2048) + + @property + def discovery_url(self) -> str: + return f"{self.issuer}/.well-known/openid-configuration" + + @property + def jwks_url(self) -> str: + return f"{self.issuer}/keys" + + @property + def authorization_endpoint(self) -> str: + return f"{self.issuer}/authorize" + + @property + def token_endpoint(self) -> str: + return f"{self.issuer}/token" + + def discovery(self) -> dict[str, Any]: + """The discovery document for this issuer.""" + return { + "issuer": self.issuer, + "authorization_endpoint": self.authorization_endpoint, + "token_endpoint": self.token_endpoint, + "jwks_uri": self.jwks_url, + "response_types_supported": ["code"], + "code_challenge_methods_supported": ["S256"], + "id_token_signing_alg_values_supported": ["RS256"], + } + + def jwks(self) -> dict[str, Any]: + """The public signing key as a JWKS document.""" + jwk = json.loads(RSAAlgorithm.to_jwk(self._key.public_key())) + return {"keys": [{**jwk, "kid": self.kid, "use": "sig", "alg": "RS256"}]} + + def sign(self, claims: dict[str, Any], *, lifetime: int = 300) -> str: + """An RS256 ID token from this issuer; ``None`` values drop a claim.""" + now = int(time.time()) + payload = {"iss": self.issuer, "iat": now, "exp": now + lifetime, **claims} + payload = {k: v for k, v in payload.items() if v is not None} + return jwt.encode(payload, self._key, algorithm="RS256", headers={"kid": self.kid}) + + +@pytest.fixture +def oidc_test_issuer() -> OidcTestIssuer: + """A fresh :class:`OidcTestIssuer` per test.""" + return OidcTestIssuer() diff --git a/framework/testing/simple_module_test/plugin.py b/framework/testing/simple_module_test/plugin.py index 834ccfa8..7bef10bf 100644 --- a/framework/testing/simple_module_test/plugin.py +++ b/framework/testing/simple_module_test/plugin.py @@ -35,6 +35,7 @@ setup_pending_app, ) from simple_module_test.mail import captured_mail # noqa: F401 +from simple_module_test.oidc_issuer import oidc_test_issuer # noqa: F401 from simple_module_test.process_state import _reset_process_state # noqa: F401 from simple_module_test.redis_server import redis_server # noqa: F401 from simple_module_test.tenant_client import tenant_client # noqa: F401 diff --git a/framework/testing/tests/test_testing_oidc_issuer.py b/framework/testing/tests/test_testing_oidc_issuer.py new file mode 100644 index 00000000..0062c68d --- /dev/null +++ b/framework/testing/tests/test_testing_oidc_issuer.py @@ -0,0 +1,28 @@ +"""``OidcTestIssuer`` issues tokens its own JWKS verifies (#879).""" + +import jwt +from jwt.algorithms import RSAAlgorithm +from simple_module_test import OidcTestIssuer + + +def test_signed_tokens_verify_against_the_published_jwks(oidc_test_issuer): + token = oidc_test_issuer.sign({"aud": "client", "sub": "user-1", "nonce": "n"}) + key = RSAAlgorithm.from_jwk(oidc_test_issuer.jwks()["keys"][0]) + claims = jwt.decode( + token, key, algorithms=["RS256"], audience="client", issuer=oidc_test_issuer.issuer + ) + assert (claims["sub"], claims["nonce"]) == ("user-1", "n") + assert jwt.get_unverified_header(token)["kid"] == oidc_test_issuer.kid + + +def test_discovery_points_at_the_issuer_endpoints(): + issuer = OidcTestIssuer("https://idp.test/tenant/v2.0/") + doc = issuer.discovery() + assert doc["issuer"] == "https://idp.test/tenant/v2.0" + assert doc["jwks_uri"] == issuer.jwks_url + assert issuer.discovery_url.endswith("/.well-known/openid-configuration") + + +def test_none_drops_a_claim(oidc_test_issuer): + token = oidc_test_issuer.sign({"sub": "x", "exp": None}) + assert "exp" not in jwt.decode(token, options={"verify_signature": False}) diff --git a/uv.lock b/uv.lock index f6f38feb..03851e2d 100644 --- a/uv.lock +++ b/uv.lock @@ -3662,8 +3662,10 @@ name = "simple-module-test" version = "0.0.45" source = { editable = "framework/testing" } dependencies = [ + { name = "cryptography" }, { name = "fastapi" }, { name = "httpx" }, + { name = "pyjwt", extra = ["crypto"] }, { name = "pytest" }, { name = "pytest-asyncio" }, { name = "simple-module-core" }, @@ -3675,8 +3677,10 @@ dependencies = [ [package.metadata] requires-dist = [ + { name = "cryptography", specifier = ">=42" }, { name = "fastapi", specifier = ">=0.140,<0.163" }, { name = "httpx", specifier = ">=0.27,<0.29" }, + { name = "pyjwt", extras = ["crypto"], specifier = ">=2.8,<3" }, { name = "pytest", specifier = ">=8.0,<10" }, { name = "pytest-asyncio", specifier = ">=0.24,<2" }, { name = "simple-module-core", editable = "framework/core" }, From 1d2d36bdc81043ce34e595722abfc696516c84ef Mon Sep 17 00:00:00 2001 From: Anto Subash Date: Wed, 11 Nov 2026 21:40:47 +0100 Subject: [PATCH 3/6] feat(users): development discovery override for Microsoft sign-in; Keycloak recipe (#879) oauth_microsoft_discovery_url (development/testing only) builds a MicrosoftDevOidc that reads endpoints, JWKS and issuer from a discovery document on first use. docs/examples/keycloak-entra-realm.json emits Entra-shaped claims; verified once against the shared dev Keycloak. Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4 --- CHANGELOG.md | 2 + docs/examples/keycloak-entra-realm.json | 85 ++++++++++++++ docs/modules/users.md | 13 +++ docs/testing/fixtures.md | 3 + modules/users/README.md | 5 + .../test_users_oauth_microsoft_dev_idp.py | 108 ++++++++++++++++++ modules/users/users/core/oauth_settings.py | 27 +++++ modules/users/users/oauth/microsoft_dev.py | 83 ++++++++++++++ modules/users/users/oauth/providers.py | 28 +++-- 9 files changed, 347 insertions(+), 7 deletions(-) create mode 100644 docs/examples/keycloak-entra-realm.json create mode 100644 modules/users/tests/oauth/devidp/test_users_oauth_microsoft_dev_idp.py create mode 100644 modules/users/users/oauth/microsoft_dev.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b362fac..a3f480dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,8 @@ 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 development or testing (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). diff --git a/docs/examples/keycloak-entra-realm.json b/docs/examples/keycloak-entra-realm.json new file mode 100644 index 00000000..9f93ce8a --- /dev/null +++ b/docs/examples/keycloak-entra-realm.json @@ -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 + } + ] + } + ] +} diff --git a/docs/modules/users.md b/docs/modules/users.md index a4e8c0a9..63306e24 100644 --- a/docs/modules/users.md +++ b/docs/modules/users.md @@ -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 | @@ -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 `development` or `testing`; 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. 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`. diff --git a/docs/testing/fixtures.md b/docs/testing/fixtures.md index e539b7b5..34a3799f 100644 --- a/docs/testing/fixtures.md +++ b/docs/testing/fixtures.md @@ -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. @@ -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: diff --git a/modules/users/README.md b/modules/users/README.md index 567d76c7..e2a32ece 100644 --- a/modules/users/README.md +++ b/modules/users/README.md @@ -103,6 +103,11 @@ from the validated ID token. Configure under the **Microsoft OAuth** group: It trusts the tenant's admins: whoever can set a member's UPN can sign in as the local account with that address. +**Microsoft sign-in without Entra.** In development and testing only, +`oauth_microsoft_discovery_url` points the Microsoft provider at a local IdP; +`docs/examples/keycloak-entra-realm.json` is a Keycloak realm that emits +Entra-shaped claims (see the users module docs). + **Provisioning through SSO with signup closed.** `oauth_signup_providers` (e.g. `["microsoft"]`) lets those providers create an account on first sign-in when they proved the email, while local registration keeps following diff --git a/modules/users/tests/oauth/devidp/test_users_oauth_microsoft_dev_idp.py b/modules/users/tests/oauth/devidp/test_users_oauth_microsoft_dev_idp.py new file mode 100644 index 00000000..b71e3af8 --- /dev/null +++ b/modules/users/tests/oauth/devidp/test_users_oauth_microsoft_dev_idp.py @@ -0,0 +1,108 @@ +"""Microsoft sign-in against a local IdP through the discovery override (#879).""" + +from __future__ import annotations + +import logging +from urllib.parse import parse_qs, urlparse + +import pytest +from _users_oauth_support import find_user, set_allow_signup +from simple_module_test import OidcTestIssuer +from users.core.settings import UsersSettings +from users.oauth import OAuthProvider +from users.oauth.microsoft_dev import MicrosoftDevOidc +from users.oauth.providers import build_client_map + +_TENANT = "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b" +_OID = "1b2c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d" +_CLIENT = "ms-client" + + +def _settings(**update) -> UsersSettings: + return UsersSettings( + oauth_microsoft_client_id=_CLIENT, + oauth_microsoft_client_secret="secret", + oauth_microsoft_tenant=_TENANT, + **update, + ) + + +@pytest.mark.parametrize("environment", ["development", "testing"]) +def test_the_override_applies_in_development_and_tests(monkeypatch, environment): + monkeypatch.setenv("SM_ENVIRONMENT", environment) + settings = _settings(oauth_microsoft_discovery_url="http://localhost:8080/.well-known/x") + assert isinstance(build_client_map(settings)["microsoft"].client, MicrosoftDevOidc) + + +def test_the_override_is_ignored_in_production(monkeypatch, caplog): + monkeypatch.setenv("SM_ENVIRONMENT", "production") + with caplog.at_level(logging.WARNING, logger="users.settings"): + settings = _settings( + oauth_microsoft_discovery_url="http://idp.evil/.well-known/x", + reset_password_token_secret="a-real-reset-secret-for-this-test", + verification_token_secret="a-real-verify-secret-for-this-test", + ) + assert "users.oauth.microsoft_discovery_ignored" in caplog.text + client = build_client_map(settings)["microsoft"].client + assert not isinstance(client, MicrosoftDevOidc) + assert client.authorize_endpoint.startswith("https://login.microsoftonline.com/") + + +def _install(app, issuer: OidcTestIssuer) -> None: + client = MicrosoftDevOidc(_CLIENT, "secret", _TENANT, issuer.discovery_url) + app.state.users.oauth_clients["microsoft"] = OAuthProvider( + "microsoft", "Microsoft", client, trust_email=True + ) + + +async def _round_trip(client, issuer: OidcTestIssuer, httpx_mock, **claims): + httpx_mock.add_response(url=issuer.discovery_url, json=issuer.discovery()) + login = await client.get("/api/users/auth/microsoft/login", follow_redirects=False) + location = urlparse(login.headers["location"]) + query = parse_qs(location.query) + assert location.geturl().startswith(issuer.authorization_endpoint) + id_token = issuer.sign( + { + "aud": _CLIENT, + "sub": "pairwise-sub", + "tid": _TENANT, + "oid": _OID, + "preferred_username": "jane@corp.com", + "name": "Jane Doe", + "nonce": query["nonce"][0], + **claims, + } + ) + httpx_mock.add_response( + url=issuer.token_endpoint, json={"access_token": "at", "id_token": id_token} + ) + httpx_mock.add_response(url=issuer.jwks_url, json=issuer.jwks()) + return await client.get( + f"/api/users/auth/microsoft/callback?code=abc&state={query['state'][0]}", + follow_redirects=False, + ) + + +@pytest.mark.anyio +async def test_a_full_sign_in_against_a_local_issuer(users_app, anon_client, httpx_mock): + set_allow_signup(users_app, True) + issuer = OidcTestIssuer("https://idp.test/realms/entra") + _install(users_app, issuer) + + resp = await _round_trip(anon_client, issuer, httpx_mock) + + assert resp.status_code == 303 + user = await find_user(users_app, "jane@corp.com") + assert user is not None and user.is_verified and user.full_name == "Jane Doe" + + +@pytest.mark.anyio +async def test_a_token_from_another_issuer_is_refused(users_app, anon_client, httpx_mock): + set_allow_signup(users_app, True) + issuer = OidcTestIssuer("https://idp.test/realms/entra") + _install(users_app, issuer) + + resp = await _round_trip(anon_client, issuer, httpx_mock, iss="https://idp.test/realms/other") + + assert resp.json()["detail"] == "OAUTH_PROVIDER_ERROR" + assert await find_user(users_app, "jane@corp.com") is None diff --git a/modules/users/users/core/oauth_settings.py b/modules/users/users/core/oauth_settings.py index 9477678c..b2ed56d7 100644 --- a/modules/users/users/core/oauth_settings.py +++ b/modules/users/users/core/oauth_settings.py @@ -8,9 +8,11 @@ from __future__ import annotations import logging +import os import uuid from pydantic import Field, field_validator, model_validator +from simple_module_core.environments import NON_PROD_ENVIRONMENTS from simple_module_core.settings_base import DbBackedSettings from users.core.constants import ADMIN_ROLE_NAME @@ -90,6 +92,31 @@ class OAuthSettings(DbBackedSettings): default=False, json_schema_extra={"group": "Microsoft OAuth"} ) + # Development and testing only (#879): sign in with Microsoft against a + # local IdP (a Keycloak realm with Entra-shaped claims) by taking the + # endpoints, JWKS and issuer from this discovery document. Ignored, with a + # warning, in any other environment. + oauth_microsoft_discovery_url: str = Field( + default="", json_schema_extra={"group": "Microsoft OAuth"} + ) + + def microsoft_discovery_url(self) -> str: + """The discovery override if it may apply in this process, else ``""``.""" + if os.environ.get("SM_ENVIRONMENT", "development") not in NON_PROD_ENVIRONMENTS: + return "" + return self.oauth_microsoft_discovery_url.strip() + + @model_validator(mode="after") + def _warn_on_ignored_microsoft_discovery(self) -> OAuthSettings: + """A production instance must never send Microsoft sign-ins to another IdP.""" + if self.oauth_microsoft_discovery_url.strip() and not self.microsoft_discovery_url(): + logger.warning( + "users.oauth.microsoft_discovery_ignored — oauth_microsoft_discovery_url is set " + "but SM_ENVIRONMENT is not development or testing; Microsoft sign-in keeps " + "using login.microsoftonline.com." + ) + return self + @model_validator(mode="after") def _warn_on_ignored_microsoft_trust(self) -> OAuthSettings: """The UPN trust policy is inert unless one tenant is pinned by GUID.""" diff --git a/modules/users/users/oauth/microsoft_dev.py b/modules/users/users/oauth/microsoft_dev.py new file mode 100644 index 00000000..0ae49a58 --- /dev/null +++ b/modules/users/users/oauth/microsoft_dev.py @@ -0,0 +1,83 @@ +"""Microsoft sign-in against a local IdP, for development and tests only (#879). + +With ``oauth_microsoft_discovery_url`` set and ``SM_ENVIRONMENT`` development or +testing, the Microsoft provider takes its endpoints, JWKS and issuer from that +discovery document (a Keycloak realm emitting Entra-shaped claims, say) instead +of ``login.microsoftonline.com``. Every ID-token rule of :class:`MicrosoftOidc` +still applies, with the document's issuer in place of Entra's per-tenant one. +""" + +from __future__ import annotations + +import asyncio +from typing import Any, Literal + +import httpx +from auth.oidc_common.jwks import JWKSCache + +from users.oauth.microsoft import IdTokenError, MicrosoftOidc + +_REQUIRED = ("issuer", "authorization_endpoint", "token_endpoint", "jwks_uri") + + +class MicrosoftDevOidc(MicrosoftOidc): + """:class:`MicrosoftOidc` whose endpoints come from a discovery document.""" + + def __init__(self, client_id: str, client_secret: str, tenant: str, discovery_url: str) -> None: + super().__init__(client_id, client_secret, tenant) + self.discovery_url = discovery_url + self._jwks: JWKSCache | None = None + self._lock = asyncio.Lock() + + async def get_authorization_url( + self, + redirect_uri: str, + state: str | None = None, + scope: list[str] | None = None, + code_challenge: str | None = None, + code_challenge_method: Literal["plain", "S256"] | None = None, + extras_params: dict[str, Any] | None = None, + ) -> str: + await self._discover() + return await super().get_authorization_url( + redirect_uri, + state, + scope, + code_challenge, + code_challenge_method, + extras_params, + ) + + async def get_access_token( + self, code: str, redirect_uri: str, code_verifier: str | None = None + ): + await self._discover() + return await super().get_access_token(code, redirect_uri, code_verifier) + + def _cache(self, tid: str) -> JWKSCache: + if self._jwks is None: # identity() runs after get_access_token + raise IdTokenError("discovery document not loaded") + return self._jwks + + async def _discover(self) -> None: + """Fetch the document once, on first use: never at boot or settings reload.""" + if self._jwks is not None: + return + async with self._lock: + if self._jwks is not None: + return + try: + async with httpx.AsyncClient() as client: + response = await client.get(self.discovery_url, timeout=10) + response.raise_for_status() + doc = response.json() + except (httpx.HTTPError, ValueError) as exc: + raise IdTokenError(f"discovery failed: {exc}") from exc + if not isinstance(doc, dict) or not all( + isinstance(doc.get(key), str) and doc[key] for key in _REQUIRED + ): + raise IdTokenError("discovery document lacks issuer or endpoints") + self.authorize_endpoint = doc["authorization_endpoint"] + self.access_token_endpoint = doc["token_endpoint"] + self.refresh_token_endpoint = doc["token_endpoint"] + self._jwks = JWKSCache(doc["jwks_uri"], issuer=doc["issuer"], audience=self.client_id) diff --git a/modules/users/users/oauth/providers.py b/modules/users/users/oauth/providers.py index 6dbd8d00..f11563b0 100644 --- a/modules/users/users/oauth/providers.py +++ b/modules/users/users/oauth/providers.py @@ -193,17 +193,11 @@ def build_clients(settings: UsersSettings) -> list[OAuthProvider]: ) if settings.oauth_microsoft_client_id and settings.oauth_microsoft_client_secret: - from users.oauth.microsoft import MicrosoftOidc - out.append( OAuthProvider( "microsoft", "Microsoft", - MicrosoftOidc( - settings.oauth_microsoft_client_id, - settings.oauth_microsoft_client_secret, - settings.oauth_microsoft_tenant or "common", - ), + _microsoft_client(settings), trust_email=settings.oauth_microsoft_trust_tenant_upn and is_tenant_guid(settings.oauth_microsoft_tenant), ) @@ -240,6 +234,26 @@ def build_clients(settings: UsersSettings) -> list[OAuthProvider]: return [p._replace(trusted_domains=settings.trusted_domains(p.name)) for p in out] +def _microsoft_client(settings: UsersSettings) -> BaseOAuth2: + """Entra's fixed endpoints, or a discovery override in development (#879).""" + tenant = settings.oauth_microsoft_tenant or "common" + discovery_url = settings.microsoft_discovery_url() + if discovery_url: + from users.oauth.microsoft_dev import MicrosoftDevOidc + + return MicrosoftDevOidc( + settings.oauth_microsoft_client_id, + settings.oauth_microsoft_client_secret, + tenant, + discovery_url, + ) + from users.oauth.microsoft import MicrosoftOidc + + return MicrosoftOidc( + settings.oauth_microsoft_client_id, settings.oauth_microsoft_client_secret, tenant + ) + + def build_client_map(settings: UsersSettings) -> dict[str, OAuthProvider]: """Configured providers keyed by name for O(1) request-time lookup.""" return {p.name: p for p in build_clients(settings)} From 90681456826adcb0a2fbaa325cb9d56029cac2e8 Mon Sep 17 00:00:00 2001 From: Anto Subash Date: Wed, 11 Nov 2026 21:41:51 +0100 Subject: [PATCH 4/6] docs: microsoft-dev-idp plan (#879) Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4 --- .../superpowers/plans/2026-11-11-microsoft-dev-idp.md | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-11-microsoft-dev-idp.md diff --git a/docs/superpowers/plans/2026-11-11-microsoft-dev-idp.md b/docs/superpowers/plans/2026-11-11-microsoft-dev-idp.md new file mode 100644 index 00000000..84ecc6f2 --- /dev/null +++ b/docs/superpowers/plans/2026-11-11-microsoft-dev-idp.md @@ -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. From 006569a573efc33bd3c315fad16339b14d7b2e0d Mon Sep 17 00:00:00 2001 From: Anto Subash Date: Wed, 11 Nov 2026 21:46:03 +0100 Subject: [PATCH 5/6] fix: address code review findings (round 1, pass 1) The discovery override fails closed on an unset SM_ENVIRONMENT; discovery URLs must be HTTPS or loopback HTTP; a failed discovery refuses /login with OAUTH_PROVIDER_ERROR instead of a 500; one test signing key per process; README and CHANGELOG shape. Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4 --- CHANGELOG.md | 3 +- docs/modules/users.md | 2 +- framework/testing/README.md | 1 + .../testing/simple_module_test/oidc_issuer.py | 9 ++++- .../test_users_oauth_microsoft_dev_idp.py | 34 +++++++++++++++++++ modules/users/users/core/oauth_settings.py | 8 +++-- modules/users/users/oauth/api.py | 7 +++- modules/users/users/oauth/microsoft_dev.py | 16 +++++++-- 8 files changed, 70 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a3f480dd..6aae6b22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,8 +16,7 @@ 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 development or testing (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_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). diff --git a/docs/modules/users.md b/docs/modules/users.md index 63306e24..8f82984e 100644 --- a/docs/modules/users.md +++ b/docs/modules/users.md @@ -545,7 +545,7 @@ Microsoft uses OpenID Connect on the tenant's v2.0 endpoints (`https://login.mic ### 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 `development` or `testing`; 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. Every ID-token rule above still applies, with the document's `issuer` in place of Entra's. +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, so run the app with `SM_ENVIRONMENT=development`); 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): diff --git a/framework/testing/README.md b/framework/testing/README.md index 8af6dc05..29e617b9 100644 --- a/framework/testing/README.md +++ b/framework/testing/README.md @@ -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 diff --git a/framework/testing/simple_module_test/oidc_issuer.py b/framework/testing/simple_module_test/oidc_issuer.py index 0482358b..bb8db0ce 100644 --- a/framework/testing/simple_module_test/oidc_issuer.py +++ b/framework/testing/simple_module_test/oidc_issuer.py @@ -12,6 +12,7 @@ from __future__ import annotations +import functools import json import time from typing import Any @@ -22,13 +23,19 @@ from jwt.algorithms import RSAAlgorithm +@functools.cache +def _signing_key() -> rsa.RSAPrivateKey: + """One RSA key per process: generating 2048-bit keys per test is slow.""" + return rsa.generate_private_key(public_exponent=65537, key_size=2048) + + class OidcTestIssuer: """A fake IdP whose endpoints live under ``issuer`` and whose tokens verify.""" def __init__(self, issuer: str = "https://idp.test/realms/test", kid: str = "test-key") -> None: self.issuer = issuer.rstrip("/") self.kid = kid - self._key = rsa.generate_private_key(public_exponent=65537, key_size=2048) + self._key = _signing_key() @property def discovery_url(self) -> str: diff --git a/modules/users/tests/oauth/devidp/test_users_oauth_microsoft_dev_idp.py b/modules/users/tests/oauth/devidp/test_users_oauth_microsoft_dev_idp.py index b71e3af8..f7866395 100644 --- a/modules/users/tests/oauth/devidp/test_users_oauth_microsoft_dev_idp.py +++ b/modules/users/tests/oauth/devidp/test_users_oauth_microsoft_dev_idp.py @@ -34,6 +34,13 @@ def test_the_override_applies_in_development_and_tests(monkeypatch, environment) assert isinstance(build_client_map(settings)["microsoft"].client, MicrosoftDevOidc) +def test_an_unset_environment_does_not_count_as_development(monkeypatch): + monkeypatch.delenv("SM_ENVIRONMENT", raising=False) + settings = _settings(oauth_microsoft_discovery_url="http://localhost:8080/.well-known/x") + assert settings.microsoft_discovery_url() == "" + assert not isinstance(build_client_map(settings)["microsoft"].client, MicrosoftDevOidc) + + def test_the_override_is_ignored_in_production(monkeypatch, caplog): monkeypatch.setenv("SM_ENVIRONMENT", "production") with caplog.at_level(logging.WARNING, logger="users.settings"): @@ -106,3 +113,30 @@ async def test_a_token_from_another_issuer_is_refused(users_app, anon_client, ht assert resp.json()["detail"] == "OAUTH_PROVIDER_ERROR" assert await find_user(users_app, "jane@corp.com") is None + + +@pytest.mark.anyio +async def test_an_unreachable_discovery_document_refuses_the_login( + users_app, anon_client, httpx_mock +): + issuer = OidcTestIssuer("https://idp.test/realms/entra") + _install(users_app, issuer) + httpx_mock.add_response(url=issuer.discovery_url, status_code=503) + + resp = await anon_client.get("/api/users/auth/microsoft/login", follow_redirects=False) + assert resp.json()["detail"] == "OAUTH_PROVIDER_ERROR" + + +@pytest.mark.anyio +@pytest.mark.parametrize( + "discovery_url", + ["http://idp.example/.well-known/openid-configuration", "https://u:p@idp.test/x"], +) +async def test_a_remote_plain_http_discovery_url_is_refused(users_app, anon_client, discovery_url): + client = MicrosoftDevOidc(_CLIENT, "secret", _TENANT, discovery_url) + users_app.state.users.oauth_clients["microsoft"] = OAuthProvider( + "microsoft", "Microsoft", client + ) + + resp = await anon_client.get("/api/users/auth/microsoft/login", follow_redirects=False) + assert resp.json()["detail"] == "OAUTH_PROVIDER_ERROR" diff --git a/modules/users/users/core/oauth_settings.py b/modules/users/users/core/oauth_settings.py index b2ed56d7..e20415cd 100644 --- a/modules/users/users/core/oauth_settings.py +++ b/modules/users/users/core/oauth_settings.py @@ -102,7 +102,9 @@ class OAuthSettings(DbBackedSettings): def microsoft_discovery_url(self) -> str: """The discovery override if it may apply in this process, else ``""``.""" - if os.environ.get("SM_ENVIRONMENT", "development") not in NON_PROD_ENVIRONMENTS: + # Fail closed: an unset SM_ENVIRONMENT (a deployment that forgot it) never + # counts as development here, unlike the framework's general default. + if os.environ.get("SM_ENVIRONMENT") not in NON_PROD_ENVIRONMENTS: return "" return self.oauth_microsoft_discovery_url.strip() @@ -112,8 +114,8 @@ def _warn_on_ignored_microsoft_discovery(self) -> OAuthSettings: if self.oauth_microsoft_discovery_url.strip() and not self.microsoft_discovery_url(): logger.warning( "users.oauth.microsoft_discovery_ignored — oauth_microsoft_discovery_url is set " - "but SM_ENVIRONMENT is not development or testing; Microsoft sign-in keeps " - "using login.microsoftonline.com." + "but SM_ENVIRONMENT is not explicitly development or testing; Microsoft " + "sign-in keeps using login.microsoftonline.com." ) return self diff --git a/modules/users/users/oauth/api.py b/modules/users/users/oauth/api.py index dce11dca..3ac85b9c 100644 --- a/modules/users/users/oauth/api.py +++ b/modules/users/users/oauth/api.py @@ -128,7 +128,12 @@ async def begin(request: Request, provider: str) -> RedirectResponse: login = {"verifier": secrets.token_urlsafe(64), "nonce": secrets.token_urlsafe(32)} request.session[_SESSION_LOGIN_KEY_FMT.format(provider=provider)] = login callback_url = str(request.url_for(_CALLBACK_ROUTE_NAME, provider=provider)) - authorization_url = await provider_obj.authorization_url(callback_url, state, login) + try: + authorization_url = await provider_obj.authorization_url(callback_url, state, login) + except (HTTPXOAuthError, HTTPError) as exc: + # A development discovery document that cannot be fetched (#879). + logger.warning("OAuth login through %s could not start: %s", provider, exc) + return refuse_login(request, "OAUTH_PROVIDER_ERROR") return RedirectResponse(authorization_url, status_code=302) @router.get("/{provider}/callback", name=_CALLBACK_ROUTE_NAME) diff --git a/modules/users/users/oauth/microsoft_dev.py b/modules/users/users/oauth/microsoft_dev.py index 0ae49a58..9231a446 100644 --- a/modules/users/users/oauth/microsoft_dev.py +++ b/modules/users/users/oauth/microsoft_dev.py @@ -11,6 +11,7 @@ import asyncio from typing import Any, Literal +from urllib.parse import urlsplit import httpx from auth.oidc_common.jwks import JWKSCache @@ -18,6 +19,15 @@ from users.oauth.microsoft import IdTokenError, MicrosoftOidc _REQUIRED = ("issuer", "authorization_endpoint", "token_endpoint", "jwks_uri") +_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"}) + + +def _allowed_url(url: str) -> bool: + """HTTPS, or plain HTTP to this machine (a local Keycloak), without credentials.""" + parts = urlsplit(url) + if not parts.hostname or parts.username or parts.password or "{" in url: + return False + return parts.scheme == "https" or (parts.scheme == "http" and parts.hostname in _LOOPBACK_HOSTS) class MicrosoftDevOidc(MicrosoftOidc): @@ -61,6 +71,8 @@ def _cache(self, tid: str) -> JWKSCache: async def _discover(self) -> None: """Fetch the document once, on first use: never at boot or settings reload.""" + if not _allowed_url(self.discovery_url): + raise IdTokenError("discovery URL must be HTTPS or a loopback HTTP address") if self._jwks is not None: return async with self._lock: @@ -74,9 +86,9 @@ async def _discover(self) -> None: except (httpx.HTTPError, ValueError) as exc: raise IdTokenError(f"discovery failed: {exc}") from exc if not isinstance(doc, dict) or not all( - isinstance(doc.get(key), str) and doc[key] for key in _REQUIRED + isinstance(doc.get(key), str) and _allowed_url(doc[key]) for key in _REQUIRED ): - raise IdTokenError("discovery document lacks issuer or endpoints") + raise IdTokenError("discovery document lacks usable issuer or endpoints") self.authorize_endpoint = doc["authorization_endpoint"] self.access_token_endpoint = doc["token_endpoint"] self.refresh_token_endpoint = doc["token_endpoint"] From ff42c99112307bf6858ead9bdb804283aebbe623 Mon Sep 17 00:00:00 2001 From: Anto Subash Date: Wed, 11 Nov 2026 21:50:27 +0100 Subject: [PATCH 6/6] fix: address code review findings (round 1, pass 2) Docs: make dev does not set SM_ENVIRONMENT; env-vars reference notes the fail-closed override; CHANGELOG list spacing. Claude-Session: https://claude.ai/code/session_01M9neheZZEe3sVpDi2S3zT4 --- CHANGELOG.md | 2 -- docs/modules/users.md | 2 +- docs/reference/env-vars.md | 2 +- 3 files changed, 2 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6aae6b22..cbb4bc30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,9 +19,7 @@ All notable changes to this project are documented in this file. The format is b - `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 diff --git a/docs/modules/users.md b/docs/modules/users.md index 8f82984e..5332e5e6 100644 --- a/docs/modules/users.md +++ b/docs/modules/users.md @@ -545,7 +545,7 @@ Microsoft uses OpenID Connect on the tenant's v2.0 endpoints (`https://login.mic ### 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, so run the app with `SM_ENVIRONMENT=development`); 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. +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): diff --git a/docs/reference/env-vars.md b/docs/reference/env-vars.md index f0ca2984..b8c12b67 100644 --- a/docs/reference/env-vars.md +++ b/docs/reference/env-vars.md @@ -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`. |