simple-module-users 0.0.11__tar.gz → 0.0.12__tar.gz

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_users
-Version: 0.0.11
+Version: 0.0.12
 Summary: Email + password user management, admin invites, RBAC-ready — replaces Keycloak for simple_module apps
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -23,12 +23,12 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: aiosmtplib>=3.0
 Requires-Dist: cachetools>=5.3
-Requires-Dist: fastapi-users[sqlalchemy]<16,>=15
-Requires-Dist: simple-module-auth==0.0.11
-Requires-Dist: simple-module-core==0.0.11
-Requires-Dist: simple-module-db==0.0.11
-Requires-Dist: simple-module-hosting==0.0.11
-Requires-Dist: simple-module-settings==0.0.11
+Requires-Dist: fastapi-users[oauth,sqlalchemy]<16,>=15
+Requires-Dist: simple-module-auth==0.0.12
+Requires-Dist: simple-module-core==0.0.12
+Requires-Dist: simple-module-db==0.0.12
+Requires-Dist: simple-module-hosting==0.0.12
+Requires-Dist: simple-module-settings==0.0.12
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 
@@ -42,7 +42,7 @@ Email+password user management for [simple_module](https://github.com/antosubash
 pip install simple_module_users
 ```
 
-Pre-wired into any app scaffolded with `simple-module new`.
+Pre-wired into any app scaffolded with `smpy new`.
 
 ## What it provides
 
@@ -50,7 +50,7 @@ Pre-wired into any app scaffolded with `simple-module new`.
 - Admin invite flow — admin enters an email, recipient clicks a link, sets a password, is logged in.
 - Public signup toggle (`SM_USERS_ALLOW_SIGNUP`, default `false`).
 - Bootstrap admin via env vars (`SM_USERS_BOOTSTRAP_EMAIL` + `SM_USERS_BOOTSTRAP_PASSWORD`) — idempotent, only creates if the users table is empty.
-- `sm-users create-admin` CLI for ad-hoc admin creation.
+- `smpy users create-admin` CLI for ad-hoc admin creation.
 - Inertia pages for login/register/invite-accept/admin-invite.
 - Console mailer (logs to stdout) or SMTP mailer (`SM_USERS_MAILER=smtp`).
 
@@ -59,7 +59,7 @@ Pre-wired into any app scaffolded with `simple-module new`.
 CLI:
 
 ```bash
-uv run sm-users create-admin --email admin@example.com --password 'change-me'
+uv run smpy users create-admin --email admin@example.com --password 'change-me'
 ```
 
 Bootstrap-on-boot (`.env`):

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/README.md

@@ -8,7 +8,7 @@ Email+password user management for [simple_module](https://github.com/antosubash
 pip install simple_module_users
 ```
 
-Pre-wired into any app scaffolded with `simple-module new`.
+Pre-wired into any app scaffolded with `smpy new`.
 
 ## What it provides
 
@@ -16,7 +16,7 @@ Pre-wired into any app scaffolded with `simple-module new`.
 - Admin invite flow — admin enters an email, recipient clicks a link, sets a password, is logged in.
 - Public signup toggle (`SM_USERS_ALLOW_SIGNUP`, default `false`).
 - Bootstrap admin via env vars (`SM_USERS_BOOTSTRAP_EMAIL` + `SM_USERS_BOOTSTRAP_PASSWORD`) — idempotent, only creates if the users table is empty.
-- `sm-users create-admin` CLI for ad-hoc admin creation.
+- `smpy users create-admin` CLI for ad-hoc admin creation.
 - Inertia pages for login/register/invite-accept/admin-invite.
 - Console mailer (logs to stdout) or SMTP mailer (`SM_USERS_MAILER=smtp`).
 
@@ -25,7 +25,7 @@ Pre-wired into any app scaffolded with `simple-module new`.
 CLI:
 
 ```bash
-uv run sm-users create-admin --email admin@example.com --password 'change-me'
+uv run smpy users create-admin --email admin@example.com --password 'change-me'
 ```
 
 Bootstrap-on-boot (`.env`):

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_users"
-version = "0.0.11"
+version = "0.0.12"
 description = "Email + password user management, admin invites, RBAC-ready — replaces Keycloak for simple_module apps"
 readme = "README.md"
 license = "MIT"
@@ -21,15 +21,15 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "simple_module_core==0.0.11",
-    "simple_module_db==0.0.11",
-    "simple_module_hosting==0.0.11",
-    "simple_module_settings==0.0.11",
-    "simple_module_auth==0.0.11",
+    "simple_module_core==0.0.12",
+    "simple_module_db==0.0.12",
+    "simple_module_hosting==0.0.12",
+    "simple_module_settings==0.0.12",
+    "simple_module_auth==0.0.12",
     # Pinned to a narrow range: `deps.py` relies on mutating CookieTransport
     # fields after construction (see reconfigure_cookie_transport in backend.py).
     # Bumping the major version requires re-checking those field names.
-    "fastapi-users[sqlalchemy]>=15,<16",
+    "fastapi-users[sqlalchemy,oauth]>=15,<16",
     "aiosmtplib>=3.0",
     "cachetools>=5.3",
     "typer>=0.12",

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/tests/test_cli.py

@@ -1,4 +1,4 @@
-"""Tests for the sm-users CLI (users.cli).
+"""Tests for the smpy users CLI (users.cli).
 
 Strategy: monkeypatch ``users.bootstrap.create_admin`` so tests do not need
 a real database.  This avoids the complexity of standing up a schema-stamped
@@ -161,7 +161,7 @@ def test_create_admin_missing_email() -> None:
 
 
 def test_app_help() -> None:
-    """``sm-users --help`` shows the top-level help text and lists create-admin."""
+    """``smpy users --help`` shows the top-level help text and lists create-admin."""
     result = runner.invoke(app, ["--help"])
     assert result.exit_code == 0
     assert "create-admin" in result.output

simple_module_users-0.0.12/tests/test_oauth.py

@@ -0,0 +1,189 @@
+"""Unit + integration tests for the OAuth/OIDC plumbing.
+
+Provider client construction and the /authorize+/callback ASGI flow are not
+covered here because both depend on real httpx-oauth clients that hit the
+network (token exchange, profile fetch). Those are best validated in a manual
+QA pass against a dev IdP. What this file *does* cover:
+
+- ``enabled_provider_names`` correctly reflects settings.
+- ``build_clients`` instantiates the Google + GitHub clients when configured.
+- ``OAuthAccount`` persists and FK-cascades on user delete.
+- ``UserManager.oauth_callback`` (the find-or-create core fastapi-users helper
+  the route delegates to) creates a fresh user + linked OAuthAccount, and
+  associates by email when the user already exists.
+"""
+
+from __future__ import annotations
+
+import uuid
+
+import pytest
+from fastapi_users.password import PasswordHelper
+from sqlalchemy import select
+from users.models import OAuthAccount, User
+from users.oauth import build_clients, enabled_provider_names
+from users.settings import UsersSettings
+
+_pw = PasswordHelper()
+
+
+# ---------------------------------------------------------------------------
+# Settings → provider list
+# ---------------------------------------------------------------------------
+
+
+def test_enabled_provider_names_empty_by_default():
+    assert enabled_provider_names(UsersSettings()) == []
+
+
+def test_enabled_provider_names_lists_configured_providers():
+    s = UsersSettings(
+        oauth_google_client_id="g-id",
+        oauth_google_client_secret="g-secret",
+        oauth_github_client_id="gh-id",
+        oauth_github_client_secret="gh-secret",
+    )
+    names = [p["name"] for p in enabled_provider_names(s)]
+    assert names == ["google", "github"]
+
+
+def test_enabled_provider_names_skips_provider_missing_secret():
+    s = UsersSettings(oauth_google_client_id="g-id")  # no secret
+    assert enabled_provider_names(s) == []
+
+
+def test_enabled_provider_names_oidc_requires_discovery_url():
+    s = UsersSettings(
+        oauth_oidc_client_id="x",
+        oauth_oidc_client_secret="y",
+        # discovery_url unset → not registered
+    )
+    assert enabled_provider_names(s) == []
+
+
+# ---------------------------------------------------------------------------
+# build_clients (no-network providers only)
+# ---------------------------------------------------------------------------
+
+
+def test_build_clients_google_and_github():
+    s = UsersSettings(
+        oauth_google_client_id="g-id",
+        oauth_google_client_secret="g-secret",
+        oauth_github_client_id="gh-id",
+        oauth_github_client_secret="gh-secret",
+    )
+    providers = build_clients(s)
+    assert [p.name for p in providers] == ["google", "github"]
+    # Sanity-check that the underlying httpx-oauth client carries our id.
+    assert providers[0].client.client_id == "g-id"
+    assert providers[1].client.client_id == "gh-id"
+
+
+# ---------------------------------------------------------------------------
+# OAuthAccount persistence + cascade
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.anyio
+async def test_oauth_account_round_trip_and_cascade(users_db):
+    user = User(
+        id=uuid.uuid4(),
+        email="oauth-rt@example.com",
+        hashed_password=_pw.hash("SecurePass1!"),
+        is_active=True,
+        is_verified=True,
+    )
+    users_db.add(user)
+    await users_db.commit()
+
+    account = OAuthAccount(
+        user_id=user.id,
+        oauth_name="google",
+        access_token="tok",
+        account_id="google-123",
+        account_email=user.email,
+    )
+    users_db.add(account)
+    await users_db.commit()
+
+    found = (
+        await users_db.execute(select(OAuthAccount).where(OAuthAccount.account_id == "google-123"))
+    ).scalar_one()
+    assert found.user_id == user.id
+
+    # FK cascade: deleting the user removes the linked account.
+    await users_db.delete(user)
+    await users_db.commit()
+    remaining = (
+        await users_db.execute(select(OAuthAccount).where(OAuthAccount.account_id == "google-123"))
+    ).scalar_one_or_none()
+    assert remaining is None
+
+
+# ---------------------------------------------------------------------------
+# UserManager.oauth_callback — the find-or-create flow the route delegates to
+# ---------------------------------------------------------------------------
+
+
+async def _build_user_manager(app):
+    """Construct a UserManager bound to the test app's DB session."""
+    from users.db_adapter import UserDatabaseWithRoles
+    from users.manager import UserManager
+    from users.models import OAuthAccount, User
+
+    session = app.state.sm.db.session_factory()
+    s = await session.__aenter__()
+    user_db = UserDatabaseWithRoles(s, User, OAuthAccount)
+    manager = UserManager(user_db, app.state.users.mailer, app.state.users.settings)
+    return manager, session, s
+
+
+@pytest.mark.anyio
+async def test_oauth_callback_creates_new_user_and_account(users_app):
+    manager, session, _ = await _build_user_manager(users_app)
+    try:
+        user = await manager.oauth_callback(
+            "google",
+            access_token="tok",
+            account_id="google-new-1",
+            account_email="newuser@example.com",
+            associate_by_email=True,
+            is_verified_by_default=True,
+        )
+        assert user.email == "newuser@example.com"
+        assert user.is_verified is True
+        assert len(user.oauth_accounts) == 1
+        assert user.oauth_accounts[0].oauth_name == "google"
+        assert user.oauth_accounts[0].account_id == "google-new-1"
+    finally:
+        await session.__aexit__(None, None, None)
+
+
+@pytest.mark.anyio
+async def test_oauth_callback_links_to_existing_email(users_app, users_db):
+    existing = User(
+        id=uuid.uuid4(),
+        email="existing@example.com",
+        hashed_password=_pw.hash("SecurePass1!"),
+        is_active=True,
+        is_verified=True,
+    )
+    users_db.add(existing)
+    await users_db.commit()
+
+    manager, session, _ = await _build_user_manager(users_app)
+    try:
+        linked = await manager.oauth_callback(
+            "github",
+            access_token="tok",
+            account_id="gh-42",
+            account_email="existing@example.com",
+            associate_by_email=True,
+            is_verified_by_default=True,
+        )
+        assert linked.id == existing.id
+        names = [a.oauth_name for a in linked.oauth_accounts]
+        assert names == ["github"]
+    finally:
+        await session.__aexit__(None, None, None)

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/cli.py

@@ -1,9 +1,10 @@
 """Command-line entry points for the users module.
 
-Exposed via ``sm-users`` (see pyproject.toml [project.scripts]).
+Exposed via ``smpy users`` (see pyproject.toml
+[project.entry-points.simple_module_cli.cli_plugins]).
 
-    sm-users create-admin --email a@b.test --password sekret [--full-name Me]
-    sm-users create-admin --email a@b.test --password new --force
+    smpy users create-admin --email a@b.test --password sekret [--full-name Me]
+    smpy users create-admin --email a@b.test --password new --force
 """
 
 from __future__ import annotations

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/db_adapter.py

@@ -12,7 +12,7 @@ from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
-from users.models import User, UserAccessToken
+from users.models import OAuthAccount, User, UserAccessToken
 
 
 class UserDatabaseWithRoles(SQLAlchemyUserDatabase):
@@ -39,7 +39,10 @@ class UserDatabaseWithRoles(SQLAlchemyUserDatabase):
 async def get_user_db(
     session: AsyncSession = Depends(get_db),
 ) -> AsyncGenerator[UserDatabaseWithRoles, None]:
-    yield UserDatabaseWithRoles(session, User)
+    # OAuthAccount enables fastapi-users' OAuth router (get_by_oauth_account /
+    # add_oauth_account / update_oauth_account). Password-only flows are
+    # unaffected — those code paths never touch oauth_account_table.
+    yield UserDatabaseWithRoles(session, User, OAuthAccount)
 
 
 async def get_access_token_db(

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/endpoints/api.py

@@ -30,8 +30,10 @@ from users.deps import (
     get_user_manager,
 )
 from users.endpoints.api_admin import admin_router
+from users.endpoints.api_oauth import register_oauth_routes
 from users.manager import UserManager
 from users.rate_limit import LoginRateLimiter, ThroughputLimiter
+from users.settings import UsersSettings
 
 logger = logging.getLogger(__name__)
 router = APIRouter()
@@ -125,7 +127,7 @@ auth_inner = fastapi_users.get_auth_router(auth_backend, requires_verification=T
 router.include_router(auth_inner, prefix="/auth-inner")
 
 
-def register_auth_routes(api_router: APIRouter) -> None:
+def register_auth_routes(api_router: APIRouter, settings: UsersSettings) -> None:
     """Mount all auth routes.
 
     The stock fastapi-users routers (reset/verify/register) ship POST endpoints
@@ -137,6 +139,9 @@ def register_auth_routes(api_router: APIRouter) -> None:
 
     The register router is always mounted; ``require_signup_enabled`` gates
     it at request time so ``allow_signup`` is hot-reloadable.
+
+    OAuth providers configured in ``settings`` are mounted under
+    ``/auth/<provider>/{login,callback}`` — see :mod:`users.endpoints.api_oauth`.
     """
     api_router.include_router(router)
     api_router.include_router(
@@ -160,6 +165,7 @@ def register_auth_routes(api_router: APIRouter) -> None:
             Depends(enforce_auth_throughput_limit),
         ],
     )
+    register_oauth_routes(api_router, settings)
 
 
 # ── Accept-invite (verify + set password + login, one shot) ─────────────────

simple_module_users-0.0.12/users/endpoints/api_oauth.py

@@ -0,0 +1,131 @@
+"""OAuth/OIDC login routes — one pair (``/login``, ``/callback``) per provider.
+
+Why a custom handler rather than ``fastapi_users.get_oauth_router``: the stock
+router's ``/callback`` returns a 204 No Content with the auth cookie set. That
+works for SPA flows that redirect on a successful AJAX response, but Inertia
+expects the user's browser to land on a real page. Here ``/callback`` returns
+a 303 redirect to ``settings.login_redirect_url`` instead, with the same
+cookie attached.
+
+Find-or-create + email-association logic still goes through
+``UserManager.oauth_callback`` — we don't reimplement it, only the transport
+around it. State CSRF uses Starlette's signed session cookie (already mounted
+by the framework) instead of fastapi-users' separate JWT-state cookie.
+"""
+
+from __future__ import annotations
+
+import logging
+import secrets
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi_users import exceptions as fu_exceptions
+from starlette.responses import RedirectResponse
+
+from users.deps import auth_backend, get_user_manager
+from users.oauth import OAuthProvider, build_clients
+
+if TYPE_CHECKING:
+    from users.manager import UserManager
+    from users.settings import UsersSettings
+
+logger = logging.getLogger(__name__)
+
+_SESSION_STATE_KEY_FMT = "oauth_state:{provider}"
+
+
+def _build_provider_router(provider: OAuthProvider, login_redirect_url: str) -> APIRouter:
+    """Mount /login + /callback for one provider."""
+    router = APIRouter()
+    state_key = _SESSION_STATE_KEY_FMT.format(provider=provider.name)
+
+    @router.get("/login")
+    async def begin(request: Request) -> RedirectResponse:
+        """Generate a state nonce, stash it in the session, redirect to the IdP."""
+        state = secrets.token_urlsafe(32)
+        request.session[state_key] = state
+        callback_url = str(request.url_for(f"oauth_{provider.name}_callback"))
+        authorization_url = await provider.client.get_authorization_url(callback_url, state)
+        return RedirectResponse(authorization_url, status_code=302)
+
+    @router.get("/callback", name=f"oauth_{provider.name}_callback")
+    async def callback(
+        request: Request,
+        code: str | None = None,
+        state: str | None = None,
+        user_manager: UserManager = Depends(get_user_manager),
+        strategy=Depends(auth_backend.get_strategy),
+    ) -> RedirectResponse:
+        """Verify state, exchange code, find-or-create user, set cookie, redirect."""
+        expected_state = request.session.pop(state_key, None)
+        if not state or not expected_state or not secrets.compare_digest(state, expected_state):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="OAUTH_INVALID_STATE"
+            )
+        if not code:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="OAUTH_MISSING_CODE"
+            )
+
+        callback_url = str(request.url_for(f"oauth_{provider.name}_callback"))
+        token = await provider.client.get_access_token(code, callback_url)
+        account_id, account_email = await provider.client.get_id_email(token["access_token"])
+        if account_email is None:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="OAUTH_NO_EMAIL")
+
+        try:
+            user = await user_manager.oauth_callback(
+                provider.name,
+                token["access_token"],
+                account_id,
+                account_email,
+                token.get("expires_at"),
+                token.get("refresh_token"),
+                request,
+                associate_by_email=True,
+                is_verified_by_default=True,
+            )
+        except fu_exceptions.UserAlreadyExists:
+            # Email exists but associate_by_email=False would forbid linking.
+            # We always pass True above, so this branch only fires if the
+            # provider returns ambiguous data.
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="OAUTH_USER_ALREADY_EXISTS",
+            ) from None
+
+        if not user.is_active:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="LOGIN_BAD_CREDENTIALS"
+            )
+
+        # Set the auth cookie via the existing backend, then bridge the
+        # session in on_after_login (sets session["user_id"] for AuthMiddleware).
+        login_response = await auth_backend.login(strategy, user)
+        await user_manager.on_after_login(user, request, login_response)
+
+        redirect = RedirectResponse(login_redirect_url, status_code=303)
+        for key, value in login_response.headers.items():
+            if key.lower() == "set-cookie":
+                redirect.raw_headers.append((b"set-cookie", value.encode("latin-1")))
+        return redirect
+
+    return router
+
+
+def register_oauth_routes(api_router: APIRouter, settings: UsersSettings) -> None:
+    """Mount /auth/<provider>/{login,callback} for every configured provider."""
+    providers = build_clients(settings)
+    for provider in providers:
+        api_router.include_router(
+            _build_provider_router(provider, settings.login_redirect_url),
+            prefix=f"/auth/{provider.name}",
+            tags=["users-auth"],
+        )
+    if providers:
+        logger.info(
+            "Registered %d OAuth provider(s): %s",
+            len(providers),
+            ", ".join(p.name for p in providers),
+        )

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/endpoints/views.py

@@ -14,6 +14,7 @@ from starlette.responses import RedirectResponse
 from users.constants import PERM_USERS_MANAGE, sanitize_list_filters
 from users.deps import get_user_service
 from users.exceptions import UserNotFoundError
+from users.oauth import enabled_provider_names
 from users.roles_cache import get_roles_cache
 from users.service import UserService
 
@@ -72,6 +73,7 @@ async def login_page(request: Request, inertia: InertiaDep) -> InertiaResponse:
             "allow_signup": users_settings.allow_signup,
             "dev_accounts": dev_accounts,
             "login_redirect_url": users_settings.login_redirect_url,
+            "oauth_providers": enabled_provider_names(users_settings),
         },
     )
 

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/manager.py

@@ -11,6 +11,7 @@ from fastapi import Depends, Request
 from fastapi_users import BaseUserManager, UUIDIDMixin, exceptions
 from fastapi_users.jwt import generate_jwt
 
+from users.constants import SESSION_USER_ID_KEY
 from users.contracts.events import UserRegistered
 from users.db_adapter import UserDatabaseWithRoles, get_user_db
 from users.mailer import Mailer
@@ -86,6 +87,13 @@ class UserManager(UUIDIDMixin, BaseUserManager[User, uuid.UUID]):
     ) -> None:
         user.last_login_at = datetime.now(UTC)
         await self.user_db.update(user, {"last_login_at": user.last_login_at})
+        # Bridge to AuthMiddleware: it reads session["user_id"] (not the
+        # fastapi-users cookie) to identify the request principal. Setting it
+        # here covers OAuth callbacks too, where there's no wrapper to do it
+        # explicitly. Password / accept-invite flows already set this in their
+        # wrappers — re-assigning the same value here is a harmless no-op.
+        if request is not None:
+            request.session[SESSION_USER_ID_KEY] = str(user.id)
 
     # ── Token helpers (no email side-effect) ─────────────────
 

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/models/__init__.py

@@ -9,12 +9,14 @@ from fastapi_users_db_sqlalchemy.access_token import SQLAlchemyAccessTokenDataba
 
 from users.models._base import Base
 from users.models.access_token import UserAccessToken
+from users.models.oauth_account import OAuthAccount
 from users.models.role import Role
 from users.models.user import User
 from users.models.user_role import UserRole
 
 __all__ = [
     "Base",
+    "OAuthAccount",
     "Role",
     "SQLAlchemyAccessTokenDatabase",
     "SQLAlchemyUserDatabase",

simple_module_users-0.0.12/users/models/oauth_account.py

@@ -0,0 +1,41 @@
+"""OAuth account table — links a (provider, account_id) pair to a User row.
+
+Column surface mirrors fastapi-users' ``SQLAlchemyBaseOAuthAccountTableUUID``
+so ``SQLAlchemyUserDatabase`` binds to it without inheriting from the upstream
+base class (whose ``Mapped[...]`` columns are incompatible with SQLModel's
+metaclass — same constraint as ``User`` / ``UserAccessToken``).
+"""
+
+# NOTE: intentionally no ``from __future__ import annotations`` — SQLModel
+# Relationship resolution requires runtime annotations.
+
+import uuid
+
+from fastapi_users_db_sqlalchemy.generics import GUID
+from sqlmodel import Field
+
+from users.models._base import Base
+
+
+class OAuthAccount(Base, table=True):  # ty: ignore[unsupported-base]
+    """One row per (provider, account_id) link to a local User."""
+
+    __tablename__ = "users_oauth_account"
+
+    id: uuid.UUID = Field(
+        default_factory=uuid.uuid4,
+        sa_type=GUID,
+        primary_key=True,
+    )
+    user_id: uuid.UUID = Field(
+        sa_type=GUID,
+        foreign_key="users_user.id",
+        ondelete="CASCADE",
+        index=True,
+    )
+    oauth_name: str = Field(max_length=100, index=True)
+    access_token: str = Field(max_length=1024)
+    expires_at: int | None = Field(default=None)
+    refresh_token: str | None = Field(default=None, max_length=1024)
+    account_id: str = Field(max_length=320, index=True)
+    account_email: str = Field(max_length=320)

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/models/user.py

@@ -25,6 +25,7 @@ from users.models.user_role import UserRole
 if TYPE_CHECKING:
     # Resolved at runtime by SQLModel via the string forward ref;
     # this import only feeds the type checker.
+    from users.models.oauth_account import OAuthAccount
     from users.models.role import Role
 
 
@@ -62,6 +63,17 @@ class User(Base, AuditMixin, table=True):  # ty: ignore[unsupported-base]
         sa_relationship_kwargs={"lazy": "noload"},
     )
 
+    # fastapi-users' SQLAlchemyUserDatabase.add_oauth_account does
+    # ``user.oauth_accounts.append(...)``, so this attribute must exist.
+    # ``selectin`` so the OAuth router can read the list without an
+    # implicit async lazy-load.
+    oauth_accounts: list["OAuthAccount"] = Relationship(
+        sa_relationship_kwargs={
+            "lazy": "selectin",
+            "cascade": "all, delete-orphan",
+        },
+    )
+
     # Functional index so the ``lower(email)`` predicate used by
     # ``UserDatabaseWithRoles.get_by_email`` can be served from an index.
     __table_args__ = (Index("ix_users_user_email_lower", text("lower(email)")),)

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/module.py

@@ -112,11 +112,12 @@ class UsersModule(ModuleBase):
     def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
         from users.endpoints.api import register_auth_routes
         from users.endpoints.views import router as views
+        from users.settings import UsersSettings
 
-        # The register router is always mounted; its `allow_signup` gate lives
-        # on a per-request dependency, so toggling the setting at runtime takes
-        # effect without needing to remount.
-        register_auth_routes(api_router)
+        # Construct settings here (re-reads env_str-bound fields like OAuth
+        # client ids/secrets). Validators have already passed by this point —
+        # ``register_settings`` ran first and would have raised on placeholders.
+        register_auth_routes(api_router, UsersSettings())
         view_router.include_router(views)
 
     def register_middleware(self, app: FastAPI) -> None:

simple_module_users-0.0.12/users/oauth.py

@@ -0,0 +1,120 @@
+"""OAuth/OIDC provider client factory.
+
+Constructs the ``httpx_oauth`` clients for every provider that has both
+``client_id`` and ``client_secret`` set in :class:`UsersSettings`. A provider
+with no credentials is silently skipped — that's the "feature flag" knob.
+
+Lives in its own module so :func:`UsersModule.register_routes` can import it
+without dragging the heavy ``httpx_oauth`` packages into the cold-start path
+when no provider is configured.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, NamedTuple
+
+if TYPE_CHECKING:
+    from httpx_oauth.oauth2 import BaseOAuth2
+
+    from users.settings import UsersSettings
+
+logger = logging.getLogger(__name__)
+
+
+class OAuthProvider(NamedTuple):
+    """One configured provider — name is the URL segment (``/auth/<name>``)."""
+
+    name: str
+    display_name: str
+    client: BaseOAuth2
+
+
+def enabled_provider_names(settings: UsersSettings) -> list[dict[str, str]]:
+    """Return ``[{"name": ..., "display_name": ...}]`` for configured providers.
+
+    Cheap settings-only check used by the login page to render social-login
+    buttons. Does not construct clients or hit the network — that would be
+    wasteful per page render and would fail-open if discovery is briefly
+    unreachable.
+    """
+    out: list[dict[str, str]] = []
+    if settings.oauth_google_client_id and settings.oauth_google_client_secret:
+        out.append({"name": "google", "display_name": "Google"})
+    if settings.oauth_github_client_id and settings.oauth_github_client_secret:
+        out.append({"name": "github", "display_name": "GitHub"})
+    if (
+        settings.oauth_oidc_client_id
+        and settings.oauth_oidc_client_secret
+        and settings.oauth_oidc_discovery_url
+    ):
+        out.append({"name": "oidc", "display_name": settings.oauth_oidc_display_name or "OIDC"})
+    return out
+
+
+def build_clients(settings: UsersSettings) -> list[OAuthProvider]:
+    """Return one entry per provider that has both id and secret configured.
+
+    The generic OIDC provider also requires a discovery URL. If discovery
+    fetch fails at construction time, the provider is logged and skipped
+    rather than raising — a misconfigured IdP must not break boot.
+    """
+    out: list[OAuthProvider] = []
+
+    if settings.oauth_google_client_id and settings.oauth_google_client_secret:
+        from httpx_oauth.clients.google import GoogleOAuth2
+
+        out.append(
+            OAuthProvider(
+                "google",
+                "Google",
+                GoogleOAuth2(
+                    settings.oauth_google_client_id,
+                    settings.oauth_google_client_secret,
+                ),
+            )
+        )
+
+    if settings.oauth_github_client_id and settings.oauth_github_client_secret:
+        from httpx_oauth.clients.github import GitHubOAuth2
+
+        out.append(
+            OAuthProvider(
+                "github",
+                "GitHub",
+                GitHubOAuth2(
+                    settings.oauth_github_client_id,
+                    settings.oauth_github_client_secret,
+                ),
+            )
+        )
+
+    if (
+        settings.oauth_oidc_client_id
+        and settings.oauth_oidc_client_secret
+        and settings.oauth_oidc_discovery_url
+    ):
+        from httpx_oauth.clients.openid import OpenID, OpenIDConfigurationError
+
+        try:
+            client = OpenID(
+                settings.oauth_oidc_client_id,
+                settings.oauth_oidc_client_secret,
+                settings.oauth_oidc_discovery_url,
+                name="oidc",
+            )
+        except OpenIDConfigurationError:
+            logger.exception(
+                "OIDC discovery failed for %s — provider disabled",
+                settings.oauth_oidc_discovery_url,
+            )
+        else:
+            out.append(
+                OAuthProvider(
+                    "oidc",
+                    settings.oauth_oidc_display_name or "OIDC",
+                    client,
+                )
+            )
+
+    return out

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/pages/Login.tsx

@@ -12,15 +12,22 @@ interface DevAccount {
   password: string;
 }
 
+interface OAuthProvider {
+  name: string;
+  display_name: string;
+}
+
 interface Props {
   allow_signup: boolean;
   dev_accounts: DevAccount[];
   login_redirect_url: string;
+  oauth_providers: OAuthProvider[];
 }
 
 function Login() {
-  const { allow_signup, dev_accounts, login_redirect_url } = usePage<{ props: Props }>()
-    .props as unknown as Props;
+  const { allow_signup, dev_accounts, login_redirect_url, oauth_providers } = usePage<{
+    props: Props;
+  }>().props as unknown as Props;
 
   const [email, setEmail] = useState('');
   const [password, setPassword] = useState('');
@@ -156,6 +163,21 @@ function Login() {
         </p>
       )}
 
+      {oauth_providers && oauth_providers.length > 0 && (
+        <div className="mt-5 border-t border-border pt-4">
+          <p className="mb-2 text-center font-mono text-[11px] text-muted-foreground">
+            Or continue with
+          </p>
+          <div className="flex flex-col gap-2">
+            {oauth_providers.map((p) => (
+              <Button key={p.name} type="button" variant="outline" asChild disabled={loading}>
+                <a href={`/api/users/auth/${p.name}/login`}>{p.display_name}</a>
+              </Button>
+            ))}
+          </div>
+        </div>
+      )}
+
       {dev_accounts && dev_accounts.length > 0 && (
         <div className="mt-5 border-t border-border pt-4">
           <p className="mb-2 text-center font-mono text-[11px] text-muted-foreground">

{simple_module_users-0.0.11 → simple_module_users-0.0.12}/users/settings.py

@@ -31,7 +31,7 @@ class UsersSettings(BaseSettings):
     require_verification: bool = True
 
     # Where the login page sends a successful sign-in. Sites without the
-    # bundled ``dashboard`` module (``sm new --preset minimal``) override
+    # bundled ``dashboard`` module (``smpy new --preset minimal``) override
     # this to wherever their post-login landing lives.
     login_redirect_url: str = "/dashboard/"
 
@@ -84,6 +84,21 @@ class UsersSettings(BaseSettings):
     bootstrap_user_email: str = ""
     bootstrap_user_password: str = ""
 
+    # OAuth / OIDC providers. Each provider is enabled by setting both client
+    # id and secret; missing credentials = provider not registered. Resolved
+    # at module-import time (env_str) because client secrets shouldn't ride
+    # in the DB-backed settings table that admins can read via the UI.
+    oauth_google_client_id: str = env_str("SM_USERS_OAUTH_GOOGLE_CLIENT_ID", "")
+    oauth_google_client_secret: str = env_str("SM_USERS_OAUTH_GOOGLE_CLIENT_SECRET", "")
+    oauth_github_client_id: str = env_str("SM_USERS_OAUTH_GITHUB_CLIENT_ID", "")
+    oauth_github_client_secret: str = env_str("SM_USERS_OAUTH_GITHUB_CLIENT_SECRET", "")
+    # Generic OIDC — works with any provider that exposes a discovery URL
+    # (Keycloak, Authentik, Auth0, Zitadel, Entra ID, ...).
+    oauth_oidc_client_id: str = env_str("SM_USERS_OAUTH_OIDC_CLIENT_ID", "")
+    oauth_oidc_client_secret: str = env_str("SM_USERS_OAUTH_OIDC_CLIENT_SECRET", "")
+    oauth_oidc_discovery_url: str = env_str("SM_USERS_OAUTH_OIDC_DISCOVERY_URL", "")
+    oauth_oidc_display_name: str = env_str("SM_USERS_OAUTH_OIDC_DISPLAY_NAME", "OIDC")
+
     @model_validator(mode="after")
     def _forbid_placeholder_token_secrets_in_production(self) -> UsersSettings:
         """Fail boot if the reset/verify token secrets are still placeholders.