docs(02-01): add Authentik provider setup and Phase 2 source audit

Task 02-01-03. Creates docs/authentik-setup.md as the load-bearing Phase 2 deliverable (D-10): a reproducible playbook for the homelab Authentik provider plus the multi-source audit that ties every Phase 2 input to a covering plan. Sections (in mandated order): - Provider — Public + PKCE S256, recipe-app client_id, RS256, single- string aud, JWKS URI, end-session endpoint, Issuer trailing slash. - Scopes — exactly `openid profile email offline_access`; explains why offline_access must be both requested AND mapped on the provider for refresh tokens (PITFALLS.md Phase 2 Pitfall 2). - Redirect URI — recipe://callback, registered byte-for-byte in Authentik + iOS Info.plist + Android <intent-filter>. - Server Env Vars — OIDC_ISSUER / OIDC_AUDIENCE / OIDC_JWKS_URL with override semantics matching Phase 1's DATABASE_URL pattern. - Logout — RP-initiated end-session sequence (D-19, D-20). - Manual UAT — UAT-01 fresh login, UAT-02 reopen with refresh, UAT-03 logout returns to login, UAT-04 curl/HTTP verification of GET /api/v1/me 200/401 cases including wrong-aud and never-log- Authorization assertion. - Source Audit — exhaustive table mapping GOAL Phase 2, REQ AUTH-01..AUTH-06, RESEARCH constraints, CONTEXT D-01..D-34, UI-SPEC, VALIDATION Wave 0, and PATTERNS file map to either this doc (✅) or a downstream Phase 2 plan (⤳). All deferred ideas listed as ✂ excluded: Universal Links/App Links, real Desktop OIDC, Wasm OIDC, Apple Sign-in, Authentik provisioning automation, per-user AuthState, modal refresh-failure UX, background refresh, two-tier logout, BuildConfig OIDC injection, real-Authentik integration tests. Verification: - grep -E 'openid profile email offline_access|PKCE S256|single-string |recipe://callback|/api/v1/me|Source Audit' docs/authentik-setup.md: hits all six tokens. - All Task 3 grep acceptance criteria PASS, including AUTH-01.*AUTH-02.*AUTH-03.*AUTH-04.*AUTH-05.*AUTH-06 on a single audit-table line and "Universal Links / App Links.*excluded".
2026-04-28 10:55:38 +02:00
parent c1cc713bbb
commit 62040d461a
1 changed files with 242 additions and 0 deletions
--- a/docs/authentik-setup.md
+++ b/docs/authentik-setup.md
@@ -0,0 +1,242 @@
+# Authentik Provider Setup — Recipe (Phase 2)
+
+> Reproducible Authentik configuration for the Recipe app. Anyone with admin access
+> to the homelab Authentik should be able to recreate the OAuth2/OIDC provider in
+> under five minutes by following this document end to end (D-10).
+>
+> Phase: `02-authentication-foundation`. Locked decisions referenced here live in
+> `.planning/phases/02-authentication-foundation/02-CONTEXT.md` (D-05 .. D-10,
+> D-19, D-21 .. D-23) and the version-controlled requirements in
+> `.planning/REQUIREMENTS.md` (AUTH-01, AUTH-02, AUTH-03, AUTH-04, AUTH-05, AUTH-06).
+
+## Provider
+
+Configure a **single OAuth2/OIDC provider** in Authentik with the following pinned settings.
+Authentik admin path: **Admin → Applications → Providers → Create → OAuth2/OpenID Provider**.
+
+| Setting | Value | Why this exact value |
+|---------|-------|----------------------|
+| Provider type | **OAuth2/OIDC, Public client** | Mobile apps cannot ship a secret per RFC 8252 (D-05). No `client_secret` is set on the provider, sent on the wire, or stored anywhere in this repo. |
+| Authorization flow | **Authorization code with PKCE S256** | PKCE S256 is the only safe pattern for native + custom-scheme redirect URIs (D-05, D-09). `plain` is forbidden. |
+| Client ID | **`recipe-app`** | Mirrors `dev.ulfrx.recipe.shared.Constants.OIDC_CLIENT_ID`. The same value is the JWT `aud` claim per D-07. |
+| Client secret | **(leave empty)** | Public client — D-05. Any non-empty value is a bug. |
+| Redirect URIs | **`recipe://callback`** (exactly, no trailing slash, no spaces) | Custom URL scheme — see [`## Redirect URI`](#redirect-uri). Byte-for-byte match with `Constants.OIDC_REDIRECT_URI` (D-09). |
+| Signing algorithm | **RS256** | Authentik default; matches `JwkProviderBuilder` expectations on the server (D-08, D-21, D-22). |
+| Signing key | RS256 asymmetric key from Authentik (auto-managed) | Public key reaches the server through the JWKS endpoint, never copied or pinned in code (D-22). |
+| Audience | **single-string** value `aud = recipe-app` (NOT array) | Authentik can emit `aud` as either an array or a single string per provider config; pin to single string and let `JWTAuth.withAudience("recipe-app")` validate against it (D-07, PITFALLS.md #7). A negative test in Plan 02-02 asserts wrong-`aud` → 401. |
+| Issuer URL | `https://auth.<your-homelab>.tld/application/o/recipe/` (trailing slash required) | Trailing slash is byte-sensitive in Authentik's OpenID metadata responses (PITFALLS.md #8). The placeholder host `auth.example.invalid` in `Constants.kt` is replaced at deploy time via env-var override on the server (`OIDC_ISSUER`) — do not commit your real homelab URL here. |
+| JWKS URI | Pulled from `<issuer>/.well-known/openid-configuration` `jwks_uri` (typically `<issuer>jwks/`) | Cached and rate-limited on the server with `JwkProviderBuilder(issuer).cached(10, 15, MINUTES).rateLimited(10, 1, MINUTES)` (D-22). |
+| End-session endpoint | Pulled from `<issuer>/.well-known/openid-configuration` `end_session_endpoint` | Required for RP-initiated logout (D-19, D-20). See [`## Logout`](#logout). |
+| Token validity | Access token ~5 min, refresh token long-lived (default Authentik) | Short access lifetime exercises the `performActionWithFreshTokens` + Ktor bearer 401 fallback paths (D-16, D-17). |
+
+After saving, bind the provider to a new **Application** (Admin → Applications → Applications → Create) called `Recipe`. The application is what Authentik users see in their My Apps / consent screens.
+
+## Scopes
+
+The app requests **exactly** these four scopes from Authentik:
+
+```
+openid profile email offline_access
+```
+
+| Scope | Purpose | Where it lands |
+|-------|---------|----------------|
+| `openid` | Marks the request as OIDC; Authentik issues an ID token | Mandatory; without it Authentik issues OAuth2-only tokens that are unusable here (D-06) |
+| `profile` | Populates the `name` / `preferred_username` claim | Maps to `users.display_name` via JIT provisioning (D-25) |
+| `email` | Populates the `email` claim | Maps to `users.email` via JIT provisioning (D-25) |
+| `offline_access` | Asks Authentik to issue a **refresh** token | AUTH-04 (session persists across launches via refresh) is impossible without it. Authentik issues no refresh token unless `offline_access` is BOTH requested by the client AND mapped/allowed in the provider's scope mapping (D-06, PITFALLS.md Phase 2 Pitfall 2). |
+
+**Authentik provider configuration must explicitly map the `offline_access` scope** so the
+provider returns a refresh token. Newer Authentik versions add it by default; older ones
+require explicit creation under **Customization → Property Mappings → OAuth2 / OpenID Scope
+Mapping**.
+
+## Redirect URI
+
+The app uses a **custom URL scheme**:
+
+```
+recipe://callback
+```
+
+This single URI must be registered three times — byte-for-byte identical, no trailing
+slash, no query parameters. Drift between any of these three places produces silent OAuth
+redirect failures (D-09).
+
+| Where | Mechanism | Phase 2 plan that lands it |
+|-------|-----------|----------------------------|
+| Authentik provider | Redirect URIs textbox (one line) | This document (Plan 02-01) |
+| iOS | `iosApp/iosApp/Info.plist` `CFBundleURLTypes` → `CFBundleURLSchemes` array containing exactly `recipe` | Plan 02-05 (iOS AppAuth actual) |
+| Android | `composeApp/src/androidMain/AndroidManifest.xml` `<intent-filter>` on AppAuth's `RedirectUriReceiverActivity` with `android:scheme="recipe"` and `android:host="callback"` | Plan 02-04 (Android AppAuth actual). Plan 02-01 already supplies the `appAuthRedirectScheme=recipe` manifest placeholder so the AppAuth dependency merges cleanly without yet wiring the receiver. |
+
+PKCE S256 + AppAuth's state/nonce handling makes the well-known custom-scheme
+interception attack non-exploitable in practice. **Universal Links / App Links are
+explicitly excluded** from v1 — see [`## Source Audit`](#source-audit).
+
+## Server Env Vars
+
+The Ktor server reads OIDC configuration from `application.conf` with env-var overrides
+(D-12, mirrors Phase 1 D-16's `DATABASE_URL` pattern). Set these on the homelab deploy
+target before booting the server:
+
+| Variable | Required | Example value | Notes |
+|----------|----------|---------------|-------|
+| `OIDC_ISSUER` | yes | `https://auth.example.invalid/application/o/recipe/` | Trailing slash required (PITFALLS.md #8). Must equal Authentik's issuer URL byte-for-byte. |
+| `OIDC_AUDIENCE` | yes | `recipe-app` | Equal to the provider's Client ID; validated as a **single string** (D-07). |
+| `OIDC_JWKS_URL` | optional | `https://auth.example.invalid/application/o/recipe/jwks/` | Optional — derived from `<OIDC_ISSUER>/.well-known/openid-configuration` if unset. Set explicitly only when Authentik puts JWKS at a non-standard path. |
+
+Plan 02-02 wires these into `application.conf` and the `JwkProviderBuilder`. They are NOT
+read by the client — the client OIDC config is hardcoded in
+`shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/Constants.kt` per D-11 (single-
+environment v1 acceptance from PITFALLS.md tech-debt table).
+
+## Logout
+
+Logout is **RP-initiated end-session** (D-19, D-20). Tapping "Wyloguj się" performs both
+of these atomically, in this order:
+
+1. Call Authentik's `end_session_endpoint` (advertised by `<issuer>/.well-known/openid-configuration`) with the user's `id_token_hint`. AppAuth's `EndSessionRequest` API drives this on both mobile platforms (D-20).
+2. Delete the persisted `AuthState` blob from secure storage (Keychain on iOS, EncryptedSharedPreferences on Android per D-13).
+
+If step 1 fails (network unreachable, Authentik down), step 2 still runs so the user
+isn't trapped in a half-logged-out state — correct semantics for a shared household
+device. Local-only logout would fail AUTH-05 because the next "Zaloguj się" tap would
+silently SSO instead of forcing fresh credentials.
+
+To support this, the Authentik provider's **end-session endpoint must be reachable** from
+the device — confirm via `curl -I "<issuer>/.well-known/openid-configuration"` and
+checking that the JSON response contains `end_session_endpoint`.
+
+## Manual UAT
+
+These checks must pass on a real iOS device or simulator before Phase 2 is signed off
+(per `02-VALIDATION.md`'s Manual-Only Verifications). They cover the surface unit tests
+cannot reach: real Authentik, real browser handoff, real Keychain.
+
+### UAT-01 — Fresh iOS login (AUTH-01)
+
+1. Wipe app data: delete the app from the simulator/device.
+2. Reinstall via `./gradlew :composeApp:iosDeployIPhone…` or Xcode.
+3. Tap **"Zaloguj się przez Authentik"**.
+4. Confirm the system browser (`ASWebAuthenticationSession`) opens at Authentik's hosted login page.
+5. Authenticate. Confirm Authentik consent screen lists `openid profile email offline_access`.
+6. Confirm the app returns to foreground via `recipe://callback` and renders `Witaj, {displayName}!` with the partner's actual display name.
+7. **Failure modes to verify visually:** cancelling the system browser shows "Logowanie anulowane. Spróbuj ponownie." inline.
+
+### UAT-02 — Reopen with refresh (AUTH-04)
+
+1. Sign in via UAT-01.
+2. In Authentik, set the provider's access-token lifetime to ~60 seconds (or wait the default).
+3. Backgroud the app for ~2 minutes; relaunch.
+4. Confirm the app returns directly to `Witaj, {displayName}!` with no login prompt — the AppAuth `performActionWithFreshTokens` path silently exchanged the refresh token (D-16, D-17).
+
+### UAT-03 — Logout returns to login (AUTH-05)
+
+1. Sign in via UAT-01.
+2. Tap **"Wyloguj się"**.
+3. Confirm the app returns to the LoginScreen.
+4. Tap "Zaloguj się przez Authentik" again. Confirm Authentik **prompts for credentials** (no silent SSO) — proves the end-session call succeeded.
+5. **Network-failure variant:** disconnect from network, tap "Wyloguj się", confirm app still returns to LoginScreen and the local AuthState is gone (relaunching does not auto-sign-in).
+
+### UAT-04 — `/api/v1/me` validation (AUTH-03)
+
+This is the only UAT step performed via terminal, not the app. It validates the server
+side of the boundary independently of mobile UI bugs.
+
+1. Run the server locally or hit the homelab. Capture a valid access token (e.g., copy from `AuthState` JSON via the iOS debugger immediately after UAT-01, or use `curl` directly against Authentik's token endpoint with the same client_id).
+2. Confirm:
+   ```bash
+   curl -i -H "Authorization: Bearer $TOKEN" https://api.<homelab>/api/v1/me
+   # expect: HTTP/1.1 200 OK; body matches MeResponse {"id":..., "sub":..., "email":..., "displayName":...}
+   ```
+3. Confirm:
+   ```bash
+   curl -i https://api.<homelab>/api/v1/me
+   # expect: HTTP/1.1 401 Unauthorized
+   ```
+4. Confirm wrong-audience rejection by minting a JWT with `aud != recipe-app` (use the test JWKS Plan 02-02 ships):
+   ```bash
+   curl -i -H "Authorization: Bearer $WRONG_AUD_TOKEN" https://api.<homelab>/api/v1/me
+   # expect: HTTP/1.1 401 Unauthorized
+   ```
+5. Confirm logs do **not** contain the token body. The custom `CallLogging` filter must redact the `Authorization` header (D-23).
+
+## Source Audit
+
+This document is the Phase 2 anchor for "every locked source is honored". The table below
+asserts that every Phase 2 input — goal, requirement, research finding, decision, UI
+spec, validation gate, and pattern map — is either covered here or in a downstream Phase
+2 plan. Markers: ✅ covered in this document, ⤳ covered in a downstream plan (with
+plan number), ✂ explicitly deferred (see end of section).
+
+| Source | Item | Coverage |
+|--------|------|----------|
+| GOAL | Phase 2 goal: end-to-end OIDC+PKCE login with server JWT validation and JIT users | ✅ Provider + Scopes + Redirect URI + Server Env Vars + Manual UAT |
+| REQ | **AUTH-01** sign in via Authentik OIDC + PKCE | ✅ Provider; ⤳ 02-04 (Android AppAuth) + 02-05 (iOS AppAuth) |
+| REQ | **AUTH-02** secure token storage | ⤳ 02-03 (common contract) + 02-04 (Android EncryptedSharedPreferences) + 02-05 (iOS Keychain) |
+| REQ | **AUTH-03** server JWT validation via JWKS | ✅ Provider (RS256, single-string aud, JWKS); ⤳ 02-02 (Ktor JWT install + tests) |
+| REQ | **AUTH-04** session persists across launches via refresh | ✅ Scopes (`offline_access`); ⤳ 02-03 (AuthSession refresh wiring) + Manual UAT-02 |
+| REQ | **AUTH-05** logout returns to login | ✅ Logout section; ⤳ 02-04/02-05 (AppAuth end-session per platform) + Manual UAT-03 |
+| REQ | **AUTH-06** JIT user provisioning by `sub` | ⤳ 02-02 (`V1__users.sql` + upsert by sub + `/api/v1/me`) |
+| RESEARCH | Standard stack: AppAuth, Ktor JWT, multiplatform-settings, Exposed DSL, Flyway | ✅ Server Env Vars (Ktor); ⤳ 02-01 catalog wiring (this plan, task 2) + per-platform plans |
+| RESEARCH | Open Questions resolved: Android secure storage = EncryptedSharedPreferences behind `SecureAuthStateStore` seam | ⤳ 02-03 (seam) + 02-04 (Android impl) |
+| RESEARCH | Open Question resolved: Exposed `newSuspendedTransaction` import verified at impl time | ⤳ 02-02 |
+| RESEARCH | Open Question resolved: Ktor stays at 3.4.1 (no patch bump) | ✅ Task 2 catalog keeps `ktor = "3.4.1"` |
+| CONTEXT | **D-01** AppAuth on both mobile platforms via expect/actual `OidcClient` | ⤳ 02-03 (expect) + 02-04 (Android actual) + 02-05 (iOS actual) |
+| CONTEXT | **D-02** JVM `actual` is `DEV_AUTH_TOKEN` env-var stub | ⤳ 02-03 |
+| CONTEXT | **D-03** Wasm `actual` is `NotImplementedError("Wasm OIDC: v2")` | ⤳ 02-03 |
+| CONTEXT | **D-04** `OidcClient.login()` / `.refresh()` are `suspend` | ⤳ 02-03 |
+| CONTEXT | **D-05** Public + PKCE S256 | ✅ Provider |
+| CONTEXT | **D-06** scopes `openid profile email offline_access` | ✅ Scopes |
+| CONTEXT | **D-07** single-string `aud` = `client_id` | ✅ Provider |
+| CONTEXT | **D-08** RS256 signing | ✅ Provider |
+| CONTEXT | **D-09** redirect URI `recipe://callback` | ✅ Redirect URI |
+| CONTEXT | **D-10** this document is a Phase 2 deliverable | ✅ this document |
+| CONTEXT | **D-11** client OIDC config in `shared/commonMain/Constants.kt` | ✅ Server Env Vars (relationship spelled out); ⤳ 02-01 task 1 (Constants.kt landed) |
+| CONTEXT | **D-12** server OIDC config via env vars | ✅ Server Env Vars |
+| CONTEXT | **D-13** persist full AppAuth `AuthState` JSON via `multiplatform-settings` | ⤳ 02-03 + 02-04 + 02-05 |
+| CONTEXT | **D-14** iOS Keychain `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | ⤳ 02-05 |
+| CONTEXT | **D-15** one AuthState blob per app install | ⤳ 02-03 |
+| CONTEXT | **D-16** proactive refresh via `performActionWithFreshTokens` | ⤳ 02-04 + 02-05 |
+| CONTEXT | **D-17** Ktor bearer `refreshTokens` 401 fallback | ⤳ 02-03 |
+| CONTEXT | **D-18** silent refresh-failure transition | ⤳ 02-03 |
+| CONTEXT | **D-19** RP-initiated end-session | ✅ Logout |
+| CONTEXT | **D-20** AppAuth `EndSessionRequest` drives logout | ✅ Logout; ⤳ 02-04 + 02-05 |
+| CONTEXT | **D-21** Ktor `jwt("authentik")` install with leeway 30s and `sub` validation | ⤳ 02-02 |
+| CONTEXT | **D-22** JWKS provider cache 10 / 15min, rate limit 10/min | ⤳ 02-02 |
+| CONTEXT | **D-23** never log Authorization header / token bodies | ✅ Manual UAT-04 step 5; ⤳ 02-02 (server filter) + 02-03 (client logger discipline) |
+| CONTEXT | **D-24** ship `V1__users.sql` migration | ⤳ 02-02 |
+| CONTEXT | **D-25** JIT upsert by `sub`, update email/display_name | ⤳ 02-02 |
+| CONTEXT | **D-26** Exposed DSL only, `newSuspendedTransaction` | ⤳ 02-02 |
+| CONTEXT | **D-27** `/api/v1/me` returns `MeResponse` | ✅ Manual UAT-04; ⤳ 02-01 task 1 (DTO) + 02-02 (route) |
+| CONTEXT | **D-28** `AuthState` sealed shape with `householdId: HouseholdId? = null` | ⤳ 02-03 |
+| CONTEXT | **D-29** `AuthSession` Koin singleton in `authModule` | ⤳ 02-03 + 02-06 |
+| CONTEXT | **D-30** auth gate in `App()` | ⤳ 02-06 (UI) |
+| CONTEXT | **D-31** minimal login screen | ⤳ 02-06 |
+| CONTEXT | **D-32** inline login error states | ⤳ 02-06 |
+| CONTEXT | **D-33** post-login placeholder `Witaj, {displayName}!` | ⤳ 02-06 |
+| CONTEXT | **D-34** Compose Resources strings from day 1 | ⤳ 02-06 |
+| UI-SPEC | Auth screen contract: SplashScreen / LoginScreen / PostLoginPlaceholderScreen | ⤳ 02-06 |
+| VALIDATION | Wave 0 tests: AuthJwtTest, MeRouteTest, AuthSessionTest, SecureAuthStateStoreTest | ⤳ 02-02 (server tests) + 02-03 (client tests) |
+| VALIDATION | Manual UAT checklist in `docs/authentik-setup.md` | ✅ Manual UAT |
+| PATTERNS | File map: shared DTO/Constants location, Koin authModule, Ktor JWT install, Exposed table, AppAuth platform actuals | ⤳ 02-01 task 1 (shared) + 02-02 (server) + 02-03 (client common) + 02-04 (Android) + 02-05 (iOS) + 02-06 (UI) |
+
+### Deferred (excluded from Phase 2)
+
+These are explicitly out of scope for v1 per `.planning/phases/02-authentication-foundation/02-CONTEXT.md` § Deferred Ideas. Listed here so the audit makes the exclusions traceable.
+
+- **Universal Links / App Links** — excluded; rely on `recipe://callback` custom scheme. Revisit only if app gains broader distribution beyond the household or if Apple/Google deprecate custom-scheme OIDC redirects.
+- **Real Desktop OIDC** — JVM target ships a `DEV_AUTH_TOKEN` env-var stub (D-02). Loopback-redirect implementation deferred until Desktop becomes a release surface.
+- **Wasm OIDC implementation** — `wasmJs` actual throws `NotImplementedError`. Browser-redirect flow deferred until Wasm becomes a release surface.
+- **Apple Sign-in as a first-class button** — Authentik can federate Apple upstream if ever desired.
+- **Authentik provisioning automation (Terraform/Ansible)** — this document is the manual reproduction playbook; automation deferred post-v1.
+- **JWT validation tests against a real Authentik instance** — Phase 2 ships unit/integration tests with hand-crafted JWTs. Real-Authentik integration tests deferred to Phase 11 (deployment).
+- **BuildConfig-style Gradle injection of OIDC config** — `Constants.kt` is the v1 single-environment acceptance per PITFALLS.md tech-debt table.
+- **Per-user persisted `AuthState`** — one user per install is the v1 model.
+- **Modal/toast for refresh-failure UX** — silent transition ships in v1 (D-18).
+- **Background token refresh** — v1 has no background work.
+- **"Wyloguj się i zapomnij sesję" two-tier logout** — single RP-initiated logout only.
+
+---
+
+*Phase: `02-authentication-foundation` · Plan: `02-01` · Last updated: 2026-04-28*