Thore Cimbal
80714fe901
The matrix-invitation flow only had Invite+Prompt stage bindings, both at order=0 (undefined order), missing the Write/Password/Login stages entirely — invited users were never written to the DB. Applied the fix live in-cluster (mirroring the working matrix-enrollment stage chain), and captured it as an Authentik Blueprint (ConfigMap, mounted via blueprints.configMaps) so the flow state is reproducible via GitOps instead of manual admin-UI clicks.
113 lines
4.2 KiB
Markdown
Executable File
113 lines
4.2 KiB
Markdown
Executable File
# 🔧 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` | **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-05-18
|
||
**Verfasser**: Claude Code + Thore
|