axion1337.chat-gitops/docs/troubleshooting/AUTHENTIK-INVITATION-FLOW-FIX.md

🔧 Authentik Invitation Flow Fix – Für Einladungslinks

Problem:

• Standard Enrollment (akadmin): ✅ funktioniert
• Invitation Flow (Boje über Einladungslink): ❌ Nur Username gefragt, keine Email
• Nach Enrollment: "Fehler fehlende Rechte"

Root Cause: Invitation Flow erfasst nicht alle erforderlichen Felder (Email) für OIDC-Token-Generation.

---

Phase 1: Diagnose im Authentik Admin UI

# Authentik Admin UI öffnen
kubectl port-forward -n authentik svc/authentik 9000:9000
# Browser: http://localhost:9000/
# Admin credentials: akadmin / (password)

1.1 Überprüfe: Welche Flows existieren?

Navigation: Admin → Flows & Stages → Flows

Suche nach diesen Flows:

• enrollment – Standard Enrollment (für akadmin)
• invitation – Invitation Flow (für Einladungslinks)
• default-authentication-flow – Standard Login

1.2 Überprüfe: Standard Enrollment Flow (funktioniert)

Navigation: Flows → enrollment öffnen

Stages sollten sein:

1. Identify (if not exists)
   └─ Binding: "Identification (if not exists)"

2. Write
   └─ Binding: "Create or update user"
   └─ Field bindings MUST include:
      ├─ username
      ├─ email  ← WICHTIG
      └─ name (optional)

3. (optional) Weitere Stages

4. Finish

Wichtig: Alle Felder müssen "required" sein (nicht optional).

1.3 Überprüfe: Invitation Flow (wahrscheinlich kaputt)

Navigation: Flows → invitation öffnen

Problem: Wahrscheinlich fehlt die "Email" Stage hier!

Sollte sein:

1. Invite Stage
   └─ Binding: "Invite user"

2. Identification (if not exists)
   └─ Binding: "Identify"

3. Prompt Stage (für zusätzliche Daten!)
   └─ Binding: "Prompt for data"
   └─ Fields: username, email, name, password

4. Write
   └─ Binding: "Create or update user"

5. Finish

---

Phase 2: Reparatur der Invitation Flow

Schritt 1: Neue "Prompt Stage" erstellen (falls nicht existiert)

Navigation: Admin → Flows & Stages → Stages

1. Klick "Create"

2. Name: invitation-prompt oder ähnlich

3. Type: "Prompt Stage"

4. Configure:

   • Fields to Prompt:
     • Username (required)
     • Email (required) ← WICHTIG
     • Name (optional)
     • Password (optional, da OIDC)

5. Save

Schritt 2: Invitation Flow reparieren

Navigation: Admin → Flows & Stages → Flows → invitation

Stages in dieser Reihenfolge:

Stage 1: Invite Stage
├─ Binding: "Invite"
├─ Required: Yes

Stage 2: Identification Stage
├─ Binding: "Identify" (oder "Identification (if not exists)")
├─ Required: No

Stage 3: [NEUE STAGE] Prompt für Email/Username
├─ Type: "Prompt Stage"
├─ Binding: "Prompt for data"
├─ Fields:
│  ├─ username (required)
│  ├─ email (required) ← ENTSCHEIDEND
│  └─ name (optional)
├─ Required: Yes

Stage 4: Write
├─ Binding: "Create or update user"
├─ User Creation Policies: (standard)
├─ Required: Yes

Stage 5: Finish
├─ Binding: "Finish"
├─ Required: Yes

Speichern und Testen!

---

Phase 3: Teste Invitation Flow

Test 1: Neuen Einladungslink erstellen

Navigation: Admin → Users & Groups → Invitations

1. Klick "Create"
2. Expiry: 7 days
3. Create & Copy Link

Test 2: Einladungslink öffnen (in neuem Browser/Inkognito)

1. Link öffnen

2. Enrollment Flow sollte jetzt:

   • Username eingeben
   • Email eingeben ← Das sollte jetzt da sein!
   • Name eingeben (optional)
   • "Sign in with Authentik" klicken (falls Authentik-Binding korrekt)

3. Nach Authentik-Login: User in Synapse erstellt?

   kubectl exec -it -n matrix matrix-stack-postgres-0 -- \
     psql -U synapse -d synapse -c "SELECT name FROM users WHERE created_ts > now() - interval '5 minutes';"
   

Test 3: Prüfe MAS Logs auf Fehler

kubectl logs -f matrix-stack-matrix-authentication-service-6b994b9fcf-qqcxz -n matrix | grep -i "error\|fail\|boje"

---

Phase 4: Häufige Fehler & Lösungen

Fehler 1: "Fehlende Rechte" nach Enrollment

Symptom: Enrollment abgeschlossen, aber Fehler auf Berechtigungsseite

Ursachen:

• Email-Feld wurde nicht erfasst
• OIDC-Token hat unvollständige Daten
• Synapse User konnte nicht erstellt werden (Duplikat?)

Lösung:

1. Authentik Logs prüfen: kubectl logs -n authentik -l app.kubernetes.io/name=authentik -f | grep -i "error\|invitation"
2. MAS Logs prüfen: kubectl logs -f matrix-stack-matrix-authentication-service-6b994b9fcf-qqcxz -n matrix | grep -i "boje\|error"
3. Synapse Logs prüfen: kubectl logs -f -n matrix matrix-stack-synapse-0 | grep -i "boje\|register"

Fehler 2: "Stage not found" oder "Flow invalid"

Ursache: Invitation Flow hat Binding-Fehler

Lösung:

1. Admin UI → Flows → Invitation Flow öffnen
2. Alle Stages überprüfen, dass sie korrekt gebunden sind
3. Keine leeren/ungültigen Bindings
4. Save & Retry

Fehler 3: Email-Feld wird nicht angezeigt

Ursache: Prompt Stage hat email nicht in Fields

Lösung:

1. Admin UI → Flows → Stages → Prompt Stage öffnen
2. Edit → Fields überprüfen
3. Email hinzufügen if missing:
   • Field name: email
   • Type: email
   • Required: Yes
4. Save

---

Erwarteter Ablauf nach Fix

1. Browser öffnet Einladungslink → Enrollment Flow
2. "Username eingeben" → z.B. "boje"
3. "Email eingeben" ← Sollte jetzt da sein
4. "Name eingeben" (optional)
5. "Weiter" oder "Mit Authentik anmelden"
6. Authentik Login
7. Enrollment abgeschlossen
8. User "boje" in Synapse DB angelegt
9. Login zu ElementWeb möglich

---

Checkliste

• Authentik Admin UI geöffnet (port-forward 9000)
• Standard Enrollment Flow überprüft (funktioniert mit akadmin)
• Invitation Flow überprüft
• Prompt Stage existiert mit email field
• Invitation Flow hat alle 5 Stages in korrekter Reihenfolge
• Neuen Einladungslink erstellt und getestet
• Test-User hat Email eingeben können
• Test-User in Synapse DB nach Login
• MAS Logs zeigen keine Fehler

---

Frage: Stimmt das mit deiner Beobachtung überein - dass bei der Einladung nur Username gefragt wurde, aber nicht die Email?

Wenn ja, dann ist der Fix:

1. Prompt Stage erstellen/reparieren (mit email field)
2. Zur Invitation Flow hinzufügen
3. Testen

Soll ich dir noch mehr Detailschritte geben?