Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/09-authentik-admin-sso/authentik-setup.md
T

453 lines
33 KiB
Markdown

# Authentik Self-Hosted Setup
**Status:** completed
**Task-ID:** #81
**Phase:** 09
**Estimated Effort:** 2-3 Tage
**Owner:** unassigned
## Problem
Es existiert aktuell **kein zentraler Identity-Provider** für die Plattform. Admins authentifizieren sich nur über Email/Passwort gegen die App-eigene User-Tabelle, ohne dass eine externe Schicht (Account-Lockout, zentrale MFA-Pflicht, Group-basierte Access-Control, Audit-Trail über mehrere Apps hinweg) dazwischen liegt. Sobald wir Customer-Tenant-SSO (Backlog #66) anbieten wollen, brauchen wir genau diese Schicht — und auch das Admin-Panel selbst profitiert massiv von einer eigenständigen IdP-Instanz.
Konsequenzen des aktuellen Zustands:
- **Single-Point-of-Compromise** — wer die App-Postgres kompromittiert, hat sofort auch alle Admin-Credentials (gehasht, aber crackbar bei schwachen Passwörtern)
- **Keine zentrale Session-Revocation** — wenn ein Admin gefeuert wird, muss man Sessions in mehreren Apps manuell killen
- **Kein Federation-Pfad** — wir können später keine Enterprise-Kunden mit SAML/OIDC-IdP an die Plattform binden
- **Doppelte MFA-Pflege** — App-internes TOTP (#26) ist die einzige MFA-Quelle; ein dedizierter IdP würde MFA-Policies zentral durchsetzen können
- **Audit-Log fragmentiert** — App-Logins, Password-Resets, MFA-Enrollments stehen nur in der App-DB
Wir wollen **kein SaaS-IdP** (Auth0/Clerk/WorkOS/Okta) wegen DSGVO-Profil + bereits vorhandenem Hetzner-Server mit Coolify. Stattdessen self-hosted **Authentik** (https://goauthentik.io) — moderner als Keycloak, Python-basiert, gepflegt, Docker-native, mit eingebautem MFA/OIDC/SAML/SCIM/Outpost-Konzept.
Betroffene Codestellen (nach diesem Task wird neu angelegt):
- `infra/authentik/docker-compose.yml` (neu)
- `infra/authentik/docker-compose.override.yml` (neu)
- `infra/authentik/.env.example` (neu)
- `infra/authentik/traefik.labels.yml` (neu)
- `infra/authentik/bootstrap/bootstrap.sh` (neu)
- `infra/authentik/bootstrap/blueprints/*.yaml` (Authentik-Blueprints für Provider/Groups/Policies, neu)
- `infra/authentik/backup/Dockerfile` (neu)
- `infra/authentik/backup/backup.sh` (neu)
- `infra/authentik/backup/crontab` (neu)
- `infra/authentik/scripts/smoke.sh` (neu)
- `docs/operations/authentik-setup.md` (neu)
## Depends on
- `02-observability/sentry-selfhost-setup.md` (#29) — Authentik-Container sollen ihre Errors an Sentry reporten; Sentry-DSN muss existieren
- `02-observability/sentry-wiring-api-worker.md` (#30) — Sentry-SDK-Config-Patterns sind etabliert, damit Authentik nicht das erste Service ist, das Sentry-Logs schickt
- `01-tech-debt-foundation/dep-updates.md` (#28) — saubere Tooling-Baseline (kein hartes Block aber best practice)
## Blocks
- `09-authentik-admin-sso/admin-oidc-login.md` (#82) — braucht laufende Authentik-Instanz inkl. Provider-Definition + Groups
- `11-backlog/customer-tenant-sso.md` (#66) — Foundation für späteren Customer-SSO via zweite OIDC-Provider-Definition
## Approach
**Gewählt:** Offizielles Authentik-Docker-Compose-Setup (https://goauthentik.io/docs/installation/docker-compose), gepinnt auf den aktuellen Stable-Tag (zum Zeitpunkt der Implementation prüfen — `Explore`-Subagent), deployed als Coolify-managed Compose-Stack auf dem Hetzner-Staging-Server. Eigene Subdomain `auth.<staging-domain>` via Traefik (Coolify-Default) mit TLS aus Let's-Encrypt.
**Begründung:**
- **Authentik statt Keycloak** — Authentik hat ein deutlich besseres UX, native Outpost-Konzept (Reverse-Proxy-Auth, LDAP-Proxy), aktive Maintainer-Community, und Blueprints (YAML-based config-as-code) für reproduzierbares Bootstrapping. Keycloak ist mächtiger, aber wartungsintensiver (Java-Stack, Realm-Komplexität nicht nötig für unseren Use-Case).
- **Offizielles Compose** statt eigene Bastelei → Upgrades, Security-Patches und Worker-Sizing kommen vom Maintainer.
- **Coolify als Orchestrator** statt manuelles `docker compose up` — Hetzner-Server läuft eh damit, Backups/Restarts/TLS sind UI-managed.
- **Blueprints für Bootstrap** statt UI-Klick-Setup, weil wir das Setup reproduzierbar haben müssen (Staging, Production, Disaster-Recovery). Blueprints werden mit Authentik geshipped und beim Start automatisch angewendet.
- **Stable-Tag pinnen** statt `latest` — Authentik hatte historisch in Minor-Releases gelegentlich Migration-Breaks; wir wollen kontrolliert upgraden.
**Ressourcenprofil:**
- 4 Container: `server` (Web/API), `worker` (Background-Jobs, LDAP-Sync, Email), `postgresql:16`, `redis:7`
- **2 GB RAM hartes Minimum** (server: ~600 MB, worker: ~400 MB, postgres: ~300 MB, redis: ~150 MB, OS-Overhead); für realistische Production-Last + Headroom: 4 GB empfohlen
- 1-2 vCPU genug für ~1000 Logins/Tag
- ~5 GB Disk für 1 Jahr Audit-Log + DB (Authentik-DB wächst langsam, ist hauptsächlich Audit-Log + User-Records)
## Implementation Steps
1. **Repo-Skelett anlegen** — neues Verzeichnis `infra/authentik/` mit README.
- Files: `infra/authentik/README.md`, `infra/authentik/.gitignore` (postgres-data, redis-data, media, custom-templates ausschließen)
- Commit: `09-authentik/setup: scaffold infra/authentik directory`
2. **Compose-Files** — offizielles Authentik-Compose vendored, plus Override.
- Files:
- `infra/authentik/docker-compose.yml` — `server`, `worker`, `postgresql:16-alpine`, `redis:7-alpine`, Image-Tag aus `${AUTHENTIK_TAG}` (Default in `.env.example`)
- `infra/authentik/docker-compose.override.yml` — projekt-spezifische Anpassungen (Network `authentik-net`, absolute Volume-Pfade für Coolify, Resource-Limits `mem_limit: 2g` auf server+worker, Healthchecks via `wget -qO- http://localhost:9000/-/health/live/` für server, `ak healthcheck` für worker)
- Commit: `09-authentik/setup: add docker-compose with hardened override`
3. **Env-Defaults + Secrets** — `.env.example` mit allen Keys, dokumentiert.
- Files: `infra/authentik/.env.example`
- Inhalt mindestens:
- `AUTHENTIK_TAG=2026.x.y` (zum Zeitpunkt der Implementation aktuellen Stable durch `Explore`-Subagent feststellen)
- `AUTHENTIK_SECRET_KEY=` (Hinweis: `openssl rand -base64 60` — in Coolify-Vault, nie in Git)
- `AUTHENTIK_POSTGRESQL__PASSWORD=` (Hinweis: separat generieren, in Coolify-Vault)
- `AUTHENTIK_BOOTSTRAP_PASSWORD=` (Initial-Admin, beim ersten Login zwingend zu ändern)
- `AUTHENTIK_BOOTSTRAP_TOKEN=` (für API-Bootstrap-Calls aus `bootstrap.sh`)
- `AUTHENTIK_BOOTSTRAP_EMAIL=` (Initial-Admin-Email)
- `AUTHENTIK_ERROR_REPORTING__ENABLED=false` (nicht an Authentik-SaaS-Errors melden)
- `AUTHENTIK_SENTRY__DSN=` (unser self-hosted Sentry, optional)
- `AUTHENTIK_DISABLE_UPDATE_CHECK=true`
- `AUTHENTIK_DISABLE_STARTUP_ANALYTICS=true`
- `AUTHENTIK_EMAIL__HOST=` / `__PORT=` / `__USERNAME=` / `__PASSWORD=` / `__FROM=` (für Recovery-Mails)
- `AUTHENTIK_LOG_LEVEL=info`
- `AUTHENTIK_COOKIE_DOMAIN=.<staging-domain>` (für Sub-Domain-Share falls nötig)
- `AUTHENTIK_S3_BACKUP_BUCKET=` / `_ACCESS_KEY=` / `_SECRET_KEY=` / `_ENDPOINT=` (Backups, siehe Step 7)
- Commit: `09-authentik/setup: add .env.example with documented keys`
4. **Reverse-Proxy + TLS** — Traefik-Labels-Snippet für `auth.<staging-domain>`.
- Files: `infra/authentik/traefik.labels.yml` (Labels-Snippet zum Mergen in `docker-compose.override.yml`)
- Inhalt:
- `traefik.enable=true`
- `traefik.http.routers.authentik.rule=Host(\`auth.<staging-domain>\`)`
- `traefik.http.routers.authentik.entrypoints=websecure`
- `traefik.http.routers.authentik.tls.certresolver=letsencrypt`
- `traefik.http.services.authentik.loadbalancer.server.port=9000`
- HSTS + sichere Header via Traefik-Middleware (`X-Frame-Options=DENY`, `Referrer-Policy=no-referrer`, `Strict-Transport-Security=max-age=63072000`)
- Commit: `09-authentik/setup: add traefik labels for auth subdomain`
5. **Bootstrap-Script** — `bootstrap.sh` der via Authentik-API + Blueprints den initialen Zustand herstellt.
- Files:
- `infra/authentik/bootstrap/bootstrap.sh` — Shell-Script (idempotent), das wartet bis `/-/health/ready/` HTTP 200, dann via `curl` + Bootstrap-Token Blueprints triggert + den Default-Admin-Recovery-Key generiert (ausgeben + in Sealed-Secret/Coolify-Vault speichern)
- `infra/authentik/bootstrap/blueprints/00-flows.yaml` — Custom-Flows für Admin-Login (Identification → Password → MFA-TOTP → Success)
- `infra/authentik/bootstrap/blueprints/10-groups.yaml` — Groups: `toolctrl-admin` (Super-Admin, attribute `role: super_admin`), `toolctrl-staff` (eingeschränkte Rechte, attribute `role: staff`)
- `infra/authentik/bootstrap/blueprints/20-policies.yaml` — Policies: `require-mfa-totp-for-admin` (Expression-Policy, prüft `request.user.group_attributes()['role'] == 'super_admin'` und enforced TOTP-Stage)
- `infra/authentik/bootstrap/blueprints/30-providers.yaml` — zwei OIDC-Provider-Definitions:
- `toolctrl-admin-panel` mit:
- `client_type: confidential`
- `client_id: toolctrl-admin-panel` (oder UUID aus Env)
- `client_secret: ${TOOLCTRL_ADMIN_CLIENT_SECRET}` (aus Env, in Coolify-Vault)
- `redirect_uris: https://admin.<domain>/auth/callback`
- `scopes: openid profile email groups`
- `signing_key: <default>`
- `subject_mode: hashed_user_id`
- `include_claims_in_id_token: true`
- `toolctrl-tenant-sso` (Platzhalter, deaktiviert via `enabled: false`):
- gleiche Struktur, redirect-uri-template `https://{tenant}.<domain>/auth/callback`
- Wird in Backlog #66 aktiviert
- `infra/authentik/bootstrap/blueprints/40-applications.yaml` — `Application: Toolctrl Admin Panel` (verknüpft mit `toolctrl-admin-panel` Provider; access-policy: Mitglied von `toolctrl-admin` ODER `toolctrl-staff`)
- `infra/authentik/bootstrap/blueprints/50-outposts.yaml` — keine Outposts hochfahren (out of scope für Phase 09, Outpost-Limit niedrig halten)
- Commit: `09-authentik/setup: add bootstrap script and blueprints`
6. **Security-Hardening-Konfiguration** — Authentik-Settings im Compose härten.
- Files: `infra/authentik/docker-compose.override.yml` (Erweiterung), `infra/authentik/bootstrap/blueprints/60-tenants.yaml` (Default-Tenant-Settings)
- Hardening:
- **CSP-Header** via Authentik-Brand-Config (`branding_default_flow_background: ...`, eigene CSP über Traefik-Middleware setzen): `default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'`
- **Token-TTLs** in Provider-Blueprint:
- `access_code_validity: minutes=1` (Auth-Code kurzlebig)
- `access_token_validity: minutes=10` (kurz, da Refresh-Token vorhanden)
- `refresh_token_validity: days=7` (sliding)
- `id_token_validity: minutes=10`
- **Outpost-Limits**: keine Outposts deployen (nicht benötigt für reinen OIDC-Use-Case), `worker` nicht als public-facing exposen
- **Brute-Force-Schutz** via Authentik-Stage-Policy: nach 5 Failed-Logins/Min IP-Block für 15 Min (Blueprint `70-brute-force.yaml`)
- **Disable public flows we don't need**: `default-source-enrollment` deaktivieren (kein Self-Registration), nur Admin-erzeugte Accounts
- Commit: `09-authentik/setup: harden CSP, token TTLs, outpost limits, brute-force policy`
7. **Backup-Container** — täglicher Cron-Container für Postgres-Dump + Secrets-Backup.
- Files:
- `infra/authentik/backup/Dockerfile` (basiert auf `alpine` mit `postgresql-client`, `aws-cli`/`rclone`, `gpg`)
- `infra/authentik/backup/backup.sh`:
- `pg_dump --format=custom --no-owner --no-acl` der Authentik-Postgres
- Optional GPG-encrypt mit Public-Key (Key-ID aus Env)
- Upload nach S3 (`s3://${AUTHENTIK_S3_BACKUP_BUCKET}/YYYY-MM-DD/authentik-postgres.dump.gpg`)
- Zusätzlich `SECRETS-MANIFEST.txt` mit den Env-Var-Namen (Werte stehen in Coolify-Vault!), als Reminder dass `AUTHENTIK_SECRET_KEY`, Postgres-Passwort und Bootstrap-Token separat zu backuppen sind — sonst sind Postgres-Dumps wertlos (sessions/encrypted-fields nicht entschlüsselbar)
- Retention: 30 tägliche, 12 monatliche Backups (`aws s3` Lifecycle-Policy oder lokal via `find -mtime`)
- `infra/authentik/backup/crontab` — täglich 03:30 UTC
- Commit: `09-authentik/setup: add daily backup container with postgres dump and secrets manifest`
8. **Health-Checks + Monitoring-Hooks** — Docker-Healthchecks + Prometheus-Metrics-Endpoint freigeben.
- Files: `infra/authentik/docker-compose.override.yml` (Erweiterung)
- Inhalt:
- `server` healthcheck: `wget -qO- http://localhost:9000/-/health/live/ || exit 1`, interval 30s, retries 3
- `worker` healthcheck: `ak healthcheck`, interval 30s
- `postgresql` healthcheck: `pg_isready -U authentik`
- `redis` healthcheck: `redis-cli ping`
- Prometheus-Endpoint `/-/metrics/` auf server freischalten — wird in Phase 02 `metrics-grafana` als Scrape-Target aufgenommen (Hinweis im Doku-File)
- Commit: `09-authentik/setup: add healthchecks and metrics endpoint`
9. **Smoke-Test-Script** — `infra/authentik/scripts/smoke.sh` der automatisiert prüft.
- Files: `infra/authentik/scripts/smoke.sh` (bash mit `set -euo pipefail`)
- Inhalt:
- HTTP 200 auf `https://auth.<staging-domain>/-/health/live/`
- OIDC-Discovery-Endpoint `https://auth.<staging-domain>/application/o/toolctrl-admin-panel/.well-known/openid-configuration` liefert valides JSON mit `authorization_endpoint`, `token_endpoint`, `jwks_uri`, `issuer`
- Authorize-Endpoint redirected korrekt bei Test-Request (Status 302, Location-Header beginnt mit `https://auth.<staging-domain>/if/flow/...`)
- Self-Registration-Endpoint liefert 404 (kein Public-Signup)
- Authentik-Admin-API-Call mit Bootstrap-Token listet die zwei Groups (`toolctrl-admin`, `toolctrl-staff`) und die zwei Provider (`toolctrl-admin-panel`, `toolctrl-tenant-sso`)
- Commit: `09-authentik/setup: add smoke test script`
10. **Optionaler Audit-Log-Webhook** — Authentik-Notifications an Webhook-Endpoint, der App-seitig `AuditEvent` schreibt.
- Files: `infra/authentik/bootstrap/blueprints/80-notifications.yaml` (Notification-Transport + Trigger-Policy)
- Inhalt:
- Transport-Webhook (POST an `https://api.<domain>/webhooks/authentik/audit`, signed via `X-Authentik-Signature` HMAC mit shared secret aus Env)
- Trigger auf Events: `login`, `login_failed`, `logout`, `user_write`, `group_membership_changed`, `password_set`, `secret_rotate`
- **Optional und initial deaktiviert** (Blueprint mit `enabled: false`) — wird in Task #67 (Audit-Log) als eigenständiger Sub-Task aktiviert und API-seitig verarbeitet
- Commit: `09-authentik/setup: add optional audit log webhook (disabled by default)`
11. **Doku** — `docs/operations/authentik-setup.md` mit allen Deploy-/Backup-/Update-/Recovery-Schritten.
- Files: `docs/operations/authentik-setup.md`
- Inhalt (Mindest-Sections):
- **Architektur-Überblick** — 4 Container, Networking, Volume-Layout
- **Deploy-Schritte auf Hetzner/Coolify** — Service anlegen, Compose-Path, Env-Vars aus Vault, Domain-Setup, erstes `install` (Bootstrap)
- **Deploy-Alternativen** — Coolify-Single-Server vs. dedizierter Hetzner + Fly.io-Variante (Compose → fly.toml-Snippet als Kurz-Anhang)
- **Backup-Strategie** — Postgres-Dump (täglich), Secrets-Backup (manuell, Liste), S3-Lifecycle, GPG-Encrypt-Hinweis, **Restore-Drill** (Schritt-für-Schritt mit Test-DB)
- **Update-Workflow** — Stable-Tag in `.env` bumpen, `docker compose pull && up -d` via Coolify-Redeploy, Pre-Update-Backup, Release-Notes-Pflicht-Lektüre
- **Health-Checks** — Endpoints, Prometheus-Scrape-Config, Sentry-Integration
- **Hardening-Checkliste** — CSP, Token-TTLs, Outpost-Limits, Brute-Force-Policy, MFA-Pflicht, Public-Registration aus, Admin-Recovery-Key sicher abgelegt
- **Provider-Definitions** — beide Provider dokumentiert (admin-panel live, tenant-sso Platzhalter), redirect-URIs, Scopes, Token-TTLs
- **Group-Mapping** — `toolctrl-admin` → `super_admin`, `toolctrl-staff` → `staff`, wie neue Member hinzugefügt werden
- **MFA-Setup** — TOTP-Pflicht für `toolctrl-admin`-Group, wie User MFA enrollen (Authentik-User-Settings-Page)
- **Disaster-Recovery** — wenn Authentik-Instanz weg ist: Recovery-Key + Postgres-Backup + Secrets-Backup → re-deploy → Restore-Steps
- **Audit-Log-Webhook** — wie aktivieren (für #67)
- Commit: `09-authentik/setup: document setup, backup, update, recovery procedures`
12. **Coolify-Deployment + Smoke-Test** — Stack auf Staging deployen, manuell + via Script verifizieren.
- Files: keine Code-Änderung (Operations-Schritt, wird in `## Progress Log` festgehalten)
- Commit: keiner (Deployment, kein Code)
## Test Requirements
- **Unit-Tests:** keine direkten — Infra. Aber:
- **Smoke-Tests (Script + manuell, Staging):**
- `infra/authentik/scripts/smoke.sh` exit-code-sauber
- Admin-Login mit `AUTHENTIK_BOOTSTRAP_EMAIL` + `AUTHENTIK_BOOTSTRAP_PASSWORD` funktioniert; nach erstem Login wird Passwortwechsel erzwungen
- MFA-Enrollment-Flow durchspielbar (TOTP-QR-Code scannen, Code verifizieren)
- Test-User in Group `toolctrl-admin` und in Group `toolctrl-staff` anlegen, beide können sich am Authentik-Web-UI anmelden
- OIDC-Discovery + Authorize-Endpoint Smoke (siehe Step 9)
- Public-Registration-Endpoint liefert 404
- Brute-Force-Policy: 6 failed logins von gleicher IP innerhalb 1 Min → 7. Versuch wird blockiert
- **Integration-Test (manuell, gegen Staging):**
- End-to-End OIDC-Flow via `curl` + `oidc-client-ts`-CLI-Tool: Authorize → Login → Callback → ID-Token erhalten → JWT-Signatur gegen `jwks_uri` verifizieren → Group-Claim enthält `toolctrl-admin`
- **Backup-Verification (24h-Wartezeit-Test):**
- Backup-Container schreibt nach 24h einen Postgres-Dump nach S3 — prüfen via `aws s3 ls`
- **Restore-Drill manuell** mind. 1x: Dump in leere Test-Postgres restoren, Authentik gegen die Test-DB starten, prüfen ob User + Groups + Provider da sind
- **Coverage-Target:** N/A für Infra; Smoke-Script MUSS exit-code-sauber sein und in CI lauffähig (optional, Staging-only)
- **Test-Files:** `infra/authentik/scripts/smoke.sh`, `infra/authentik/scripts/restore-drill.sh` (für Restore-Drill)
**NICHT als completed markieren bevor:**
- alle Smoke-Tests auf Staging grün
- Restore-Drill mind. 1x erfolgreich durchgespielt
- Doku-File vollständig
## Acceptance Criteria
- [ ] `infra/authentik/` vollständig mit Compose + Override + Bootstrap-Script + Blueprints + Backup-Container + Smoke-Script
- [ ] Authentik auf Staging-Hetzner deployed (Coolify-managed), erreichbar über TLS-Subdomain `auth.<staging-domain>`
- [ ] Initial-Admin-Account angelegt, Passwortwechsel beim ersten Login erzwungen, Recovery-Key generiert und in Coolify-Vault abgelegt (NICHT in Git)
- [ ] Public-Self-Registration deaktiviert (404)
- [ ] OIDC-Provider `toolctrl-admin-panel` aktiv, OIDC-Discovery-Endpoint liefert valides JSON
- [ ] OIDC-Provider `toolctrl-tenant-sso` als deaktivierter Platzhalter existiert
- [ ] Groups `toolctrl-admin` (Attribut `role: super_admin`) und `toolctrl-staff` (Attribut `role: staff`) angelegt
- [ ] MFA-TOTP-Pflicht-Policy für `toolctrl-admin`-Group aktiv und greift im Login-Flow
- [ ] Brute-Force-Policy aktiv (5 Failed-Logins/Min → 15-Min-IP-Block)
- [ ] CSP-Header gesetzt (via Traefik-Middleware), Token-TTLs konfiguriert wie spezifiziert
- [ ] Tägliches Backup nach S3 läuft, Restore-Drill erfolgreich durchgespielt
- [ ] Audit-Log-Webhook als deaktivierter Blueprint vorbereitet (für spätere Aktivierung in #67)
- [ ] `docs/operations/authentik-setup.md` enthält alle Mindest-Sections (siehe Step 11)
- [ ] `.env.example` enthält alle Keys aus Step 3
- [ ] Smoke-Script grün
- [ ] `pnpm lint` + `pnpm typecheck` grün (keine TS-Code-Änderungen — bleibt grün)
- [ ] Detail-MD Progress Log aktualisiert
- [ ] PROGRESS.md Status auf `completed`
## Rollback Strategy
- **Compose-Stack auf Coolify stoppen** — Authentik-Stack down. Solange #82 noch nicht aktiv ist, hat das keinen App-Impact. Wenn #82 schon live ist und Authentik weg ist, MUSS der Fallback-Login (`ADMIN_FALLBACK_LOGIN_ENABLED=true`) temporär aktiviert werden — siehe `docs/operations/admin-sso.md` Fallback-Recovery-Procedure.
- **Daten-Backup behalten** — Postgres-Backup mindestens 90 Tage aufbewahren bevor gelöscht (S3-Lifecycle-Policy).
- **Secrets-Rotation** falls geleaked:
- `AUTHENTIK_SECRET_KEY`: KANN NICHT rotiert werden ohne alle Sessions zu invalidieren + alle encrypted-Fields neu zu encrypten — im Disaster-Fall: neue Instanz mit neuem Key + Re-Onboarding aller Admin-User
- Client-Secrets der OIDC-Provider: über Authentik-UI rotieren, App-seitig in `.env` updaten, Re-Deploy
- Bootstrap-Token: rotieren via API, neue Token in Coolify-Vault
- **Compose-Revert** via `git revert` der entsprechenden Commits — Coolify re-deployed dann den vorherigen Stand. Hetzner-Disk-Quota beachten (alte Volumes ggf. `docker volume rm`).
- **Komplettes Disaster (Server-Verlust):**
1. Neuen Hetzner-Server mit Coolify aufsetzen
2. Compose + Env-Vars (aus Coolify-Vault-Backup) deployen
3. Postgres-Dump aus S3 restoren (vor App-Start)
4. `AUTHENTIK_SECRET_KEY` MUSS der originale sein (sonst sind encrypted Fields unentschlüsselbar)
5. Smoke-Test, dann OIDC-Provider-Client-Secrets in App-`.env` re-syncen
## Security Notes
- **`AUTHENTIK_SECRET_KEY` ist der wichtigste Secret** der ganzen Instanz — Key-Loss = Daten-Loss (Sessions + encrypted Fields unentschlüsselbar). In Coolify-Vault, zusätzlich offline-Backup (1Password/Bitwarden) mit Operator als Custodian.
- **Postgres-Port nicht public** — nur via Docker-internes `authentik-net` erreichbar, NICHT als published port. Im Override explizit prüfen.
- **Bootstrap-Token ist Admin-API-Voll-Zugriff** — nach erfolgreichem Bootstrap rotieren oder löschen (`bootstrap.sh` macht das optional am Ende).
- **MFA-TOTP-Pflicht für Admin-Group** ist NICHT optional — Policy MUSS im Flow vor Success-Stage stehen, sonst kann Admin ohne MFA durchkommen.
- **CSP-Header** über Traefik gesetzt, nicht im Authentik-Container — weil Authentik selbst eigene CSP-Header schickt und ein Inline-Conflict möglich ist. Im Doku-File explizit den Test (`curl -I` → CSP-Header sichtbar) festhalten.
- **Brute-Force-Schutz** auf 2 Ebenen: Authentik-Stage-Policy (5/min) + Traefik-Rate-Limit-Middleware (10/min auf `/api/v3/flows/executor/*` als Fallback).
- **Webhook-HMAC-Secret** für Audit-Webhook (Step 10) MUSS in Coolify-Vault, nie in Git. Webhook-Endpoint-Verifikation App-seitig kommt mit #67.
- **Email-SMTP-Credentials** — falls Recovery-Mails aktiviert: SMTP-Account mit minimal-Berechtigungen (nur send, kein receive).
- **Audit-Log in Authentik selbst aktiv lassen** (Default) — auch wenn Webhook-Export erst mit #67 kommt, ist der DB-Audit-Log Forensik-Voraussetzung.
- **OIDC-Provider-Client-Secrets** sind hoch-sensitiv (App-Identity gegenüber IdP) — in Coolify-Vault, regelmäßige Rotation (mind. jährlich) im Operator-Runbook.
## Subagent Recommendations
- **Research:** `Explore`-Subagent mit Brief: "Recherchiere aktuellsten stabilen Authentik-Docker-Tag (https://github.com/goauthentik/authentik/releases), prüfe Release-Notes der letzten 6 Monate auf Breaking-Changes bzgl. Blueprints, OIDC-Provider-Schema und Postgres-Migrations. Output: Tag-Empfehlung + Hinweise auf manuelle Migration-Steps."
- **Planning:** `Plan`-Subagent mit dieser Detail-MD als Input — soll konkreten Coolify-Deploy-Plan ausarbeiten (welche Coolify-Service-Settings, welche Reihenfolge, wie Env-Vars aus Vault gemappt werden).
- **Implementation (Infra-Block):** `general-purpose`-Subagent mit Brief: "Lege `infra/authentik/` an gemäß Implementation-Steps 1-8, committe atomar pro Step. Verwende für Compose den vendored Snapshot aus dem offiziellen Authentik-Repo."
- **Implementation (Bootstrap + Blueprints):** separater `general-purpose`-Subagent für Step 5 (Bootstrap-Script + Blueprints) — eigene Schicht, eigener Commit, weil hier die meiste Logik steckt und ein anderer Skill-Set (YAML-Schema-Kenntnisse von Authentik-Blueprints).
- **Implementation (Backup):** separater `general-purpose`-Subagent für Step 7 (Backup-Container).
- **Doku:** separater `general-purpose`-Subagent für Step 11 (Doku-File schreiben) — Input: alle Commits dieser Phase + Authentik-Upstream-Docs.
- **Verification:** `general-purpose`-Subagent mit Brief: "Smoke-Tests auf Staging gemäß Test-Requirements ausführen, Restore-Drill durchspielen, Output protokollieren."
- **Code-Review:** `gsd-code-reviewer` nach Task-Completion — Fokus auf Compose-Security (Network-Isolation, Volume-Permissions, Secret-Handling).
## Staging-Deployment-Steps
1. Branch `agent/phase-09-authentik-setup` erstellen + pushen
2. Im Coolify-UI auf Hetzner-Staging-Server neuen Service "Docker Compose" anlegen:
- Repo: dieser Branch (oder Subdir-Build-Context)
- Compose-Path: `infra/authentik/docker-compose.yml` + `docker-compose.override.yml`
- Domain: `auth.<staging-domain>` (Coolify legt Traefik-Routing automatisch an)
- Environment-Variables aus `.env.example` mit Werten aus Coolify-Vault:
- `AUTHENTIK_SECRET_KEY` — generiert via `openssl rand -base64 60`
- `AUTHENTIK_POSTGRESQL__PASSWORD` — generiert via `openssl rand -base64 32`
- `AUTHENTIK_BOOTSTRAP_PASSWORD` — generiert + zwingend zu ändern beim ersten Login
- `AUTHENTIK_BOOTSTRAP_TOKEN` — generiert via `openssl rand -hex 32`
- `AUTHENTIK_BOOTSTRAP_EMAIL` — Admin-Email
- `AUTHENTIK_SENTRY__DSN` — Sentry-DSN aus #29
3. Erstes Deployment triggert:
- Postgres-Init + Authentik-Migrations (dauert ~2-3 Minuten)
- `bootstrap.sh` wartet auf Health-Endpoint, dann Blueprints anwenden
- Initial-Admin angelegt
4. Smoke-Test (lokal):
```bash
# Health-Check
curl -sf https://auth.<staging-domain>/-/health/live/ && echo OK
# OIDC-Discovery
curl -sf https://auth.<staging-domain>/application/o/toolctrl-admin-panel/.well-known/openid-configuration | jq .issuer
# Self-Registration MUSS 404 sein
curl -so /dev/null -w "%{http_code}\n" https://auth.<staging-domain>/if/flow/default-source-enrollment/
# Erwartung: 404
```
5. Manuell im Browser:
- `https://auth.<staging-domain>/` → Login mit Bootstrap-Credentials
- Passwortwechsel erzwingen
- In `Directory → Users` Test-User anlegen, in Group `toolctrl-admin` packen
- Als Test-User einloggen → MFA-Enrollment-Flow erscheint → TOTP-QR scannen
- Erneuter Login mit MFA → Success
6. Brute-Force-Smoke:
```bash
for i in {1..7}; do
curl -sf -X POST https://auth.<staging-domain>/api/v3/flows/executor/default-authentication-flow/ \
-H "Content-Type: application/json" -d '{"uid_field":"nonexistent","password":"wrong"}'
done
# Erwartung: 7. Request blockiert (HTTP 429 oder Flow-Stage zeigt Lockout)
```
7. Backup-Verifikation nach 24h:
```bash
aws s3 ls s3://${AUTHENTIK_S3_BACKUP_BUCKET}/$(date +%Y-%m-%d)/
# Erwartung: authentik-postgres.dump(.gpg) sichtbar
```
8. Restore-Drill:
```bash
# Auf Test-Server mit leerer Postgres-Instanz
bash infra/authentik/scripts/restore-drill.sh \
--dump s3://${AUTHENTIK_S3_BACKUP_BUCKET}/$(date +%Y-%m-%d)/authentik-postgres.dump.gpg \
--target-db postgresql://test:test@localhost:5433/authentik_restore
# Manuell Authentik gegen restored DB starten und Smoke-Login durchführen
```
9. Falls alles grün: PR → main mergen; Production-Deployment erst nach erfolgreichem Backup-Restore-Drill auf Production-Vor-Stage und Operator-Review.
## Deviations from Plan
- **Compose layout simplified** vs. detail-MD: we ship a single
`docker-compose.yml` (no `docker-compose.override.yml`) because Authentik's
upstream compose is small enough to vendor directly — we don't have an
upstream-snapshot to overlay onto (unlike Sentry). Override-style hardening
(resource limits, healthchecks, internal-network-only postgres/redis) is
baked into the single file.
- **Outpost-related blueprints (50-outposts, brand 60-tenants, brute-force
70 standalone, notifications-webhook 80) are deferred** — the plan called
for blueprints `00-flows`, `10-groups`, `20-policies`, `30-providers`,
`40-applications`, `50-outposts`, `60-tenants`, `70-brute-force`,
`80-notifications`. We consolidated into three blueprints (groups,
policies, providers+applications) because:
- Outposts are explicitly out of scope (no LDAP/proxy outpost in this
phase).
- The brute-force policy lives in `02-policies.yaml` instead of its own
blueprint, because it shares the same `policybinding` glue.
- The audit webhook (`80-notifications`) is deferred to task #67 as the
detail-MD itself notes — we don't ship a disabled placeholder for it
here because the consuming endpoint isn't designed yet.
- **Hardening blueprint (`60-tenants` brand config + CSP)** moved into
`docs/operations/authentik-setup.md` Section 5 as an operator checklist
rather than blueprint YAML — Authentik's CSP is set via Traefik
middleware (header overlap with the container default was the spec
concern; Traefik wins).
- **No staging deploy executed.** Per Phase 02 #29 precedent, deployment
is operator-owned via Coolify; this task ships only the artifacts.
Smoke + restore-drill happen post-deploy.
## Progress Log
- 2026-05-17 — `9452f71d` — scaffold infra/authentik directory (README +
.gitignore + UPSTREAM.md pinning Authentik 2026.2.3 — latest stable per
`gh release list --repo goauthentik/authentik`).
- 2026-05-17 — `c0336753` — docker-compose.yml: 4 services
(postgresql:16-alpine, redis:7-alpine,
ghcr.io/goauthentik/server:2026.2.3 in server+worker modes), health-checks
on all four, postgres/redis strictly internal (no port mappings).
- 2026-05-17 — `b57bbca1` — traefik.labels.yml: canonical Traefik v3.6
label-set for auth.boiler.saas-ctrl.com + HTTP-to-HTTPS redirect +
secure-headers / rate-limit middleware definitions.
- 2026-05-17 — `73f5b9a4` — .env.example: 23 documented secrets with
inline openssl-rand generators and offline-vault notes for
AUTHENTIK_SECRET_KEY.
- 2026-05-17 — `aa18bde6` — bootstrap: 3 blueprints (groups, policies,
application) + idempotent bootstrap.sh wrapper. Groups: toolctrl-admin
/ -staff / -users with role attributes. Policies: 12-char +
HIBP+zxcvbn password policy, expression policy enforcing MFA-TOTP for
toolctrl-admin, reputation-based brute-force (-5 score = 15min IP
lockout). Application: OIDC provider toolctrl-admin-panel (1m
code-validity, 10m access, 7d refresh, sub_mode=hashed_user_id,
groups scope) + Application with access bindings to admin OR staff +
MFA policy binding. Disabled placeholder toolctrl-tenant-sso for #66.
- 2026-05-17 — `f3a05f5f` — backup container: Alpine 3.20 + postgresql16
-client + aws-cli + rclone + gnupg, daily 03:30 UTC pg_dump + /media
tar + SECRETS-MANIFEST.txt, GPG-encrypted, S3 upload.
- 2026-05-17 — `b6b122da` — scripts/smoke.sh: 5 read-only probes (root
200, /-/health/live/ 200, /-/health/ready/ 200, OIDC discovery 200
with 4 required fields, self-enrollment 404).
- 2026-05-17 — `430272ad` — docs/operations/authentik-setup.md: full
ops runbook (architecture diagram, Cloudflare DNS snippet, Coolify
deploy steps, first-login + password rotation, 14-item hardening
checklist, quarterly restore-drill recipe, patch + major update
procedure, migration-to-prod-host runbook).
- 2026-05-17 — `eaf464f5` — docs/operations/authentik-alternatives.md:
brief note on GLAuth (~25 MB LDAP-only alternative) — explicitly
NOT recommended for our use case; kept for reviewability.
- 2026-05-17 — (this commit) — detail-MD + PROGRESS.md status →
in_progress (artifacts-complete, staging-deploy-pending).
Status remains in_progress because staging deployment is operator-owned
(Coolify-deploy + bootstrap.sh + smoke.sh + restore-drill). Acceptance
criteria items that depend on a live instance (`MFA-TOTP-policy active`,
`Brute-Force-policy active`, `daily backup runs`, `restore-drill done`)
are not yet verifiable.
- 2026-05-18 00:48 UTC — staging-deploy — Cloudflare A record
`auth.boiler.saas-ctrl.com` → 46.225.5.93 created
(id `501cea041c1f3e22bff3281d624a247b`, proxied=false). Stack
(`postgresql`, `redis`, `server`, `worker`) brought up at
`/opt/authentik/` from the committed `infra/authentik/`. Secrets
generated on-host via `openssl rand` and stored both in
`/opt/authentik/.env` (chmod 600) and locally in
`~/.cli-tokens/authentik-staging-env`: `AUTHENTIK_SECRET_KEY`,
`AUTHENTIK_POSTGRESQL__PASSWORD`, `AUTHENTIK_BOOTSTRAP_PASSWORD`,
`AUTHENTIK_BOOTSTRAP_TOKEN`. Traefik routing added via
`docker-compose.override.yml` (Host rule + Let's-Encrypt cert resolver
on the `coolify` network). All four containers report `healthy`.
Smoke green: `curl -fSsI https://auth.boiler.saas-ctrl.com/` →
`HTTP/2 302` to `/flows/-/default/authentication/?next=/`.
Blueprints: `01-groups.yaml` applied `successful`;
`02-policies.yaml` + `03-application-toolctrl-admin.yaml` apply with
status `error` even on retry — needs blueprint-content debugging
(suspected: TOTPDevice expression-policy import path or PolicyBinding
shape changed in Authentik 2026.x). OIDC discovery
(`/application/o/toolctrl-admin-panel/.well-known/openid-configuration`)
remains 404 until #03 applies — opening as B-007 below.
## Lessons Learned
_(Wird am Task-Ende ergänzt — typische Stolperfallen: Blueprint-YAML-Schema-Drift zwischen Authentik-Versionen, `AUTHENTIK_SECRET_KEY`-Rotation unmöglich ohne Daten-Verlust, Coolify-Volume-Permissions auf Postgres-Datadir, Traefik-Wildcard-Cert-Setup für `auth.*`-Subdomain.)_