From bd4604cdcce2a2a1fa5d196f1f816f0ecbce5139 Mon Sep 17 00:00:00 2001
From: Petru Paler <petru@paler.net>
Date: Fri, 21 Nov 2025 14:12:19 +0000
Subject: [PATCH] Auth docs.

---
 CLAUDE.md          |  9 +++++++-
 docs/AUTH_SETUP.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 docs/AUTH_SETUP.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 71a1061..b4c5df2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,7 +20,8 @@ NixOS cluster configuration using flakes. Homelab infrastructure with Nomad/Cons
 ├── docs/
 │   ├── CLUSTER_REVAMP.md    # Master plan for architecture changes
 │   ├── MIGRATION_TODO.md    # Tracking checklist for migration
-│   └── NFS_FAILOVER.md      # NFS failover procedures
+│   ├── NFS_FAILOVER.md      # NFS failover procedures
+│   └── AUTH_SETUP.md        # Authentication (Pocket ID + Traefik OIDC)
 └── services/            # Nomad job specs (.hcl files)
 ```
 
@@ -76,6 +77,12 @@ NixOS cluster configuration using flakes. Homelab infrastructure with Nomad/Cons
 - SOPS for secrets, files in `secrets/`
 - Keys managed per-host
 
+**Authentication**:
+- Pocket ID (OIDC provider) at `pocket-id.v.paler.net`
+- Traefik uses `traefik-oidc-auth` plugin for SSO
+- Services add `middlewares=oidc-auth@file` tag to protect
+- See `docs/AUTH_SETUP.md` for details
+
 ## Migration Status
 
 **Phase 3 & 4**: COMPLETE! GlusterFS removed, all services on NFS
diff --git a/docs/AUTH_SETUP.md b/docs/AUTH_SETUP.md
new file mode 100644
index 0000000..ca723e6
--- /dev/null
+++ b/docs/AUTH_SETUP.md
@@ -0,0 +1,55 @@
+# Authentication Setup
+
+SSO for homelab services using OIDC.
+
+## Architecture
+
+**Pocket ID** (`pocket-id.v.paler.net`) - Lightweight OIDC provider, data in `/data/services/pocket-id`
+
+**Traefik** - Uses `traefik-oidc-auth` plugin (v0.16.0) to protect services
+- Plugin downloaded from GitHub at startup, cached in `/data/services/traefik/plugins-storage`
+- Middleware config in `/data/services/traefik/rules/middlewares.yml`
+- Protected services add tag: `traefik.http.routers.<name>.middlewares=oidc-auth@file`
+
+## Flow
+
+1. User hits protected service → Traefik intercepts
+2. Redirects to Pocket ID for login
+3. Pocket ID returns OIDC token
+4. Traefik validates and forwards with `X-Oidc-Username` header
+
+## Protected Services
+
+Use `oidc-auth@file` middleware (grep codebase for full list):
+- Wikis (TiddlyWiki instances)
+- Media stack (Radarr, Sonarr, Plex, etc.)
+- Infrastructure (Traefik dashboard, Loki, Jupyter, Unifi)
+
+## Key Files
+
+- `services/pocket-id.hcl` - OIDC provider
+- `services/traefik.hcl` - Plugin declaration
+- `/data/services/traefik/rules/middlewares.yml` - Middleware definitions (oidc-auth, simple-auth fallback)
+
+## Cold Start Notes
+
+- Traefik needs internet to download plugin on first start
+- Pocket ID needs `/data/services` NFS mounted
+- Pocket ID down = all protected services inaccessible
+
+## Troubleshooting
+
+**Infinite redirects**: Check `TRUST_PROXY=true` on Pocket ID
+
+**Plugin not loading**: Clear cache in `/data/services/traefik/plugins-storage/`, restart Traefik
+
+**401 after login**: Verify client ID/secret in middlewares.yml matches Pocket ID client config
+
+## Migration History
+
+- Previous: Authentik with forwardAuth (removed Nov 2024)
+- Current: Pocket ID + traefik-oidc-auth (simpler, lighter)
+
+---
+
+*Manage users/clients via Pocket ID UI. Basic auth fallback available via `simple-auth` middleware.*