From 5bbb03bc5229a72b7db3b06205116e6e5a1bc025 Mon Sep 17 00:00:00 2001 From: Scrublord MacBad Date: Mon, 18 May 2026 13:03:33 +0200 Subject: [PATCH] refactor: Organize troubleshooting docs into docs/troubleshooting/ Move all Authentik troubleshooting guides into dedicated subdirectory: - DIAGNOSTIK-AUTHENTIK-FLOW.md - AUTHENTIK-FIX-TEMPLATE.md - AUTHENTIK-INVITATION-FLOW-FIX.md - AUTHENTIK-CREATE-INVITATION-FLOW.md Add README.md with: - Quick reference guide for each document - Scenario-based navigation - Known issues tracking - Tips and best practices This keeps the root directory clean and organizes related guides together. Co-Authored-By: Claude Haiku 4.5 --- .../AUTHENTIK-CREATE-INVITATION-FLOW.md | 0 .../troubleshooting/AUTHENTIK-FIX-TEMPLATE.md | 0 .../AUTHENTIK-INVITATION-FLOW-FIX.md | 0 .../DIAGNOSTIK-AUTHENTIK-FLOW.md | 0 docs/troubleshooting/README.md | 112 ++++++++++++++++++ 5 files changed, 112 insertions(+) rename AUTHENTIK-CREATE-INVITATION-FLOW.md => docs/troubleshooting/AUTHENTIK-CREATE-INVITATION-FLOW.md (100%) rename AUTHENTIK-FIX-TEMPLATE.md => docs/troubleshooting/AUTHENTIK-FIX-TEMPLATE.md (100%) rename AUTHENTIK-INVITATION-FLOW-FIX.md => docs/troubleshooting/AUTHENTIK-INVITATION-FLOW-FIX.md (100%) rename DIAGNOSTIK-AUTHENTIK-FLOW.md => docs/troubleshooting/DIAGNOSTIK-AUTHENTIK-FLOW.md (100%) create mode 100644 docs/troubleshooting/README.md diff --git a/AUTHENTIK-CREATE-INVITATION-FLOW.md b/docs/troubleshooting/AUTHENTIK-CREATE-INVITATION-FLOW.md similarity index 100% rename from AUTHENTIK-CREATE-INVITATION-FLOW.md rename to docs/troubleshooting/AUTHENTIK-CREATE-INVITATION-FLOW.md diff --git a/AUTHENTIK-FIX-TEMPLATE.md b/docs/troubleshooting/AUTHENTIK-FIX-TEMPLATE.md similarity index 100% rename from AUTHENTIK-FIX-TEMPLATE.md rename to docs/troubleshooting/AUTHENTIK-FIX-TEMPLATE.md diff --git a/AUTHENTIK-INVITATION-FLOW-FIX.md b/docs/troubleshooting/AUTHENTIK-INVITATION-FLOW-FIX.md similarity index 100% rename from AUTHENTIK-INVITATION-FLOW-FIX.md rename to docs/troubleshooting/AUTHENTIK-INVITATION-FLOW-FIX.md diff --git a/DIAGNOSTIK-AUTHENTIK-FLOW.md b/docs/troubleshooting/DIAGNOSTIK-AUTHENTIK-FLOW.md similarity index 100% rename from DIAGNOSTIK-AUTHENTIK-FLOW.md rename to docs/troubleshooting/DIAGNOSTIK-AUTHENTIK-FLOW.md diff --git a/docs/troubleshooting/README.md b/docs/troubleshooting/README.md new file mode 100644 index 0000000..f1ae561 --- /dev/null +++ b/docs/troubleshooting/README.md @@ -0,0 +1,112 @@ +# 🔧 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 ` +- **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