Add infrastructure documentation

2026-01-18 16:57:25 +02:00
parent 69e1338a5b
commit 62a6267026
10 changed files with 2658 additions and 0 deletions
--- a/docs/03-PHASE3-AUTHENTIK-ZEROTRUST.md
+++ b/docs/03-PHASE3-AUTHENTIK-ZEROTRUST.md
@@ -0,0 +1,196 @@
+# Phase 3: Identity & Zero Trust (Authentik)
+
+## Status: ✅ COMPLETED
+
+**Last Verified:** 2026-01-18
+
+---
+
+## Goal
+Gate every `*.xtrm-lab.org` service behind OIDC authentication using Authentik, implementing Zero Trust access control.
+
+---
+
+## Current Authentik State
+
+| Parameter | Value |
+|-----------|-------|
+| Container | authentik (+ authentik-worker) |
+| Version | 2025.8.1 |
+| Network | dockerproxy |
+| Ports | 9000 (HTTP), 9443 (HTTPS) |
+| URL | https://auth.xtrm-lab.org |
+| PostgreSQL | postgresql17 (authentik_db) |
+| Redis | redis |
+| Status | ✅ Running (healthy) |
+
+---
+
+## Verified Configuration
+
+### Users
+
+| Username | Name | Status |
+|----------|------|--------|
+| akadmin | authentik Default Admin | Active |
+| admin | Admin User | Active |
+| jazzymc | Kaloyan Danchev | Active |
+
+### Groups
+
+| Group Name | Purpose |
+|------------|---------|
+| authentik Admins | Administrative access |
+| authentik Read-only | Read-only access |
+
+### Outpost
+
+| Name | Type | Status |
+|------|------|--------|
+| authentik Embedded Outpost | proxy | ✅ Running |
+
+### Applications
+
+| Application | Slug |
+|-------------|------|
+| XTRM-Lab Protected Services | xtrm-lab-protected |
+| Actual Budget | actual-budget |
+
+### Proxy Provider
+
+| External Host | Mode |
+|---------------|------|
+| https://auth.xtrm-lab.org | forward_domain |
+
+### 2FA Status
+
+| Type | Count |
+|------|-------|
+| TOTP Devices | 2 |
+| WebAuthn Devices | 0 |
+
+---
+
+## Services Protected by Authentik Forward Auth
+
+The following services require Authentik authentication:
+
+| Service | Domain |
+|---------|--------|
+| n8n | n8n.xtrm-lab.org |
+| Traefik Dashboard | traefik.xtrm-lab.org |
+| NetAlertX | netalert.xtrm-lab.org |
+| UrBackup | urbackup.xtrm-lab.org |
+| Pi-hole 1 | ph1.xtrm-lab.org |
+| Pi-hole 2 | ph2.xtrm-lab.org |
+| Unimus | unimus.xtrm-lab.org |
+| Homarr | xtrm-lab.org |
+| Uptime Kuma | uptime.xtrm-lab.org |
+| Transmission | transmission.xtrm-lab.org |
+
+**Total: 12 protected routes** (including root redirects for Pi-holes)
+
+---
+
+## Services WITHOUT Authentik Protection
+
+These services have their own authentication or are public:
+
+| Service | Domain | Reason |
+|---------|--------|--------|
+| Authentik | auth.xtrm-lab.org | Self (would cause redirect loop) |
+| Plex | plex.xtrm-lab.org | Has own Plex authentication |
+| Vaultwarden | vault.xtrm-lab.org | Has own authentication |
+| Home Assistant | ha.xtrm-lab.org | Has own authentication |
+| Karakeep | karakeep.xtrm-lab.org | Public/own auth |
+| RustFS CDN | cdn.xtrm-lab.org | Public CDN (S3 auth) |
+| Pangolin API | pangolin.xtrm-lab.org | API access |
+| Nextcloud | nextcloud.xtrm-lab.org | Has own authentication |
+
+---
+
+## Traefik Forward Auth Middleware
+
+Configured in `/mnt/user/appdata/traefik/dynamic.yml`:
+
+```yaml
+authentik-forward-auth:
+  forwardAuth:
+    address: "http://authentik:9000/outpost.goauthentik.io/auth/traefik"
+    trustForwardHeader: true
+    authResponseHeaders:
+      - X-authentik-username
+      - X-authentik-groups
+      - X-authentik-email
+      - X-authentik-name
+      - X-authentik-uid
+```
+
+---
+
+## Verification Checklist
+
+- [x] Authentik initial setup completed (admin password set)
+- [x] Outpost running and connected (embedded outpost)
+- [x] User groups created (authentik Admins, authentik Read-only)
+- [x] Application/provider pairs configured (2 applications)
+- [x] Traefik config updated with forward auth middleware
+- [x] Services tested successfully (302 redirect to login)
+- [x] All planned services protected (12 routes)
+- [x] 2FA enabled for admin accounts (2 TOTP devices)
+
+---
+
+## Architecture
+
+```
+                           Internet User
+                                 │
+                    ┌────────────▼────────────┐
+                    │  Traefik (Reverse Proxy)│
+                    │  *.xtrm-lab.org:443     │
+                    └────────────┬────────────┘
+                                 │
+                    ┌────────────▼────────────┐
+                    │  Forward Auth Check     │
+                    │  → Authentik Outpost    │
+                    └────────────┬────────────┘
+                                 │
+              ┌──────────────────┴──────────────────┐
+              │                                      │
+    ┌─────────▼─────────┐                 ┌─────────▼─────────┐
+    │  Authenticated?   │                 │  Login Required   │
+    │  YES → Pass       │                 │  Redirect to      │
+    │  through to       │                 │  auth.xtrm-lab.org│
+    │  backend service  │                 └───────────────────┘
+    └───────────────────┘
+```
+
+---
+
+## Maintenance Notes
+
+### Database
+- PostgreSQL database: `authentik_db`
+- User: `authentik_user`
+- Host: `postgresql17` container
+- Data path: `/mnt/user/appdata/postgresql`
+
+### Backup Recommendation
+Regularly backup:
+- PostgreSQL database (contains all Authentik config)
+- `/mnt/user/appdata/traefik/dynamic.yml`
+
+### Rollback Procedure
+
+**Remove all protection (emergency):**
+1. Edit `/mnt/user/appdata/traefik/dynamic.yml`
+2. Remove `authentik-forward-auth` from all router middlewares
+3. Traefik will auto-reload
+
+---
+
+## Related Documents
+
+- [00-CURRENT-STATE.md](./00-CURRENT-STATE.md) - Infrastructure overview
+- [02-PHASE2-FOSSORIAL-STACK.md](./02-PHASE2-FOSSORIAL-STACK.md) - Pangolin integration