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

```bash
# 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?
   ```bash
   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

```bash
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?