Add Authentik OAuth/OIDC SSO, email change, and setup docs

Phase 18 changes:

OAuth/OIDC SSO (Authorization Code + PKCE):
- alembic/versions/0015_add_oauth_fields.py: add oauth_sub UNIQUE column,
  drop NOT NULL on password_hash
- src/fabledassistant/services/oauth.py: OIDC discovery (cached), build_auth_url,
  exchange_code, get_userinfo, find_or_create_oauth_user (sub→email auto-link→create)
- src/fabledassistant/routes/auth.py: GET /api/auth/oauth/login and
  GET /api/auth/oauth/callback; LOCAL_AUTH_ENABLED guards on login/register;
  /api/auth/status now returns oauth_enabled + local_auth_enabled
- src/fabledassistant/config.py: OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET,
  OIDC_SCOPES, LOCAL_AUTH_ENABLED, oidc_enabled() classmethod
- src/fabledassistant/models/user.py: password_hash nullable, oauth_sub field,
  has_password bool in to_dict()
- src/fabledassistant/services/auth.py: create_user accepts password=None +
  oauth_sub kwarg; authenticate returns None for OAuth-only users;
  add get_user_by_oauth_sub, link_oauth_sub, update_user_email
- frontend: AuthStatus + User types updated; auth store exposes oauthEnabled +
  localAuthEnabled; LoginView shows SSO button / hides password form accordingly

Email change:
- PUT /api/auth/email: requires password confirmation for local-auth users,
  skips check for OAuth-only users; enforces email uniqueness
- SettingsView.vue: new Email Address section pre-filled with current email,
  updates authStore.user in-place on success

Docs:
- docs/oauth-setup.md: step-by-step Authentik provider setup, example
  docker-compose env vars, account linking explanation, per-provider issuer URL table

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/fabledassistant/config.py

@@ -45,3 +45,14 @@ class Config:
     SMTP_USE_TLS: bool = os.environ.get("SMTP_USE_TLS", "true").lower() in ("1", "true", "yes")
     BASE_URL: str = os.environ.get("BASE_URL", "http://localhost:5000").rstrip("/")
     TRUST_PROXY_HEADERS: bool = os.environ.get("TRUST_PROXY_HEADERS", "").lower() in ("1", "true", "yes")
+
+    # OIDC / OAuth2 SSO (e.g. Authentik)
+    OIDC_ISSUER: str = os.environ.get("OIDC_ISSUER", "")
+    OIDC_CLIENT_ID: str = os.environ.get("OIDC_CLIENT_ID", "")
+    OIDC_CLIENT_SECRET: str = _read_secret("OIDC_CLIENT_SECRET", "OIDC_CLIENT_SECRET_FILE", "")
+    OIDC_SCOPES: str = os.environ.get("OIDC_SCOPES", "openid profile email")
+    LOCAL_AUTH_ENABLED: bool = os.environ.get("LOCAL_AUTH_ENABLED", "true").lower() not in ("0", "false", "no")
+
+    @classmethod
+    def oidc_enabled(cls) -> bool:
+        return bool(cls.OIDC_ISSUER and cls.OIDC_CLIENT_ID and cls.OIDC_CLIENT_SECRET)

src/fabledassistant/models/user.py

@@ -12,7 +12,8 @@ class User(Base):
     id: Mapped[int] = mapped_column(primary_key=True)
     username: Mapped[str] = mapped_column(Text, unique=True, nullable=False)
     email: Mapped[str | None] = mapped_column(Text, nullable=True)
-    password_hash: Mapped[str] = mapped_column(Text, nullable=False)
+    password_hash: Mapped[str | None] = mapped_column(Text, nullable=True)
+    oauth_sub: Mapped[str | None] = mapped_column(Text, unique=True, nullable=True)
     role: Mapped[str] = mapped_column(Text, nullable=False, default="user")
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
@@ -29,4 +30,5 @@ class User(Base):
             "email": self.email,
             "role": self.role,
             "created_at": self.created_at.isoformat(),
+            "has_password": self.password_hash is not None,
         }

src/fabledassistant/routes/auth.py

@@ -1,6 +1,10 @@
 import asyncio
+import base64
+import hashlib
+import os
+import secrets
 
-from quart import Blueprint, g, jsonify, request, session
+from quart import Blueprint, g, jsonify, redirect, request, session
 
 from fabledassistant.auth import login_required, get_current_user_id
 from fabledassistant.config import Config
@@ -17,7 +21,9 @@ from fabledassistant.services.auth import (
     is_registration_open,
     register_with_invitation,
     reset_password_with_token,
+    update_user_email,
     validate_invitation_token,
+    verify_password,
 )
 from fabledassistant.services.logging import log_audit
 from fabledassistant.services.notifications import (
@@ -26,6 +32,12 @@ from fabledassistant.services.notifications import (
     send_password_reset_success_email,
 )
 from fabledassistant.services.email import get_base_url, is_smtp_configured
+from fabledassistant.services.oauth import (
+    build_auth_url,
+    exchange_code,
+    get_userinfo,
+    find_or_create_oauth_user,
+)
 
 auth_bp = Blueprint("auth", __name__, url_prefix="/api/auth")
 
@@ -41,6 +53,8 @@ def _client_ip() -> str:
 
 @auth_bp.route("/register", methods=["POST"])
 async def register():
+    if not Config.LOCAL_AUTH_ENABLED:
+        return jsonify({"error": "Local authentication is disabled. Please use SSO."}), 403
     if await is_rate_limited(f"register:{_client_ip()}", max_requests=5, window_seconds=300):
         return jsonify({"error": "Too many registration attempts. Try again later."}), 429
     if not await is_registration_open():
@@ -68,6 +82,8 @@ async def register():
 
 @auth_bp.route("/login", methods=["POST"])
 async def login():
+    if not Config.LOCAL_AUTH_ENABLED:
+        return jsonify({"error": "Local authentication is disabled. Please use SSO."}), 403
     if await is_rate_limited(f"login:{_client_ip()}", max_requests=10, window_seconds=60):
         return jsonify({"error": "Too many login attempts. Try again later."}), 429
     data = await request.get_json()
@@ -146,6 +162,37 @@ async def update_password():
     return jsonify({"status": "ok"})
 
 
+@auth_bp.route("/email", methods=["PUT"])
+@login_required
+async def update_email():
+    data = await request.get_json()
+    new_email = (data.get("email") or "").strip().lower() or None
+    password = data.get("password") or ""
+
+    uid = get_current_user_id()
+    user = await get_user_by_id(uid)
+    if not user:
+        return jsonify({"error": "User not found"}), 404
+
+    # Require password confirmation only for local-auth users
+    if user.password_hash is not None:
+        if not password:
+            return jsonify({"error": "Password is required to change your email"}), 400
+        if not verify_password(password, user.password_hash):
+            return jsonify({"error": "Incorrect password"}), 403
+
+    # Check the new email isn't taken by a different account
+    if new_email:
+        existing = await get_user_by_email(new_email)
+        if existing and existing.id != uid:
+            return jsonify({"error": "Email already in use by another account"}), 409
+
+    await update_user_email(uid, new_email)
+    await log_audit("email_change", user_id=uid, username=user.username, ip_address=_client_ip())
+    updated = await get_user_by_id(uid)
+    return jsonify(updated.to_dict())
+
+
 @auth_bp.route("/forgot-password", methods=["POST"])
 async def forgot_password():
     if await is_rate_limited(f"forgot:{_client_ip()}", max_requests=5, window_seconds=300):
@@ -245,4 +292,59 @@ async def register_with_invite():
 async def status():
     count = await get_user_count()
     reg_open = await is_registration_open()
-    return jsonify({"has_users": count > 0, "registration_open": reg_open})
+    return jsonify({
+        "has_users": count > 0,
+        "registration_open": reg_open,
+        "oauth_enabled": Config.oidc_enabled(),
+        "local_auth_enabled": Config.LOCAL_AUTH_ENABLED,
+    })
+
+
+@auth_bp.route("/oauth/login", methods=["GET"])
+async def oauth_login():
+    if not Config.oidc_enabled():
+        return jsonify({"error": "SSO is not configured"}), 404
+
+    state = secrets.token_hex(32)
+    code_verifier = secrets.token_urlsafe(64)
+
+    digest = hashlib.sha256(code_verifier.encode()).digest()
+    code_challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+
+    session["oauth_state"] = state
+    session["oauth_code_verifier"] = code_verifier
+
+    url = await build_auth_url(state, code_challenge)
+    return redirect(url)
+
+
+@auth_bp.route("/oauth/callback", methods=["GET"])
+async def oauth_callback():
+    error = request.args.get("error")
+    code = request.args.get("code")
+    state = request.args.get("state")
+
+    stored_state = session.pop("oauth_state", None)
+    code_verifier = session.pop("oauth_code_verifier", None)
+
+    if error or not code or state != stored_state:
+        return redirect("/login?error=oauth")
+
+    redirect_uri = Config.BASE_URL.rstrip("/") + "/api/auth/oauth/callback"
+    try:
+        token_response = await exchange_code(code, redirect_uri, code_verifier)
+        claims = await get_userinfo(token_response["access_token"])
+    except Exception:
+        return redirect("/login?error=oauth")
+
+    sub = claims.get("sub", "")
+    email = claims.get("email", "")
+    preferred_username = claims.get("preferred_username", "")
+
+    if not sub:
+        return redirect("/login?error=oauth")
+
+    user = await find_or_create_oauth_user(sub, email, preferred_username)
+    session["user_id"] = user.id
+    await log_audit("oauth_login", user_id=user.id, username=user.username, ip_address=_client_ip())
+    return redirect("/")

src/fabledassistant/services/auth.py

@@ -31,7 +31,10 @@ async def get_user_count() -> int:
 
 
 async def create_user(
-    username: str, password: str, email: str | None = None
+    username: str,
+    password: str | None,
+    email: str | None = None,
+    oauth_sub: str | None = None,
 ) -> User:
     user_count = await get_user_count()
     role = "admin" if user_count == 0 else "user"
@@ -40,7 +43,8 @@ async def create_user(
         user = User(
             username=username,
             email=email,
-            password_hash=hash_password(password),
+            password_hash=hash_password(password) if password is not None else None,
+            oauth_sub=oauth_sub,
             role=role,
         )
         session.add(user)
@@ -82,7 +86,12 @@ async def authenticate(username: str, password: str) -> User | None:
             select(User).where(User.username == username)
         )
         user = result.scalars().first()
-        if user and verify_password(password, user.password_hash):
+        if user is None:
+            return None
+        if user.password_hash is None:
+            # OAuth-only user — cannot use password login
+            return None
+        if verify_password(password, user.password_hash):
             return user
         return None
 
@@ -157,6 +166,30 @@ async def set_registration_open(admin_user_id: int, open: bool) -> None:
     await set_setting(admin_user_id, "registration_open", "true" if open else "false")
 
 
+async def update_user_email(user_id: int, email: str | None) -> None:
+    async with async_session() as session:
+        user = await session.get(User, user_id)
+        if user:
+            user.email = email
+            await session.commit()
+
+
+async def get_user_by_oauth_sub(sub: str) -> User | None:
+    async with async_session() as session:
+        result = await session.execute(
+            select(User).where(User.oauth_sub == sub)
+        )
+        return result.scalars().first()
+
+
+async def link_oauth_sub(user_id: int, sub: str) -> None:
+    async with async_session() as session:
+        await session.execute(
+            update(User).where(User.id == user_id).values(oauth_sub=sub)
+        )
+        await session.commit()
+
+
 async def get_user_by_email(email: str) -> User | None:
     async with async_session() as session:
         result = await session.execute(

src/fabledassistant/services/oauth.py

@@ -0,0 +1,124 @@
+import logging
+import urllib.parse
+
+import httpx
+
+from fabledassistant.config import Config
+from fabledassistant.models import async_session
+from fabledassistant.models.user import User
+from sqlalchemy import select
+
+logger = logging.getLogger(__name__)
+
+_oidc_config: dict | None = None
+
+
+async def get_oidc_config() -> dict:
+    global _oidc_config
+    if _oidc_config is not None:
+        return _oidc_config
+
+    discovery_url = Config.OIDC_ISSUER.rstrip("/") + "/.well-known/openid-configuration"
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(discovery_url, follow_redirects=True)
+        resp.raise_for_status()
+        _oidc_config = resp.json()
+    logger.info("OIDC config loaded from %s", discovery_url)
+    return _oidc_config
+
+
+async def build_auth_url(state: str, code_challenge: str) -> str:
+    oidc = await get_oidc_config()
+    redirect_uri = Config.BASE_URL.rstrip("/") + "/api/auth/oauth/callback"
+    params = {
+        "response_type": "code",
+        "client_id": Config.OIDC_CLIENT_ID,
+        "redirect_uri": redirect_uri,
+        "scope": Config.OIDC_SCOPES,
+        "state": state,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+    }
+    return oidc["authorization_endpoint"] + "?" + urllib.parse.urlencode(params)
+
+
+async def exchange_code(code: str, redirect_uri: str, code_verifier: str) -> dict:
+    oidc = await get_oidc_config()
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            oidc["token_endpoint"],
+            data={
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "client_id": Config.OIDC_CLIENT_ID,
+                "client_secret": Config.OIDC_CLIENT_SECRET,
+                "code_verifier": code_verifier,
+            },
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def get_userinfo(access_token: str) -> dict:
+    oidc = await get_oidc_config()
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(
+            oidc["userinfo_endpoint"],
+            headers={"Authorization": f"Bearer {access_token}"},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def find_or_create_oauth_user(
+    sub: str, email: str, preferred_username: str
+) -> User:
+    async with async_session() as session:
+        # 1. Look up by oauth_sub
+        result = await session.execute(select(User).where(User.oauth_sub == sub))
+        user = result.scalars().first()
+        if user:
+            return user
+
+        # 2. Look up by email — auto-link
+        if email:
+            from sqlalchemy import func
+            result = await session.execute(
+                select(User).where(func.lower(User.email) == email.lower())
+            )
+            user = result.scalars().first()
+            if user:
+                user.oauth_sub = sub
+                await session.commit()
+                await session.refresh(user)
+                logger.info(
+                    "Linked OAuth sub %s to existing user %d (%s) via email",
+                    sub, user.id, user.username,
+                )
+                return user
+
+        # 3. Create new user — pick a non-colliding username
+        base_username = preferred_username or (email.split("@")[0] if email else "user")
+        candidate = base_username
+        suffix = 2
+        while True:
+            result = await session.execute(
+                select(User).where(User.username == candidate)
+            )
+            if not result.scalars().first():
+                break
+            candidate = f"{base_username}_{suffix}"
+            suffix += 1
+
+        user = User(
+            username=candidate,
+            email=email or None,
+            password_hash=None,
+            oauth_sub=sub,
+        )
+        session.add(user)
+        await session.commit()
+        await session.refresh(user)
+        logger.info("Auto-provisioned OAuth user %d (%s) for sub %s", user.id, user.username, sub)
+        return user