# Phase 1: OAuth/Authentik Integration

**Status:** ⬜ Not Started
**Parent plan:** [PLAN.md](./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
- [ ] 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
<!-- Filled in by the implementation agent after completing this phase. -->