Thore CimbalandClaude Sonnet 5
2b7f42dc8c
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>
113 lines
4.5 KiB
Markdown
113 lines
4.5 KiB
Markdown
# 🔧 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` | **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
|