Files

T

Moritz Graf 8f01b75bd6 refactor(structure): reorganize monorepo with projects, terraform hierarchy, and strict k8s namespace rules

2026-10-12 13:49:41 +02:00

7.1 KiB

Raw Permalink Blame History

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

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

# 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

# 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

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

🔑 Initial Setup & Admin Onboarding

Open your browser and navigate to:

https://auth.haumdaucher.de/if/flow/initial-setup/

Set a secure password for the default akadmin account.
Configure your admin user profile and optionally enroll a WebAuthn / Passkey / TOTP 2FA device.

👥 User Management & Invitations

Creating Users & Sending Invites

Navigate to Directory > Users in the Authentik Admin interface.
You can create users manually or upload/provision users in batches.
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.

🤖 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):

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.
Accessing Protected Endpoints:
- Pass the token in the HTTP Authorization header:
```
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 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).

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).
Go to Applications > Applications:
- Create Application, link the Provider, and set access policies/groups.

Add the middleware annotation to the application's Kubernetes Ingress:

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).

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
Create an Application in Authentik and assign it to the Provider.
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:

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:
```
velero backup create auth-backup-$(date +%Y%m%d) --include-namespaces auth --wait
```

7.1 KiB Raw Permalink Blame History