Thore CimbalandClaude Sonnet 5
932443df63
Documentation audit across the repo found several places still describing finished work as pending or in-progress (Authentik Stage 2, Element Call fork, NetworkPolicies in TASKS.md's own Next Steps section, the Boje troubleshooting entry). Also moves CLAUDE.md from the untracked parent directory into the repo root and brings its content up to date, and documents the new host-config/ pattern in README.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
🔧 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):
- Neuen Flow
matrix-invitationerstellen - 5 Stages konfigurieren (Invite → Identify → Prompt → Write → Finish)
- Email-Feld in Prompt Stage hinzufügen
- Invitations auf neuen Flow setzen
- 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 |
Resolved (2026-07-27) — identischer Root Cause wie bei Klaus (fehlende Write/Password/Login-Stages im matrix-invitation-Flow), behoben durch denselben Issue-#7-Fix. Nicht erneut mit Boje selbst nachgetestet, aber mit anderen Test-Usern (clark, lucky) end-to-end verifiziert - der zugrundeliegende Flow ist jetzt für jeden Nutzer korrekt. |
| Einladungslink-Fehler: "kein ausstehender benutzer" | Klaus | AUTHENTIK-CREATE-INVITATION-FLOW.md |
Fixed (2026-07-27) — matrix-invitation Flow hatte nur Invite+Prompt Stage-Bindings, beide auf order=0. Write/Password/Login-Stages fehlten komplett. Live gefixt + als Blueprint (apps/authentik/authentik-blueprints.yaml) reproduzierbar gemacht. |
| 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-07-30
Verfasser: Claude Code + Thore