axion1337.chat-gitops/docs/troubleshooting/DIAGNOSTIK-AUTHENTIK-FLOW.md

🔍 Authentik Enrollment Flow – Diagnostik & Reparaturplan

Symptom:

• akadmin wurde manuell in Matrix-DB angelegt (funktioniert)
• Boje wurde nur in Authentik erstellt, nicht in Matrix-DB (kaputt)
• Beide sollen denselben Enrollment Flow verwenden

Vermutung: Die Authentik → MAS → Synapse Kette ist unterbrochen

---

Phase 1: Diagnose (Bestandsaufnahme)

1.1 Authentik Logs prüfen

# Authentik Server logs
kubectl logs -n authentik -l app.kubernetes.io/name=authentik -f | grep -i "oauth\|oidc\|enroll\|flow"

# Worker logs
kubectl logs -n authentik -l app.kubernetes.io/component=worker -f | grep -i "enroll"

Worauf achten:

• Fehler bei "Enrollment create"?
• OIDC Token-Probleme?
• Flow-Validierungsfehler?

1.2 MAS (Matrix Authentication Service) Logs prüfen

# MAS logs
kubectl logs -n matrix -l app=matrix-authentication-service -f | grep -i "oauth\|upstream\|user\|oidc"

Worauf achten:

• Verbindung zu Authentik erfolgreich?
• Token-Validierung fehlgeschlagen?
• User-Provisioning-Fehler?

1.3 Synapse Logs prüfen

# Synapse logs (für User-Erstellung)
kubectl logs -n matrix -l app=synapse -f | grep -i "user\|provision\|register\|auth"

Worauf achten:

• User-Registrierungs-Fehler?
• Provisioning-Fehler?
• Authentifizierungsprobleme?

---

Phase 2: Authentik UI Überprüfung

2.1 Enrollment Flow inspizieren

# Authentik UI öffnen
kubectl port-forward -n authentik svc/authentik 9000:9000
# → Browser: http://localhost:9000
# → Admin UI → Flows & Stages → "Enrollment" Flow suchen

Checklist:

• Flow existiert und heißt "Enrollment"
• Reihenfolge der Stages:
  1. Identify (optional)
  2. Write (User-Erstellung)
  3. Enrollment (if-condition für neuen User)
  4. Verification (optional)
• "Write Stage" bindet sich an:
  • Username
  • Email
  • Name
• Alle Bindings sind "required" (nicht optional)

2.2 OIDC Provider in Authentik prüfen

# Über Authentik UI:
# Admin → Applications → Providers → "matrix-provider" (oder ähnlich)

Checklist:

• Provider existiert
• Name: z.B. "matrix-provider"
• Client Type: "Confidential"
• Redirect URIs enthalten:
  • https://account.axion1337.chat/upstream/callback/*
  • https://account.axion1337.chat/upstream/callback/01KQDJTR1ZVTG8JQ220F5BNBFZ (exact)
• Scopes: openid profile email
• Client ID + Secret kopiert?

2.3 OIDC Application in Authentik

# Admin → Applications → Applications → "matrix"

Checklist:

• Application existiert mit Slug "matrix"
• Provider ist zugewiesen
• Enrollment Flow ist zugewiesen (nicht "deny")
• Enrollment Flow ist die richtige (die von oben)

2.4 Test-User "Boje" inspizieren

# Admin → Directory → Users → "Boje"

Checklist:

• Username: boje
• Email: boje@... (vorhanden?)
• Groups: Falls erforderlich, die richtigen Groups zugewiesen?
• Status: Active oder Disabled?
• Sessions: Aktive Logins?

---

Phase 3: MAS Konfiguration überprüfen

3.1 Current MAS Secret auslesen

Da der age-key nicht lokal verfügbar ist, müssen wir die Konfiguration im Cluster prüfen:

# MAS Config im Cluster auslesen (nicht verschlüsselt)
kubectl get secret ess-mas-values-secret -n matrix -o jsonpath='{.data.values\.yaml}' | base64 -d | yq . | head -100

Worauf achten:

• upstream_oauth2_config Block existiert
• upstream_oauth2_config.issuer: https://auth.axion1337.chat/application/o/matrix/
• upstream_oauth2_config.client_id: Authentik Client ID
• upstream_oauth2_config.client_secret: Authentik Client Secret (*)
• upstream_oauth2_config.scopes: ["openid", "profile", "email"]
• upstream_oauth2_config.user_mapping_provider:
  • type: "oidc"
  • config.localpart_template: {{ user.preferred_username }}
  • config.display_name_template: {{ user.name }}
  • config.email_template: {{ user.email }}

3.2 MAS Pod exec – Config live prüfen

# MAS Config im laufenden Pod inspizieren
kubectl exec -it -n matrix deployment/matrix-authentication-service -- cat /etc/mas/config.yaml | grep -A50 upstream_oauth2_config

Worauf achten:

• Config ist syntaktisch korrekt (YAML)?
• Indentierung ist richtig?
• Werte sind vorhanden?

3.3 MAS OIDC Discovery prüfen

# Authentik OIDC Discovery Endpoint
curl -s https://auth.axion1337.chat/application/o/matrix/.well-known/openid-configuration | jq .

# Sollte zurückgeben:
# {
#   "issuer": "https://auth.axion1337.chat/application/o/matrix/",
#   "token_endpoint": "https://auth.axion1337.chat/application/o/token/",
#   "authorization_endpoint": "...",
#   ...
# }

---

Phase 4: Login-Flow Testen

4.1 MAS Login UI öffnen

# Port-Forward zu MAS
kubectl port-forward -n matrix svc/matrix-authentication-service 8765:8080
# → Browser: http://localhost:8765

Test:

1. Auf MAS-Seite: "Sign in with Authentik" klicken
2. Authentik-Login durchführen
3. Auf Enrollment Flow warten
4. Neuen User erstellen (Test-Username, Email, Password)
5. Nach erfolgreicher Registrierung: Matrix home_server erhalten?

4.2 Fehlerberichte

Falls Fehler auftritt:

• Screenshot des Fehlers
• MAS logs auslesen: kubectl logs -n matrix -l app=matrix-authentication-service --tail=50
• Authentik logs auslesen: kubectl logs -n authentik -l app.kubernetes.io/name=authentik --tail=50

---

Phase 5: Reparaturschritte (nachdem Diagnose klar ist)

Falls MAS-Config fehlerhaft:

# 1. Secrets entschlüsseln (lokale Umgebung mit age-key erforderlich)
sops -d apps/production/custom-configs/mas-secret.yaml > /tmp/mas-secret-decrypted.yaml

# 2. Editor öffnen und Konfiguration reparieren
vim /tmp/mas-secret-decrypted.yaml
# → upstream_oauth2_config überprüfen und korrigieren

# 3. Wieder verschlüsseln
sops -e /tmp/mas-secret-decrypted.yaml > apps/production/custom-configs/mas-secret.yaml

# 4. Commiten
git add apps/production/custom-configs/mas-secret.yaml
git commit -m "Fix: Correct MAS upstream_oauth2_config for Authentik integration"

# 5. Flux triggern
flux reconcile kustomization production-apps --with-source

Falls Authentik Enrollment Flow fehlerhaft:

1. Admin UI öffnen: kubectl port-forward -n authentik svc/authentik 9000:9000
2. Flows → Enrollment Flow öffnen
3. Stages überprüfen und in richtige Reihenfolge bringen:
   • Identify: Benutzer identifizieren
   • Write: Benutzer in DB speichern
   • Enrollment: Weitere Felder (optional)
   • Finish: Abschluss
4. Speichern
5. Neuen Test-User erstellen und Enrollment durchlaufen

---

Erwartete Endergebnisse

Nach erfolgreichem Fix:

1. Benutzer klickt "Sign in with Authentik" auf MAS
2. Authentik-Login-Seite wird angezeigt
3. Nach Login: Enrollment Flow wird angezeigt
4. User füllt Formular aus
5. Nach "Finish": Authentik erstellt User UND verbindet zu Matrix
6. User wird in Matrix-DB angelegt (_matrix_auth prefix)
7. User kan sich bei ElementWeb anmelden

---

🎯 Nächster Schritt

Bitte folgende Diagnostik durchlaufen und mir die Output berichte:

1. MAS Logs (letzten 30 Zeilen)
2. Authentik Logs (letzten 30 Zeilen)
3. MAS Secret (entschlüsselt) – upstream_oauth2_config Block
4. Authentik OIDC Discovery Output
5. Screenshots der Authentik UI (Enrollment Flow, OIDC Provider, Application)

Damit kann ich dann genau sehen, wo der Bruch in der Kette ist! 🔗