alo-cluster/docs/AUTH_SETUP.md

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.