axion1337.chat-gitops/docs/troubleshooting/AUTHENTIK-FIX-TEMPLATE.md

# ✅ Authentik Enrollment Flow – Reparatur-Template

Basierend auf häufigen Problemen: Hier sind die wahrscheinlichsten Fixes.

---

## Problem 1: MAS kennt Authentik-OIDC nicht

### Symptom
- MAS zeigt "Sign in with Authentik" Button nicht
- Logs: "upstream provider not configured"

### Lösung

**MAS Secret muss diesen Block enthalten:**

```yaml
# apps/production/custom-configs/mas-secret.yaml (decrypted)
---
matrixAuthenticationService:
  upstream_oauth2_config:
    issuer: "https://auth.axion1337.chat/application/o/matrix/"
    client_id: "{{ CLIENT_ID_FROM_AUTHENTIK }}"
    client_secret: "{{ CLIENT_SECRET_FROM_AUTHENTIK }}"
    authorization_endpoint: "https://auth.axion1337.chat/application/o/authorize/"
    token_endpoint: "https://auth.axion1337.chat/application/o/token/"
    userinfo_endpoint: "https://auth.axion1337.chat/application/o/userinfo/"
    scopes:
      - "openid"
      - "profile"
      - "email"
    user_mapping_provider:
      type: "oidc"
      config:
        localpart_template: "{{ user.preferred_username }}"
        display_name_template: "{{ user.name }}"
        email_template: "{{ user.email }}"
  
  # Wichtig: Password-Login deaktivieren (da wir nur OIDC verwenden)
  passwords:
    enabled: false
```

**Wie ausfüllen:**

1. Authentik Admin UI öffnen: `https://auth.axion1337.chat`
2. Admin → Applications → Providers → "matrix-provider" (oder ähnlich)
3. Folgende Werte kopieren:
   - **Client ID**: Im Provider-Details zu sehen
   - **Client Secret**: Im Provider-Details zu sehen (unter "Credentials")

4. Local entschlüsseln (mit age-key):
```bash
cd gitops/
sops -d -i apps/production/custom-configs/mas-secret.yaml
```

5. Datei öffnen und die Werte einfügen

6. Wieder verschlüsseln:
```bash
sops -e -i apps/production/custom-configs/mas-secret.yaml
```

7. Commiten:
```bash
git add apps/production/custom-configs/mas-secret.yaml
git commit -m "Fix: Configure MAS upstream OIDC for Authentik"
git push
```

8. Flux triggern:
```bash
flux reconcile kustomization production-apps --with-source
```

9. Warten, dass MAS Pod neu startet:
```bash
kubectl get pods -n matrix -l app=matrix-authentication-service -w
```

---

## Problem 2: Authentik Enrollment Flow ist kaputt

### Symptom
- User kommt zu Authentik-Login
- Nach Login: "Error: Enrollment stage not found" oder ähnlich
- Oder: Flow bricht ohne Fehlermeldung ab

### Lösung

**Authentik UI → Flows & Stages → Enrollment Flow überprüfen:**

```
Flows → Enrollment
├── Stage 1: "Identify" (if not exists)
│   └── Binding: "Identification (if not exists)"
├── Stage 2: "Write" (wichtig!)
│   └── Binding: "Create or update user"
│   └── User Creation Policies: ???
├── Stage 3: (optional) Weitere Datenerfassung
└── Stage 4: "Finish"
```

**Häufiger Fehler**: "Write" Stage ist nicht korrekt mit den benötigten Feldern konfiguriert.

**Fix:**

1. Authentik Admin UI: `https://auth.axion1337.chat`
2. **Flows & Stages** → **Stages**
3. Nach "Write" Stage suchen (Filter: "write")
4. Klick auf "Write Stage"
5. **Field Bindings** überprüfen:
   - [ ] `username` ← MUSS mit Authentik Username bindbar sein
   - [ ] `email` ← MUSS vorhanden sein
   - [ ] `name` ← Optional, aber empfohlen
6. Alle sollten "required" sein (nicht optional)
7. **Save**

Dann zurück zu **Flows** → **Enrollment**:
1. Stages überprüfen (oben)
2. Bindings überprüfen:
   - Each Stage hat "Binding" Feld
   - "Write" Stage sollte mit "Create or update user" gebunden sein
3. **Save**

---

## Problem 3: OIDC Token werden nicht korrekt zu Synapse weitergeleitet

### Symptom
- User kommt bis zu ElementWeb
- Nach Login zu Authentik: "User not found in Synapse" oder Loop
- Oder: User wird in Authentik angelegt, aber nicht in Synapse

### Lösung

Das ist komplexer und erfordert MAS-Konfiguration + Synapse-Konfiguration.

**MAS Config (upstream_oauth2_config)** muss korrekt sein (siehe Problem 1).

**Zusätzlich in MAS Secret:**

```yaml
# apps/production/custom-configs/mas-secret.yaml
matrixAuthenticationService:
  # ... upstream_oauth2_config ...
  
  # User-Provisioning Konfiguration
  access:
    # Benutzer aus OIDC Provider automatisch erzeugen
    auto_provision: true
    # Synapse URL
    home_server: "https://matrix.axion1337.chat"
```

---

## Problem 4: ElementWeb zeigt nicht automatisch OIDC-Button

### Symptom
- MAS läuft und hat OIDC konfiguriert
- ElementWeb zeigt nur "Sign in with username" oder "SAML login"
- Kein "Sign in with Authentik" Button

### Lösung

ElementWeb muss die MAS-Konfiguration kennen. Das geschieht über `.well-known/matrix/client`:

**Test:**
```bash
curl https://axion1337.chat/.well-known/matrix/client | jq '.authentication'
```

Sollte zurückgeben:
```json
{
  "flows": [
    {
      "stages": ["m.login.sso"]
    }
  ],
  "identity_providers": [
    {
      "id": "authentik",
      "name": "Authentik",
      "icon": "...",
      "brand": "custom"
    }
  ]
}
```

Falls nicht: **ElementWeb Config in Element-Stack aktualisieren:**

```yaml
# apps/production/custom-configs/element-values.yaml
elementWeb:
  config:
    auth:
      sso_redirect_options:
        immediate: false
        on_welcome_page: true
```

**Dann:**
```bash
git add apps/production/custom-configs/element-values.yaml
git commit -m "Fix: Enable SSO redirect in ElementWeb"
git push
flux reconcile kustomization production-apps --with-source
```

---

## Problem 5: User kann sich anmelden, aber Boje ist nicht in Matrix

### Symptom
- Authentik-Login funktioniert
- MAS zeigt User erfolgreich
- ElementWeb Login funktioniert
- **ABER**: User ist nicht in Synapse (check mit `kubectl exec -n matrix synapse ...`)

### Lösung

Das bedeutet: User wird nicht automatisch in Synapse provisioniert.

**MAS muss User zu Synapse erstellen:**

In MAS Secret, `access` Sektion:

```yaml
matrixAuthenticationService:
  access:
    # Synapse erlaubt neue User-Erstellung
    homeserver: "https://matrix.axion1337.chat"
    
    # Optional: User automatisch erstellen
    registration_enabled: true
```

**Synapse-seitig** muss auch User-Erstellung erlaubt sein:

```yaml
# apps/production/custom-configs/synapse-values.yaml
synapse:
  additional:
    registration:
      config: |
        enable_registration: true
        enable_registration_without_token: false
        # Token wird von MAS bereitgestellt
```

---

## Komplettes Test-Szenario

Nach allen Fixes:

1. **Browser 1**: `https://axion1337.chat` öffnen
2. Auf ElementWeb "Sign in" klicken
3. "Sign in with Authentik" klicken (sollte sichtbar sein)
4. Authentik-Login durchführen (akadmin)
5. Nach Login: Enrollment-Flow (nur falls neuer User)
6. Zurück zu ElementWeb
7. **Synapse prüfen**:
```bash
kubectl exec -it -n matrix deployment/synapse -- \
  /usr/local/bin/psql -U synapse -d synapse -c "SELECT name, admin FROM users LIMIT 10;"
```
8. Neuer User sollte auftauchen

---

## Debugging-Commands (während Test)

```bash
# Live MAS logs (folgen)
kubectl logs -n matrix -l app=matrix-authentication-service -f

# Authentik logs
kubectl logs -n authentik -l app.kubernetes.io/name=authentik -f

# Port-Forward für manuelles Testen
kubectl port-forward -n matrix svc/matrix-authentication-service 8765:8080

# MAS Secret auslesen (im Cluster)
kubectl get secret ess-mas-values-secret -n matrix -o jsonpath='{.data.values\.yaml}' | base64 -d

# Synapse User-Liste
kubectl exec -it -n matrix deployment/synapse -- \
  /usr/local/bin/psql -U synapse -d synapse -c "SELECT name, admin, is_guest FROM users;"
```

---

## Checkliste für erfolgreichen Fix

- [ ] MAS Secret decrypted, upstream_oauth2_config eingetragen
- [ ] Client ID + Secret von Authentik kopiert
- [ ] MAS Secret re-encrypted und commited
- [ ] Authentik Enrollment Flow überprüft
- [ ] OIDC Provider in Authentik aktiv
- [ ] OIDC Application "matrix" in Authentik existiert
- [ ] MAS Pod neu gestartet (nach Secret-Change)
- [ ] ElementWeb zeigt OIDC-Button
- [ ] Test-Login durchgeführt
- [ ] Neuer User in Synapse DB vorhanden

---

**Fragen?** → Siehe `DIAGNOSTIK-AUTHENTIK-FLOW.md` für tiefergehende Diagnose.