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

---

### 5. **CALLS-FEHLEN-PROFILE-ZEILE.md**
**Für**: Konto kann sich anmelden und schreiben, aber **kein Anruf** kommt zustande  
**Wann**: Call-Klick löst serverseitig nichts aus (kein `openid/request_token`, kein `call.member`); Anzeigename lässt sich nicht setzen  
**Root Cause**: Fehlende `profiles`-Zeile in Synapse → Profil-Schreibpfad crasht (`_check_profile_size`, NoneType) → kein Displayname → Element-Call-Widget initialisiert nie  
**Lösung**: Fehlende Registrierungs-Default-Zeile nachtragen (read-only Diagnose, dann ein `INSERT`)  
**Status**: **Resolved (2026-08-11)** — `@apo` (Vor-Authentik-Konto nach mehreren Resets), einziger betroffener lebender Nutzer

---

## 🎯 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 |
| Calls scheitern still, Login/Messaging läuft | apo | `CALLS-FEHLEN-PROFILE-ZEILE.md` | **Resolved (2026-08-11)** — fehlende `profiles`-Zeile nachgetragen, an `clark`/`calltest01` gegengeprüft; open_id_tokens 0→6, Call verifiziert |

---

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