# Authentik Identity & Access Management (SSO)

Centralized authentication and identity provider for the `haumdaucher` Kubernetes cluster.

* **Domain**: `https://auth.haumdaucher.de`
* **Helm Chart**: `authentik/authentik` (Version 2026.8.0)
* **Database**: CloudNative-PG (`cnpg`) PostgreSQL cluster (`authentik-db`)
* **Ingress**: Traefik with Let's Encrypt TLS certificate (`auth-haumdaucher-de`)
* **Capabilities**: OIDC/OAuth2 Provider, Traefik ForwardAuth, 2FA (WebAuthn/Passkey, TOTP), User Invitations, Machine/AI Service Accounts.

---

## 🏗️ Architecture Layout

```mermaid
graph TD
    Client[Browser / User] -->|HTTPS| Traefik[Traefik Ingress]
    AI[AI Assistant / CLI Script] -->|HTTPS + Bearer Token| Traefik
    
    subgraph "ForwardAuth Ingresses"
        Traefik -->|ForwardAuth Check| ForwardAuthMW[Traefik ForwardAuth Middleware]
        ForwardAuthMW -->|Verify Session or Token| AuthServer[Authentik Server]
        Traefik -->|Allow| Z2M[Zigbee2MQTT]
        Traefik -->|Allow| Prom[Prometheus & Alertmanager]
        Traefik -->|Allow| PMA[phpMyAdmin]
        Traefik -->|Allow| OC[OpenClaw]
        Traefik -->|Allow| N8N[n8n Web UI]
    end

    subgraph "Native OIDC Workloads"
        Grafana[Grafana] -->|OIDC Auth Code Flow| AuthServer
        Coder[Coder v2] -->|OIDC Auth| AuthServer
        Gitea[Gitea] -->|OIDC Auth| AuthServer
        Nextcloud[Nextcloud user_oidc] -->|OIDC Auth| AuthServer
        MinIO[MinIO Console] -->|OIDC Auth| AuthServer
    end

    subgraph "auth Namespace"
        AuthServer --> DB[(CNPG Postgres: authentik-db)]
        AuthWorker[Authentik Worker] --> DB
    end
```

---

## 🚀 Deployment Instructions

### 1. Create Namespace & Provision CNPG Database

```bash
# Create auth namespace
kubectl create namespace auth

# Apply CNPG PostgreSQL cluster
kubectl apply -f k8s/auth/authentik-db.yaml

# Verify PostgreSQL cluster is ready (Status: Cluster in healthy state)
kubectl get cluster -n auth authentik-db
```

### 2. Deploy Authentik via Helm

```bash
# Add Authentik repository
helm repo add authentik https://charts.goauthentik.io
helm repo update

# Install or upgrade Authentik release
helm upgrade --install authentik authentik/authentik \
  --namespace auth \
  -f k8s/auth/authentik.secret.values.yaml
```

### 3. Deploy Traefik ForwardAuth Middleware

```bash
kubectl apply -f k8s/auth/traefik-forwardauth-middleware.yaml
```

---

## 🔑 Initial Setup & Admin Onboarding

1. Open your browser and navigate to:
   ```
   https://auth.haumdaucher.de/if/flow/initial-setup/
   ```
2. Set a secure password for the default `akadmin` account.
3. Configure your admin user profile and optionally enroll a WebAuthn / Passkey / TOTP 2FA device.

---

## 👥 User Management & Invitations

### Creating Users & Sending Invites
1. Navigate to **Directory > Users** in the Authentik Admin interface.
2. You can create users manually or upload/provision users in batches.
3. To send enrollment links, go to **Directory > Invitations**:
   * Click **Create**.
   * Set the target email and assign user groups (e.g. `family`, `friends`, `admins`).
   * Copy the generated invitation URL or send it to the user.

### Group Permissions
* `authentik Admins`: Full administrative control over Authentik.
* `infra-admins`: Access to infrastructure tools (Prometheus, Alertmanager, phpMyAdmin, Zigbee2MQTT).
* `users`: Standard user group with access to shared web services (Grafana dashboards, Coder, Nextcloud, Gitea).

👉 **For the complete guide on Terraform user management, bulk Excel/CSV imports, custom email templates, and RBAC/PBAC access limiting, see [USER_MANAGEMENT.md](./USER_MANAGEMENT.md).**

---

## 🤖 Machine & AI Agent Access (Programmatic Authentication)

For automated tools, scripts, or AI assistants that need to inspect protected applications (e.g. querying Zigbee2MQTT API/logs or Prometheus metrics):

1. **Create a Service Account**:
   * In Authentik Admin, navigate to **Directory > Users**.
   * Click **Create Service Account** (e.g. `ai-agent` or `automation-bot`).
   * Create a permanent API token for the service account.
2. **Accessing Protected Endpoints**:
   * Pass the token in the HTTP `Authorization` header:
     ```bash
     curl -H "Authorization: Bearer <your-authentik-token>" https://zigbee2mqtt.moritzgraf.de/api/...
     ```
   * Authentik's ForwardAuth middleware validates the Bearer token and allows the request without redirecting to a web login page.

See [MACHINE_AUTH.md](./MACHINE_AUTH.md) for full details.

---

## 🔒 Protecting Applications (Rollout Guide)

### Pattern 1: Traefik ForwardAuth (Proxy Protection)
Use this for applications without native OIDC (e.g. Zigbee2MQTT, Prometheus, phpMyAdmin, OpenClaw).

1. In Authentik Admin, go to **Applications > Providers**:
   * Create a **Proxy Provider**.
   * Name: `<App Name> Proxy` (e.g. `Zigbee2MQTT Proxy`).
   * Mode: `Forward auth (single application)`.
   * External Host: `https://<app-domain>` (e.g. `https://zigbee2mqtt.moritzgraf.de`).
2. Go to **Applications > Applications**:
   * Create Application, link the Provider, and set access policies/groups.
3. Add the middleware annotation to the application's Kubernetes Ingress:
   ```yaml
   annotations:
     traefik.ingress.kubernetes.io/router.middlewares: auth-authentik-forwardauth@kubernetescrd
   ```

### Pattern 2: Native OIDC SSO
Use this for applications supporting OpenID Connect (Grafana, Coder, Gitea, Nextcloud).

1. In Authentik Admin, create an **OAuth2/OpenID Provider**:
   * Name: `<App Name> OIDC`
   * Client Type: `Confidential`
   * Redirect URI: e.g. `https://grafana.haumdaucher.de/login/generic_oauth`
2. Create an **Application** in Authentik and assign it to the Provider.
3. Configure the client credentials (`client_id` and `client_secret`) in the application's Helm values / ConfigMap.

---

## 🎨 Branding & Haumdaucher UI Theme

The Authentik login screen is customized with a **Haumdaucher** glassmorphism theme matching `haumdaucher.de`.

* **Styling Highlights**:
  * **Glassmorphic Card**: Frosted glass panel (`backdrop-filter: blur(20px)`), smooth rounded corners (`24px`), and elegant ambient background aura.
  * **Typography**: Clean, modern typography using Google Font **Outfit**.
  * **Logo & Entrance Animation**: Dynamic 3D scale-and-fade entry animation for the Haumdaucher crest logo (`https://haumdaucher.de/images/logo_classic.png`).
  * **Dual Light & Dark Theme**: Automatic adaptation with dark mode styling featuring obsidian surfaces, gold accents (`#d4af37`), and glowing tactile buttons.
  * **Branded Footer**: "HAUMDAUCHER Wurst und Spezialitäten n.e.V." subtle watermark.

### Managing Theme via Terraform
Branding is provisioned via the `authentik_brand` resource in `terraform/authentik.tf` using the stylesheet `terraform/haumdaucher-theme.css`:

```bash
cd terraform
terraform apply -target=authentik_brand.haumdaucher
```

---

## 💾 Backup & Disaster Recovery

* **Database**: Managed by CloudNative-PG on `openebs-hostpath` persistent storage.
* **Velero Integration**: The `auth` namespace is backed up during daily/weekly Velero schedules:
  ```bash
  velero backup create auth-backup-$(date +%Y%m%d) --include-namespaces auth --wait
  ```