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

🆕 Authentik: Neuen Invitation Flow erstellen

Problem:

• Nur ein matrix-enrollment Flow existiert
• Wird für Standard-Signup + Invitations verwendet → Konflikt
• Fehler: "Found existing plan for other flow, deleting plan"

Lösung: Separaten matrix-invitation Flow für Einladungslinks erstellen.

---

Schritt 1: Authentik Admin UI öffnen

kubectl port-forward -n authentik svc/authentik 9000:9000
# Browser: http://localhost:9000/
# Admin: akadmin / (password)

---

Schritt 2: Neuen Flow erstellen

Navigation: Admin → Flows & Stages → Flows

1. Klick "Create" (oben rechts)
2. Fülle folgendes aus:

Name: matrix-invitation
Slug: matrix-invitation
Title: Matrix Enrollment via Invitation
Description: Enrollment flow for users created via invitation links
Designation: enrollment

3. Speichern (Save)

---

Schritt 3: Stages zur Invitation Flow hinzufügen

Nach dem Erstellen wirst du auf die Flow-Edit-Seite weitergeleitet.

Navigation: Admin → Flows & Stages → Flows → matrix-invitation → Edit

Klick auf "Add Stage" und folge dieser Reihenfolge:

Stage 1: Invite Stage (Invitation verarbeiten)

1. Klick "Add Stage"
2. Wähle: "Invite Stage"
3. Konfiguriere:

   Name: Invite
   Order: 1
   

4. Save

Dann musst du das Binding setzen:

• Klick auf die Stage in der Flow
• Binding: "Invite" (oder "Invitation")
• Required: Yes
• Save

Stage 2: Identification Stage (Username überprüfen)

1. Klick "Add Stage"
2. Wähle: "Identification Stage" (nicht "Authenticate Stage")
3. Konfiguriere:

   Name: Identification
   Order: 2
   User Fields: username (oder email)
   Create Users as Inactive: NO
   

4. Save

Binding setzen:

• Binding: "Identify"
• Required: No
• Save

Stage 3: Prompt Stage (Daten abfragen: Username, Email, Name)

1. Klick "Add Stage"
2. Wähle: "Prompt Stage"
3. Konfiguriere:

   Name: User Data
   Order: 3
   

4. Speichern (Save)

Dann Fields hinzufügen:

• Klick auf die Stage
• Klick "Add Field" für jedes Feld:

Field 1: Username

Field Name: username
Label: Username
Type: text
Required: Yes
Placeholder: Choose a username

Field 2: Email

Field Name: email
Label: Email Address
Type: email
Required: Yes
Placeholder: your@email.com

Field 3: Name (Optional)

Field Name: name
Label: Full Name
Type: text
Required: No
Placeholder: Your Name

Alle Fields Save.

Dann Stage-Binding setzen:

• Binding: "Prompt for data" (oder "User Data")
• Required: Yes
• Save

Stage 4: Write Stage (User in DB erstellen)

1. Klick "Add Stage"
2. Wähle: "Write Stage" (oder "User Write Stage")
3. Konfiguriere:

   Name: Create User
   Order: 4
   

4. Speichern (Save)

Dann Field Bindings setzen:

• Klick auf die Stage
• Unter "Field Bindings" oder "User Creation":
  • username ← mapped von username Feld
  • email ← mapped von email Feld
  • name ← mapped von name Feld
• Save

Stage-Binding setzen:

• Binding: "Create or update user"
• Required: Yes
• Save

Stage 5: Finish Stage (Abschluss)

1. Klick "Add Stage"
2. Wähle: "Finish Stage" (oder "User Login")
3. Konfiguriere:

   Name: Finish
   Order: 5
   

4. Speichern (Save)

Stage-Binding:

• Binding: "Finish" (oder "Complete enrollment")
• Required: Yes
• Save

---

Schritt 4: Flow als Standard-Invitation setzen

Navigation: Admin → System → Settings

Suche nach "Invitation Flow" oder "Default Flows":

1. Setze "Invitation Flow" auf matrix-invitation
2. Save

Alternativ:

• Admin → Flows & Stages → Flows
• Für jede Invitation/Group:
  • Klick auf Group/Invitation
  • Setze "Enrollment Flow" auf matrix-invitation

---

Schritt 5: Test mit neuem Einladungslink

1. Neuen Einladungslink erstellen:

   • Admin → Users & Groups → Invitations
   • Klick "Create"
   • Expiry: 7 days
   • Create & Copy Link

2. Link öffnen (neuer Browser/Inkognito):

   • Link in Browser öffnen
   • Sollte jetzt alle Felder zeigen:
     • Username eingeben
     • Email eingeben ← sollte jetzt da sein!
     • Name eingeben (optional)
     • "Weiter" oder "Sign in with Authentik"

3. Authentik Login (falls Binding korrekt):

   • Mit Authentik anmelden
   • Enrollment abgeschlossen
   • User sollte in Synapse erstellt sein

---

Troubleshooting

Fehler: "Stage not found"

• Stelle sicher, dass alle Stages ein Binding haben
• Alle Bindings müssen eindeutig sein (nicht doppelt)
• Save nach jeder Änderung

Felder werden nicht angezeigt

• Prompt Stage überprüfen
• Alle Fields müssen Save sein
• Ggfs. Browser-Cache löschen

Fehler nach Enrollment

• MAS Logs: kubectl logs -f matrix-stack-matrix-authentication-service-6b994b9fcf-qqcxz -n matrix
• Authentik Logs: kubectl logs -f -n authentik -l app.kubernetes.io/name=authentik

---

Erwartetes Ergebnis

Nach dem Fix:

1. Einladungslink öffnen → matrix-invitation Flow
2. Username, Email, Name eingeben
3. "Mit Authentik anmelden"
4. Nach Login: User in Synapse erstellt
5. Login zu ElementWeb möglich

---

Checkliste

• matrix-invitation Flow erstellt
• 5 Stages in korrekter Reihenfolge (Invite → Identify → Prompt → Write → Finish)
• Prompt Stage hat username, email, name Felder
• Alle Stages haben korrektes Binding
• matrix-invitation als Standard-Invitation-Flow gesetzt
• Neuen Einladungslink erstellt und getestet
• Test-User kann Email eingeben
• Test-User in Synapse DB nach Login

---

Sollte ca. 10-15 Minuten dauern! 🚀