web-app-launcher/plans/phase-2-enhanced-features/phase-1-oauth.md

Phase 1: OAuth/Authentik Integration

Status: ✅ Complete Parent plan: PLAN.md Domain: fullstack

Objective

Add OIDC/OAuth2 authentication via Authentik, including redirect/callback flows, auto-provisioning users, and admin configuration UI.

Tasks

• Task 1: Create src/lib/server/services/oauthService.ts — OIDC client setup, discovery, token exchange
• Task 2: Create src/routes/auth/oauth/authorize/+server.ts — redirect to Authentik with PKCE
• Task 3: Create src/routes/auth/oauth/callback/+server.ts — handle callback, exchange code, provision user
• Task 4: Update src/lib/server/services/userService.ts — add findOrCreateByOAuth() for auto-provisioning
• Task 5: Update src/routes/login/+page.svelte — show OAuth button when auth mode is OAUTH or BOTH
• Task 6: Update src/routes/login/+page.server.ts — load auth mode from SystemSettings
• Task 7: Update src/routes/admin/settings/+page.svelte — make OAuth config fields functional (client ID, secret, discovery URL)
• Task 8: Update src/lib/components/admin/SettingsForm.svelte — add OAuth test connection button
• Task 9: Update src/hooks.server.ts — handle OAuth sessions alongside local JWT sessions (no changes needed — existing JWT hook handles OAuth users transparently)
• Task 10: Add env vars to .env.example — OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_DISCOVERY_URL, OAUTH_REDIRECT_URI

Files to Modify/Create

• src/lib/server/services/oauthService.ts — NEW
• src/routes/auth/oauth/authorize/+server.ts — NEW
• src/routes/auth/oauth/callback/+server.ts — NEW
• src/lib/server/services/userService.ts — MODIFY
• src/routes/login/+page.svelte — MODIFY
• src/routes/login/+page.server.ts — MODIFY
• src/routes/admin/settings/+page.svelte — MODIFY
• src/lib/components/admin/SettingsForm.svelte — MODIFY
• src/hooks.server.ts — MODIFY
• .env.example — MODIFY

Acceptance Criteria

• OAuth login redirects to Authentik and returns with valid session
• New OAuth users are auto-provisioned with correct role/groups
• Existing users can link OAuth identity
• Admin can configure OAuth provider in settings
• Auth mode selector (local/oauth/both) controls which login options appear
• Login page shows appropriate buttons based on auth mode

Notes

• Use openid-client for OIDC discovery and token exchange
• Store OAuth state/nonce in HTTP-only cookies for CSRF protection
• Map Authentik groups to local groups by name
• OAuth users have nullable password field
• ⚠️ Big Bang: may not fully work until Phase 5 integration

Review Checklist

• All tasks completed
• Code follows project conventions
• No unintended side effects
• Build passes
• Tests pass (new + existing)

Handoff to Next Phase

• Installed openid-client v6.8.2 as a runtime dependency.
• OAuth flow issues local JWT tokens, so hooks.server.ts required no changes.
• New API endpoint POST /api/admin/oauth/test added for the test connection button in SettingsForm.
• findOrCreateByOAuth() syncs OAuth groups to local groups by name (groups must pre-exist locally).
• Login page conditionally renders OAuth button and/or local form based on authMode from SystemSettings.
• OIDC discovery result is cached in-memory and invalidated when the admin tests the connection.
• Phase 2 (DnD) and Phase 3 (Localization) are independent and can proceed in parallel.