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

```bash
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!** 🚀