# 🔧 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