homelabstack/plans/homelab-improvements/tasks/TB-006-authentik-forward-auth.md

TB-006 — Authentik SSO at the edge

Status: batch 1 deployed (2026-06-10) — admin sites live; batches 2–3 pending
Your call: Tweak → Do it (2026-06-10)

---

Talk first

Stop. Don't read Reference until we've talked. In chat, say "let's do TB-006" or "authentik on admin uis".

In one sentence: Every site that already shows its own login screen should authenticate through Authentik instead — without breaking webhooks, API keys, or Overseerr/Plex for friends.

Why it came up: LAN-only IP checks aren't the same as identity — Authentik is already running for famapp.

Scope (decided 2026-06-10)

In: All Caddy-proxied sites with an app login UI → Caddy forward_auth to Authentik (or keep native OIDC where already wired, e.g. famapp).

Out / untouched:

• Overseerr (requests.ginnoir.com) — friends use Plex accounts; leave as-is.
• Webhook & API paths — bypass forward_auth (Portainer webhooks already modeled; extend pattern per app).
• Static / no login — 5etools, pf2e, ffttsystems, romhacks wiki files, etc.

Explicitly out (confirmed):

• Obsidian/CouchDB — tailnet-only (TB-005); LiveSync stays on CouchDB basic auth.
• Foundry / Foundry2 — players use Foundry accounts; no Authentik.
• Overseerr — Plex login for friends.

Public apps — Authentik for human login, bypass for machine/public traffic:

Site	Authentik on	Bypass (stay open)
files (ownCloud)	Web UI / admin	Public share links (/s/*, /index.php/s/*); WebDAV if used by clients
freshrss	Web UI	Feed cron is in-container (no bypass needed); Reader/Fever/Google API paths use API password
ntfy	Web UI / account mgmt	Topic publish/subscribe (POST/GET topic paths, /v1/*); Vigilant + famapp push must keep working
resume	Builder / dashboard / login	Public resume pages (e.g. /ginnoir/resume); MinIO object GETs on storage.j-costa.com if public

Your options

Option	Meaning
Do it	We're doing this — I'll implement or walk you through it
Later	Keep on the list, not now
Drop	Remove from plan — totally fine
Tweak	Change scope; tell me how

What we decided

Decision	Do it — batch 1 admin deployed; batches 2–3 pending
Notes	Out: obsidian, foundry×2, overseerr. Batch 1: homarr native OIDC done; rest split native OAuth vs forward_auth+disable local auth (2026-06-11). Portainer needs one-time OAuth in UI; Plane needs god-mode OIDC. Push repo to persist.
Date	2026-06-10 (batch 1 deployed)

---

Reference (only open if we're doing it)

Stack / files

Caddyfile + Authentik UI

If we do it — rough steps

1. Authentik embedded outpost + proxy provider(s) on edge
2. Caddy (authentik_auth) snippet — forward_auth authentik-server:9000 with trusted headers
3. Roll out site-by-site; per-site handle bypasses for webhooks/API
4. Important: forward_auth only gates the edge — apps still show their own login unless you add native OIDC/OAuth (famapp/homarr pattern) or disable local auth (e.g. code-server --auth none). Homarr switched to native OIDC 2026-06-11.
5. Batch 1 rest (2026-06-11): BookStack/Gitea/MinIO/Portainer/Plane → native OAuth2 providers; code/uptime/kopia/registry-ui/dbx/vault → forward_auth with local auth disabled where possible. Portainer: one-time OAuth setup in Settings → Authentication (see setup-batch1-oidc.py output). Plane: god-mode at /god-mode/authentication/oidc.

Rollout batches

Batch	Sites
1 — Admin	portainer, code, registry-ui, vault, minio, homarr, uptime, backup/kopia, gitea, dbx, bookstack, plane
2 — Media	sonarr, radarr, bazarr, prowlarr, tautulli, qbit, deluge, nzbget, whisparr, stash
3 — Public + login	files, freshrss, ntfy, resume (with bypass tables above)
4 — Other internal	romm, router UI
Skip	famapp (OIDC done), auth.ginnoir.com, overseerr, obsidian, foundry×2, static sites

Done when

• Batch 1 admin sites require Authentik before app UI loads (or native OAuth equivalent)
• Homarr native OIDC (no double login)
• BookStack, Gitea, MinIO console → native Authentik OAuth/OIDC
• code-server, uptime, kopia → forward_auth only (local auth disabled)
• registry-ui, dbx, vault → forward_auth at edge
• Portainer OAuth configured in Settings → Authentication (provider created; UI step pending)
• Plane OIDC configured in god-mode (provider created; UI step pending)
• Portainer git webhooks still work (bypass path)
• Gitea /api/* + .git and Vault /v1/* bypass forward_auth
• Batch 2 media sites
• Batch 3 public apps (ownCloud shares, FreshRSS, ntfy, resume)
• ownCloud share links work without Authentik session
• FreshRSS still refreshes feeds; Vigilant/famapp still publish to ntfy
• Public resume pages still viewable without Authentik
• Overseerr unchanged for Plex friends