# Auth (Authentik + Kyverno SSO annotation policy)

Draft manifests only — nothing applied yet. Convention: any Ingress annotated
with `use-sso-auth: "true"` gets the Authentik forward-auth annotations injected
by the Kyverno ClusterPolicy (`auth/sso-auth-policy.yaml`).

## Deploy order

1. **Authentik** (`auth/authentik.yaml`) — IdP + embedded outpost. Needs a
   Postgres user/DB on postgresql.haven first (see below), plus secrets from
   Vaultwarden/ESO.
2. **Proxy provider** — create in Authentik UI (or via API) once it's up:
   one provider per app you want header-auth'd, mode "forward_auth (single
   app)", or a domain-level provider with the embedded outpost.
3. **Kyverno** (`auth/kyverno-helm.yaml`) — policy engine.
4. **SSO policy** (`auth/sso-auth-policy.yaml`) — expands `use-sso-auth: "true"`
   into `auth-url` / `auth-signin` / `auth-response-headers` annotations.
5. Annotate ingresses: `kubectl annotate ingress <name> -n <ns> use-sso-auth=true`
   and mirror the change in this repo.

## Postgres bootstrap (one-time, on postgresql.haven)

```sql
CREATE USER authentik WITH PASSWORD '<from-vaultwarden>';
CREATE DATABASE authentik OWNER authentik;
```

## Notes

- Outpost URL used everywhere is `https://auth.haven` — add DNS + ingress for
  the outpost before annotating anything.
- Apps that should *consume* the injected `X-Authentik-*` headers (Grafana auth
  proxy, Paperless remote-user, OpenWebUI trusted headers) need their own env
  changes; those are app-side, not covered by the policy.
- API/WebSocket-heavy apps (arr stack, qBittorrent) should NOT get the
  annotation on API paths — either skip the annotation or exclude paths.

## Which apps get the annotation (scoping)

Three tiers, applied per ingress — never blanket:

1. **OIDC tier** (no annotation, wire native OIDC in the app instead):
   grafana, paperless, affine, openwebui, vaultwarden, beszel, slink.
   Proper logout, group mapping, zero API breakage.
2. **Forward-auth tier** (`use-sso-auth: "true"`): browser-only utilities with
   no real auth — it-tools, notepad, searxng, homepage, archivebox,
   stirlingpdf, file-nginx, code-config, havenllo, own apps (chacal,
   mindforge) if wanted.
3. **Hands off** (built-in auth is fine, forward-auth breaks clients):
   sonarr, radarr, prowlarr, qbittorrent, adguard, changedetection,
   uptimekuma, cloudreve (WebDAV), jellyfin (clients can't do redirects —
   only the community SSO plugin route exists).

## Pre-annotation checklist (per new app)

Forward-auth breakage is loud and immediate if you look in the right places.
Before annotating any real hostname:

1. **Ask: what talks to this app that isn't a human in a browser?**
   Mobile/desktop apps with own login, API-key consumers, push/webhook
   receivers, cronjobs curling through the ingress, WebDAV/RSS → any of
   those = hands off (tier 3) or exclude paths. "Just me in a browser" =
   safe.
2. **Canary first:** create a scratch ingress for the same service
   (`<app>-test.haven`) with the annotation; leave the original untouched
   for ~a week. Forgotten integrations keep hitting the original and only
   break the canary — instant rollback
   (`kubectl annotate ingress <n> -n <ns> use-sso-auth-`).
3. **Grep the docs** (30s): "reverse proxy", "trusted header", "API key",
   "webhook", "basic auth". A "running behind a reverse proxy" doc section
   is where landmines are documented.
4. **Header-trust hygiene:** apps consuming `X-Authentik-*` must be
   reachable ONLY through the ingress (no NodePort/exposed port, otherwise
   LAN clients can forge headers straight to the pod). Keep built-in local
   login enabled; never set SSO-only mode.

## Files

- `kyverno-helm.yaml` — Kyverno install values
- `sso-auth-policy.yaml` — ClusterPolicy: `use-sso-auth` → nginx auth annotations
- `authentik.yaml` — Authentik server/worker + outpost, Postgres PVC, ingress

## Status / when to actually deploy this (decision from 2026-08-28)

NOT deployed — deliberate. Sole user, low login frequency, everything
reachable via wg-easy, so SSO solves a problem that doesn't exist. The
`*.ivanch.me` public ingresses were reviewed instead: exposure without usage
is pure risk, and the right fix is removing exposure (VPN-only), not adding
an IdP.

Pull the trigger only if one of these becomes true:

1. A second person uses the homelab regularly (SSO value scales with users).
2. Something must be exposed that can't sit behind VPN (third-party
   webhooks/callbacks) — then public tier gets `use-sso-auth` + 2FA.
3. Login friction on the OIDC apps (grafana/paperless/affine/openwebui/
   vaultwarden/beszel/slink) actually annoys on a weekly basis.

Until then this folder is a shelf-ready draft; cost of keeping it is zero.