# 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