axion1337.chat-gitops/docs/troubleshooting/README.md

🔧 Troubleshooting Guides

Dieser Ordner enthält detaillierte Troubleshooting- und Reparaturanleitungen für häufige Probleme bei der Authentik/MAS/Matrix Integration.

---

📖 Guides

1. DIAGNOSTIK-AUTHENTIK-FLOW.md

Für: Vollständige Diagnose des Authentik Enrollment Flows
Wann: Wenn Sie systematisch überprüfen möchten, ob die gesamte OIDC-Kette (Authentik → MAS → Synapse) funktioniert
Umfasst:

• Authentik Logs analysieren
• MAS Konfiguration überprüfen
• OIDC Discovery testen
• Enrollment Flow inspizieren
• Fehlersuche mit Debugging-Commands

Status: Nutzer Boje - Nur in Authentik erstellt, nicht in Synapse

---

2. AUTHENTIK-FIX-TEMPLATE.md

Für: Konkrete Reparaturen bei MAS/Authentik Integration
Wann: Wenn Sie wissen, welches Problem Sie haben und schnelle Lösungen suchen
Behandelt:

• Problem 1: MAS kennt Authentik-OIDC nicht
• Problem 2: Authentik Enrollment Flow kaputt
• Problem 3: OIDC Token werden nicht weitergeleitet
• Problem 4: ElementWeb zeigt keinen OIDC-Button
• Problem 5: User in Authentik aber nicht in Synapse

Status: Best Practices für häufige Probleme

---

3. AUTHENTIK-INVITATION-FLOW-FIX.md

Für: Reparatur des Invitation Flows bei Einladungslinks
Wann: Wenn Nutzer via Einladungslink nicht korrekt erstellt werden
Problem: Invitation Flow erfasst nur Username, nicht Email/Name
Lösung:

• Prompt Stage mit Email-Feld erstellen/reparieren
• Zur Invitation Flow hinzufügen
• Testen mit neuem Einladungslink

Status: Nutzer Klaus - Fehler "kein ausstehender benutzer Anfrage wurde verweigert"

---

4. AUTHENTIK-CREATE-INVITATION-FLOW.md ⭐ WICHTIGSTE ANLEITUNG

Für: Neuen separaten Invitation Flow erstellen
Wann: Wenn nur ein matrix-enrollment Flow existiert (Standard + Invitations gemeinsam)
Root Cause: Flow-Konflikt durch gemeinsamen Flow
Lösung (Schritt-für-Schritt):

1. Neuen Flow matrix-invitation erstellen
2. 5 Stages konfigurieren (Invite → Identify → Prompt → Write → Finish)
3. Email-Feld in Prompt Stage hinzufügen
4. Invitations auf neuen Flow setzen
5. Testen

Zeitaufwand: ~20 Minuten
Status: Aktuell für Klaus/Boje notwendig

---

🎯 Schneller Einstieg

Szenario 1: "Enrollment funktioniert nicht, ich weiß nicht warum"

→ Start: DIAGNOSTIK-AUTHENTIK-FLOW.md

Szenario 2: "Einladungslink funktioniert nicht"

→ Start: AUTHENTIK-CREATE-INVITATION-FLOW.md (wenn nur ein Flow existiert)
→ oder AUTHENTIK-INVITATION-FLOW-FIX.md (wenn zwei Flows existieren)

Szenario 3: "Ich kenne das Problem und brauche Lösungen"

→ Start: AUTHENTIK-FIX-TEMPLATE.md

Szenario 4: "Alles ist kaputt, ich brauche alles Schritt-für-Schritt"

→ Start: AUTHENTIK-CREATE-INVITATION-FLOW.md → AUTHENTIK-FIX-TEMPLATE.md → DIAGNOSTIK-AUTHENTIK-FLOW.md

---

📋 Bekannte Probleme

Problem	Nutzer	Guide	Status
Nur Standard Enrollment funktioniert	akadmin ✅	-	Resolved
User nur in Authentik, nicht in Synapse	Boje	DIAGNOSTIK-AUTHENTIK-FLOW.md	In Progress
Einladungslink-Fehler: "kein ausstehender benutzer"	Klaus	AUTHENTIK-CREATE-INVITATION-FLOW.md	In Progress
OIDC-Integration unklar	General	AUTHENTIK-FIX-TEMPLATE.md	Reference

---

🔗 Verwandte Dokumentation

• ../README.md – Hauptdokumentation & Architektur
• ../TASKS.md – Aufgabenliste & Meilensteine
• ../deployment-guides/ – Deployment-Anleitungen für andere Components

---

💡 Tipps

• Immer Logs überprüfen bevor man herumrät: kubectl logs -f -n <namespace> <pod>
• Browser-Cache löschen nach Authentik-Änderungen
• Port-Forward nutzen für lokales Testen: kubectl port-forward -n authentik svc/authentik 9000:9000
• Kleine Tests machen (einen User mit Invitation testen, nicht 10 auf einmal)

---

Zuletzt aktualisiert: 2026-05-18
Verfasser: Claude Code + Thore