189 lines
7.1 KiB
Markdown
189 lines
7.1 KiB
Markdown
# 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/infrastructure/authentik.tf` using the stylesheet `terraform/infrastructure/haumdaucher-theme.css`:
|
|
|
|
```bash
|
|
cd terraform/infrastructure
|
|
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
|
|
```
|