# 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) |

---

<details>
<summary>Reference (only open if we're doing it)</summary>

### 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

- [x] Batch 1 admin sites require Authentik before app UI loads (or native OAuth equivalent)
- [x] Homarr native OIDC (no double login)
- [x] BookStack, Gitea, MinIO console → native Authentik OAuth/OIDC
- [x] code-server, uptime, kopia → forward_auth only (local auth disabled)
- [x] 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)
- [x] Portainer git webhooks still work (bypass path)
- [x] 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

</details>