feat: OIDC SSO (Google/GitHub/generic) and LDAP login with invitation-only mode.

Adds two login paths alongside local passwords:
- OIDC/OAuth via a provider registry, shipping Google, GitHub, and a
  generic OIDC profile (Keycloak/Authentik/Okta). Access is gated by
  email-domain, email, or IdP-group allowlists, with `OIDC_ALLOW_SIGNUP`
  defaulting to invitation-only. Admins pre-provision users through a new
  `POST /api/users/invite` endpoint; SSO then links by verified email.
- LDAP/AD as a fallback in `POST /api/auth/login`, with optional group
  sync into local `groups` (rows marked `ldap_dn`) and admin-group
  mapping. Takeover guard refuses to bind when a real local password
  exists under the same username.

Schema additions land as migrations v6 (`auth_identities` table keyed by
`(provider, subject)`) and v7 (`groups.ldap_dn` with partial unique
index). SSO-only accounts use `password_hash='!'` so bcrypt can never
match.

LDAP group-search errors are distinguished from clean empty results so
transient LDAP flakes can't silently demote admins. SessionMiddleware
cookies auto-harden to HTTPS when `PUBLIC_BASE_URL` is https, with a
startup warning when SSO is enabled over plaintext.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: PttCodingMan

.env.example

@@ -33,5 +33,61 @@ AI_RATE_LIMIT_PER_HOUR=20
 #   Groq:     AI_BASE_URL=https://api.groq.com/openai/v1       AI_MODEL=llama-3.3-70b-versatile
 #   DeepSeek: AI_BASE_URL=https://api.deepseek.com             AI_MODEL=deepseek-chat
 
+# ── OIDC / OAuth SSO (optional) ──
+# Public URL the browser can reach — used to build OIDC redirect_uri.
+# Dev with Vite proxy: http://localhost:5173   Prod: https://wiki.example.com
+PUBLIC_BASE_URL=http://localhost:8000
+
+OIDC_ENABLED=false
+# Comma-separated. Only providers listed here AND with a client_id+secret below are offered.
+OIDC_PROVIDERS=google,github,generic
+
+# Who can sign in (any rule that is set must pass):
+#   invitation-only (default): admin pre-creates user via Admin → Invite (SSO).
+#   Set OIDC_ALLOW_SIGNUP=true to auto-create on first login (still gated by rules below).
+OIDC_ALLOW_SIGNUP=false
+OIDC_ALLOWED_EMAILS=
+OIDC_ALLOWED_EMAIL_DOMAINS=
+OIDC_REQUIRED_GROUPS=
+OIDC_DEFAULT_ROLE=editor
+
+# Google
+#   Redirect URI to register in Google Cloud Console:
+#   {PUBLIC_BASE_URL}/api/auth/oauth/google/callback
+OIDC_GOOGLE_CLIENT_ID=
+OIDC_GOOGLE_CLIENT_SECRET=
+OIDC_GOOGLE_DISCOVERY=https://accounts.google.com/.well-known/openid-configuration
+
+# GitHub — OAuth2 (not OIDC). The app needs `user:email` scope to read the
+# primary email when it's set to private in GitHub settings.
+#   Redirect URI: {PUBLIC_BASE_URL}/api/auth/oauth/github/callback
+OIDC_GITHUB_CLIENT_ID=
+OIDC_GITHUB_CLIENT_SECRET=
+
+# Generic OIDC — Keycloak, Authentik, Okta, Auth0, any compliant provider.
+#   Redirect URI: {PUBLIC_BASE_URL}/api/auth/oauth/generic/callback
+OIDC_GENERIC_NAME=Company SSO
+OIDC_GENERIC_CLIENT_ID=
+OIDC_GENERIC_CLIENT_SECRET=
+OIDC_GENERIC_DISCOVERY=
+
+# ── LDAP / Active Directory (optional) ──
+LDAP_ENABLED=false
+# Must be ldaps:// — plain ldap:// is rejected to avoid sending passwords in clear.
+LDAP_SERVER=ldaps://ldap.example.com
+LDAP_TLS_VERIFY=true
+LDAP_BIND_DN=cn=svc-wiki,ou=services,dc=example,dc=com
+LDAP_BIND_PASSWORD=
+LDAP_USER_BASE=ou=people,dc=example,dc=com
+LDAP_USER_FILTER=(&(objectClass=person)(uid={username}))
+LDAP_ATTR_EMAIL=mail
+LDAP_ATTR_DISPLAY_NAME=displayName
+LDAP_DEFAULT_ROLE=editor
+# Group sync (optional)
+LDAP_SYNC_GROUPS=false
+LDAP_GROUP_BASE=ou=groups,dc=example,dc=com
+LDAP_GROUP_FILTER=(&(objectClass=groupOfNames)(member={user_dn}))
+LDAP_ADMIN_GROUPS=wiki-admins
+
 # ── Webhook (Phase 7, 可選) ──
 WEBHOOK_URLS=

backend/app/config.py

@@ -19,6 +19,56 @@ class Settings(BaseSettings):
     # in production, e.g. "https://wiki.example.com".
     ALLOWED_ORIGINS: str = ""
 
+    # Public base URL the browser can reach. Used to build OIDC redirect_uri
+    # and SSO-error redirects. In dev leave as localhost:8000; in prod set to
+    # e.g. "https://wiki.example.com".
+    PUBLIC_BASE_URL: str = "http://localhost:8000"
+
+    # ── OIDC / OAuth SSO (optional) ──
+    OIDC_ENABLED: bool = False
+    OIDC_PROVIDERS: str = ""             # comma-separated: google,github,generic
+
+    # Access-control layers. Any rule that is set and does not match → 403.
+    OIDC_ALLOW_SIGNUP: bool = False      # if False, only pre-provisioned users
+    OIDC_ALLOWED_EMAILS: str = ""        # comma-separated individual whitelist
+    OIDC_ALLOWED_EMAIL_DOMAINS: str = ""  # comma-separated domain whitelist
+    OIDC_REQUIRED_GROUPS: str = ""       # IdP must return these in groups claim
+    OIDC_DEFAULT_ROLE: str = "editor"    # role for newly signed-up users
+
+    # Google
+    OIDC_GOOGLE_CLIENT_ID: str = ""
+    OIDC_GOOGLE_CLIENT_SECRET: str = ""
+    OIDC_GOOGLE_DISCOVERY: str = (
+        "https://accounts.google.com/.well-known/openid-configuration"
+    )
+
+    # GitHub (non-OIDC OAuth2; no discovery URL)
+    OIDC_GITHUB_CLIENT_ID: str = ""
+    OIDC_GITHUB_CLIENT_SECRET: str = ""
+
+    # Generic OIDC (Keycloak / Authentik / Okta / self-hosted IdP)
+    OIDC_GENERIC_NAME: str = "Company SSO"
+    OIDC_GENERIC_CLIENT_ID: str = ""
+    OIDC_GENERIC_CLIENT_SECRET: str = ""
+    OIDC_GENERIC_DISCOVERY: str = ""
+
+    # ── LDAP / Active Directory (optional) ──
+    LDAP_ENABLED: bool = False
+    LDAP_SERVER: str = ""                # must be ldaps:// unless TLS disabled
+    LDAP_TLS_VERIFY: bool = True
+    LDAP_BIND_DN: str = ""
+    LDAP_BIND_PASSWORD: str = ""
+    LDAP_USER_BASE: str = ""
+    LDAP_USER_FILTER: str = "(&(objectClass=person)(uid={username}))"
+    LDAP_ATTR_EMAIL: str = "mail"
+    LDAP_ATTR_DISPLAY_NAME: str = "displayName"
+    LDAP_DEFAULT_ROLE: str = "editor"
+
+    LDAP_SYNC_GROUPS: bool = False
+    LDAP_GROUP_BASE: str = ""
+    LDAP_GROUP_FILTER: str = "(&(objectClass=groupOfNames)(member={user_dn}))"
+    LDAP_ADMIN_GROUPS: str = ""          # CNs that grant role=admin
+
     # ── AI chat (optional, OpenAI-compatible) ──
     # Default targets Gemini's OpenAI-compatible endpoint, but any provider
     # that speaks the same wire format works (OpenAI, Ollama, Groq, DeepSeek…).

backend/app/database.py

@@ -36,6 +36,23 @@
     created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );
 
+-- SSO binding per user. A user may have zero or more identities alongside
+-- a local password (or instead of one, in which case users.password_hash
+-- is set to the sentinel '!' to disable local login while keeping the
+-- column NOT NULL).
+CREATE TABLE IF NOT EXISTS auth_identities (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id       INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    provider      TEXT    NOT NULL,
+    subject       TEXT    NOT NULL,
+    email         TEXT,
+    created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    last_login_at TIMESTAMP,
+    UNIQUE (provider, subject)
+);
+
+CREATE INDEX IF NOT EXISTS idx_auth_identities_user ON auth_identities(user_id);
+
 CREATE TABLE IF NOT EXISTS pages (
     id          INTEGER PRIMARY KEY AUTOINCREMENT,
     slug        TEXT UNIQUE NOT NULL,
@@ -187,6 +204,7 @@
     id          INTEGER PRIMARY KEY AUTOINCREMENT,
     name        TEXT UNIQUE NOT NULL,
     description TEXT DEFAULT '',
+    ldap_dn     TEXT UNIQUE,           -- non-NULL marks this group as LDAP-sourced
     created_by  INTEGER REFERENCES users(id),
     created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
 );

backend/app/main.py

@@ -4,12 +4,13 @@
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
+from starlette.middleware.sessions import SessionMiddleware
 
 from app import __version__
 from app.config import settings
 from app.database import init_db, close_db, seed_welcome_page, get_db
 from app.auth import ensure_admin_exists
-from app.routers import auth_router, pages, media, templates, search, tags, activity, bookmarks, versions, diagrams, users, comments, backup, export, trash, notifications, watch, public, dashboard, acl, groups, ai
+from app.routers import auth_router, oauth_router, pages, media, templates, search, tags, activity, bookmarks, versions, diagrams, users, comments, backup, export, trash, notifications, watch, public, dashboard, acl, groups, ai
 
 logger = logging.getLogger("justwiki")
 
@@ -42,6 +43,18 @@ def _check_security():
             "Change it in .env before deploying to production.",
             settings.ADMIN_PASS,
         )
+    # Either SSO path issues the session cookie (OIDC state/nonce/PKCE) over
+    # the wire. Without TLS marking, a passive attacker on the path can
+    # replay the short-lived state cookie. We can't force HTTPS for the
+    # operator, but we can refuse to stay quiet about the risk.
+    if (settings.OIDC_ENABLED or settings.LDAP_ENABLED) and not settings.COOKIE_SECURE:
+        if not settings.PUBLIC_BASE_URL.startswith("https://"):
+            logger.warning(
+                "OIDC/LDAP is enabled but COOKIE_SECURE=false and PUBLIC_BASE_URL "
+                "is not https. Session cookies (OAuth state/PKCE) will travel "
+                "in plaintext. Serve the app over HTTPS and set "
+                "COOKIE_SECURE=true before exposing it."
+            )
 
 
 @asynccontextmanager
@@ -126,7 +139,25 @@ def _origin_of(url: str | None) -> str | None:
     allow_headers=["*"],
 )
 
+# authlib stashes OAuth state/nonce/PKCE in the signed session cookie between
+# /login and /callback. Registered before routes so the OAuth router can read it.
+#
+# https_only follows COOKIE_SECURE, but also auto-enables when PUBLIC_BASE_URL
+# is https:// — operators running behind TLS commonly forget to flip
+# COOKIE_SECURE, and we don't want to leak an OAuth state cookie over
+# plaintext just because of a config oversight.
+_session_https_only = settings.COOKIE_SECURE or settings.PUBLIC_BASE_URL.startswith("https://")
+app.add_middleware(
+    SessionMiddleware,
+    secret_key=settings.SECRET_KEY,
+    session_cookie="justwiki_oauth",
+    same_site="lax",
+    https_only=_session_https_only,
+    max_age=600,
+)
+
 app.include_router(auth_router.router)
+app.include_router(oauth_router.router)
 app.include_router(pages.router)
 app.include_router(media.router)
 app.include_router(templates.router)

backend/app/migrations.py

@@ -71,12 +71,59 @@ async def _m005_page_is_public(db: aiosqlite.Connection) -> None:
         )
 
 
+async def _m006_auth_identities(db: aiosqlite.Connection) -> None:
+    """Create auth_identities table to record OIDC / LDAP bindings.
+
+    Fresh DBs already have it from SCHEMA_SQL; this migration handles upgrades
+    where the CREATE TABLE would otherwise never run. The index is declared
+    inside SCHEMA_SQL for fresh DBs but only gets created here for upgrades —
+    without it, ON DELETE CASCADE becomes a full-table scan per user delete.
+    """
+    await db.execute(
+        """
+        CREATE TABLE IF NOT EXISTS auth_identities (
+            id            INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id       INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+            provider      TEXT    NOT NULL,
+            subject       TEXT    NOT NULL,
+            email         TEXT,
+            created_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            last_login_at TIMESTAMP,
+            UNIQUE (provider, subject)
+        )
+        """
+    )
+    await db.execute(
+        "CREATE INDEX IF NOT EXISTS idx_auth_identities_user ON auth_identities(user_id)"
+    )
+
+
+async def _m007_groups_ldap_dn(db: aiosqlite.Connection) -> None:
+    """Add `ldap_dn` to `groups` so LDAP-mirrored groups can be reconciled.
+
+    A group with ldap_dn IS NOT NULL is considered fully managed by the LDAP
+    sync loop — user additions/removals during sync only touch those rows;
+    manually-created groups (ldap_dn IS NULL) are never pruned.
+    """
+    if not await _column_exists(db, "groups", "ldap_dn"):
+        await db.execute("ALTER TABLE groups ADD COLUMN ldap_dn TEXT")
+        # SQLite can't add UNIQUE via ALTER. A partial unique index is the
+        # idiomatic workaround and matches the semantics we want: only non-NULL
+        # DNs must be unique (multiple manual groups with NULL dn are fine).
+        await db.execute(
+            "CREATE UNIQUE INDEX IF NOT EXISTS idx_groups_ldap_dn "
+            "ON groups(ldap_dn) WHERE ldap_dn IS NOT NULL"
+        )
+
+
 MIGRATIONS: list[Migration] = [
     (1, "user_profile_columns", _m001_user_profile_columns),
     (2, "user_soft_delete", _m002_user_soft_delete),
     (3, "page_version_counter", _m003_page_version_counter),
     (4, "page_soft_delete", _m004_page_soft_delete),
     (5, "page_is_public", _m005_page_is_public),
+    (6, "auth_identities", _m006_auth_identities),
+    (7, "groups_ldap_dn", _m007_groups_ldap_dn),
 ]
 
 
@@ -91,6 +138,15 @@ async def _m005_page_is_public(db: aiosqlite.Connection) -> None:
     "CREATE INDEX IF NOT EXISTS idx_users_deleted ON users(deleted_at)",
     "CREATE INDEX IF NOT EXISTS idx_pages_deleted ON pages(deleted_at)",
     "CREATE INDEX IF NOT EXISTS idx_pages_public ON pages(slug) WHERE is_public = 1",
+    # SQLite can't express "column-level UNIQUE only when non-NULL" in a
+    # plain CREATE TABLE; the partial unique index is the standard workaround
+    # and matches what groups.ldap_dn needs.
+    "CREATE UNIQUE INDEX IF NOT EXISTS idx_groups_ldap_dn "
+    "ON groups(ldap_dn) WHERE ldap_dn IS NOT NULL",
+    # ON DELETE CASCADE on auth_identities.user_id would be a full scan
+    # without this. Declared in SCHEMA_SQL but that's skipped on upgrades
+    # where the backfill marks m006 as already applied.
+    "CREATE INDEX IF NOT EXISTS idx_auth_identities_user ON auth_identities(user_id)",
 )
 
 
@@ -147,6 +203,13 @@ async def _detect_preexisting(db: aiosqlite.Connection) -> set[int]:
         applied.add(4)
     if await _column_exists(db, "pages", "is_public"):
         applied.add(5)
+    rows = await db.execute_fetchall(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='auth_identities'"
+    )
+    if rows:
+        applied.add(6)
+    if await _column_exists(db, "groups", "ldap_dn"):
+        applied.add(7)
     return applied
 
 

backend/app/routers/auth_router.py

@@ -39,10 +39,37 @@ async def login(body: LoginRequest, request: Request, response: Response):
         "SELECT id, username, password_hash, role, display_name, email FROM users WHERE username = ? AND deleted_at IS NULL",
         (body.username,),
     )
-    if not rows or not verify_password(body.password, rows[0]["password_hash"]):
+
+    # 1. Local password path. Shell accounts (password_hash='!') always fail
+    #    this check so bcrypt can't coincidentally accept an empty / short
+    #    password; they must sign in via SSO or LDAP instead.
+    user = None
+    if rows and rows[0]["password_hash"] != "!" and verify_password(body.password, rows[0]["password_hash"]):
+        user = dict(rows[0])
+
+    # 2. LDAP fallback. The service is imported lazily so sites without LDAP
+    #    never pay the `ldap3` import cost on every login attempt.
+    if user is None and settings.LDAP_ENABLED:
+        from app.services import ldap_auth
+        try:
+            lu = await ldap_auth.authenticate(body.username, body.password)
+        except ldap_auth.LdapError as e:
+            # Configuration/connectivity problem — log but still return 401
+            # rather than 500 so a misconfigured LDAP doesn't reveal to the
+            # world that LDAP is enabled.
+            import logging
+            logging.getLogger(__name__).error("LDAP login error: %s", e)
+            lu = None
+        if lu is not None:
+            try:
+                user = await ldap_auth.provision_ldap_user(db, lu)
+            except ldap_auth.LdapError as e:
+                # Takeover guard tripped (username collision with a local user).
+                raise HTTPException(status_code=403, detail=str(e))
+
+    if user is None:
         raise HTTPException(status_code=401, detail="Invalid credentials")
 
-    user = dict(rows[0])
     token = create_token(user["id"], user["username"], user["role"])
     response.set_cookie(
         key="token",