axion1337.chat-gitops/docs/troubleshooting/DIAGNOSTIK-AUTHENTIK-FLOW.md

# 🔍 Authentik Enrollment Flow – Diagnostik & Reparaturplan

**Symptom**: 
- `akadmin` wurde manuell in Matrix-DB angelegt (funktioniert)
- `Boje` wurde nur in Authentik erstellt, nicht in Matrix-DB (kaputt)
- Beide sollen denselben Enrollment Flow verwenden

**Vermutung**: Die Authentik → MAS → Synapse Kette ist unterbrochen

---

## Phase 1: Diagnose (Bestandsaufnahme)

### 1.1 Authentik Logs prüfen

```bash
# Authentik Server logs
kubectl logs -n authentik -l app.kubernetes.io/name=authentik -f | grep -i "oauth\|oidc\|enroll\|flow"

# Worker logs
kubectl logs -n authentik -l app.kubernetes.io/component=worker -f | grep -i "enroll"
```

**Worauf achten**:
- Fehler bei "Enrollment create"?
- OIDC Token-Probleme?
- Flow-Validierungsfehler?

### 1.2 MAS (Matrix Authentication Service) Logs prüfen

```bash
# MAS logs
kubectl logs -n matrix -l app=matrix-authentication-service -f | grep -i "oauth\|upstream\|user\|oidc"
```

**Worauf achten**:
- Verbindung zu Authentik erfolgreich?
- Token-Validierung fehlgeschlagen?
- User-Provisioning-Fehler?

### 1.3 Synapse Logs prüfen

```bash
# Synapse logs (für User-Erstellung)
kubectl logs -n matrix -l app=synapse -f | grep -i "user\|provision\|register\|auth"
```

**Worauf achten**:
- User-Registrierungs-Fehler?
- Provisioning-Fehler?
- Authentifizierungsprobleme?

---

## Phase 2: Authentik UI Überprüfung

### 2.1 Enrollment Flow inspizieren

```bash
# Authentik UI öffnen
kubectl port-forward -n authentik svc/authentik 9000:9000
# → Browser: http://localhost:9000
# → Admin UI → Flows & Stages → "Enrollment" Flow suchen
```

**Checklist**:
- [ ] Flow existiert und heißt "Enrollment"
- [ ] Reihenfolge der Stages:
  1. Identify (optional)
  2. Write (User-Erstellung)
  3. Enrollment (if-condition für neuen User)
  4. Verification (optional)
- [ ] "Write Stage" bindet sich an:
  - [ ] Username
  - [ ] Email
  - [ ] Name
- [ ] Alle Bindings sind "required" (nicht optional)

### 2.2 OIDC Provider in Authentik prüfen

```bash
# Über Authentik UI:
# Admin → Applications → Providers → "matrix-provider" (oder ähnlich)
```

**Checklist**:
- [ ] Provider existiert
- [ ] Name: z.B. "matrix-provider"
- [ ] Client Type: "Confidential"
- [ ] Redirect URIs enthalten:
  - [ ] `https://account.axion1337.chat/upstream/callback/*`
  - [ ] `https://account.axion1337.chat/upstream/callback/01KQDJTR1ZVTG8JQ220F5BNBFZ` (exact)
- [ ] Scopes: `openid profile email`
- [ ] Client ID + Secret kopiert?

### 2.3 OIDC Application in Authentik

```bash
# Admin → Applications → Applications → "matrix"
```

**Checklist**:
- [ ] Application existiert mit Slug "matrix"
- [ ] Provider ist zugewiesen
- [ ] Enrollment Flow ist zugewiesen (nicht "deny")
- [ ] Enrollment Flow ist die richtige (die von oben)

### 2.4 Test-User "Boje" inspizieren

```bash
# Admin → Directory → Users → "Boje"
```

**Checklist**:
- [ ] Username: `boje`
- [ ] Email: `boje@...` (vorhanden?)
- [ ] Groups: Falls erforderlich, die richtigen Groups zugewiesen?
- [ ] Status: Active oder Disabled?
- [ ] Sessions: Aktive Logins?

---

## Phase 3: MAS Konfiguration überprüfen

### 3.1 Current MAS Secret auslesen

Da der age-key nicht lokal verfügbar ist, müssen wir die Konfiguration im Cluster prüfen:

```bash
# MAS Config im Cluster auslesen (nicht verschlüsselt)
kubectl get secret ess-mas-values-secret -n matrix -o jsonpath='{.data.values\.yaml}' | base64 -d | yq . | head -100
```

**Worauf achten**:
- [ ] `upstream_oauth2_config` Block existiert
- [ ] `upstream_oauth2_config.issuer`: `https://auth.axion1337.chat/application/o/matrix/`
- [ ] `upstream_oauth2_config.client_id`: Authentik Client ID
- [ ] `upstream_oauth2_config.client_secret`: Authentik Client Secret (*)
- [ ] `upstream_oauth2_config.scopes`: `["openid", "profile", "email"]`
- [ ] `upstream_oauth2_config.user_mapping_provider`:
  - `type`: "oidc"
  - `config.localpart_template`: `{{ user.preferred_username }}`
  - `config.display_name_template`: `{{ user.name }}`
  - `config.email_template`: `{{ user.email }}`

### 3.2 MAS Pod exec – Config live prüfen

```bash
# MAS Config im laufenden Pod inspizieren
kubectl exec -it -n matrix deployment/matrix-authentication-service -- cat /etc/mas/config.yaml | grep -A50 upstream_oauth2_config
```

**Worauf achten**:
- Config ist syntaktisch korrekt (YAML)?
- Indentierung ist richtig?
- Werte sind vorhanden?

### 3.3 MAS OIDC Discovery prüfen

```bash
# Authentik OIDC Discovery Endpoint
curl -s https://auth.axion1337.chat/application/o/matrix/.well-known/openid-configuration | jq .

# Sollte zurückgeben:
# {
#   "issuer": "https://auth.axion1337.chat/application/o/matrix/",
#   "token_endpoint": "https://auth.axion1337.chat/application/o/token/",
#   "authorization_endpoint": "...",
#   ...
# }
```

---

## Phase 4: Login-Flow Testen

### 4.1 MAS Login UI öffnen

```bash
# Port-Forward zu MAS
kubectl port-forward -n matrix svc/matrix-authentication-service 8765:8080
# → Browser: http://localhost:8765
```

**Test**:
1. Auf MAS-Seite: "Sign in with Authentik" klicken
2. Authentik-Login durchführen
3. Auf Enrollment Flow warten
4. Neuen User erstellen (Test-Username, Email, Password)
5. Nach erfolgreicher Registrierung: Matrix home_server erhalten?

### 4.2 Fehlerberichte

Falls Fehler auftritt:
- [ ] Screenshot des Fehlers
- [ ] MAS logs auslesen: `kubectl logs -n matrix -l app=matrix-authentication-service --tail=50`
- [ ] Authentik logs auslesen: `kubectl logs -n authentik -l app.kubernetes.io/name=authentik --tail=50`

---

## Phase 5: Reparaturschritte (nachdem Diagnose klar ist)

### Falls MAS-Config fehlerhaft:

```bash
# 1. Secrets entschlüsseln (lokale Umgebung mit age-key erforderlich)
sops -d apps/production/custom-configs/mas-secret.yaml > /tmp/mas-secret-decrypted.yaml

# 2. Editor öffnen und Konfiguration reparieren
vim /tmp/mas-secret-decrypted.yaml
# → upstream_oauth2_config überprüfen und korrigieren

# 3. Wieder verschlüsseln
sops -e /tmp/mas-secret-decrypted.yaml > apps/production/custom-configs/mas-secret.yaml

# 4. Commiten
git add apps/production/custom-configs/mas-secret.yaml
git commit -m "Fix: Correct MAS upstream_oauth2_config for Authentik integration"

# 5. Flux triggern
flux reconcile kustomization production-apps --with-source
```

### Falls Authentik Enrollment Flow fehlerhaft:

1. Admin UI öffnen: `kubectl port-forward -n authentik svc/authentik 9000:9000`
2. Flows → Enrollment Flow öffnen
3. Stages überprüfen und in richtige Reihenfolge bringen:
   - **Identify**: Benutzer identifizieren
   - **Write**: Benutzer in DB speichern
   - **Enrollment**: Weitere Felder (optional)
   - **Finish**: Abschluss
4. Speichern
5. Neuen Test-User erstellen und Enrollment durchlaufen

---

## Erwartete Endergebnisse

Nach erfolgreichem Fix:
1. Benutzer klickt "Sign in with Authentik" auf MAS
2. Authentik-Login-Seite wird angezeigt
3. Nach Login: Enrollment Flow wird angezeigt
4. User füllt Formular aus
5. Nach "Finish": Authentik erstellt User UND verbindet zu Matrix
6. User wird in Matrix-DB angelegt (`_matrix_auth` prefix)
7. User kan sich bei ElementWeb anmelden

---

## 🎯 Nächster Schritt

Bitte folgende Diagnostik durchlaufen und mir die Output berichte:

1. **MAS Logs** (letzten 30 Zeilen)
2. **Authentik Logs** (letzten 30 Zeilen) 
3. **MAS Secret (entschlüsselt)** – upstream_oauth2_config Block
4. **Authentik OIDC Discovery** Output
5. **Screenshots** der Authentik UI (Enrollment Flow, OIDC Provider, Application)

Damit kann ich dann genau sehen, wo der Bruch in der Kette ist! 🔗