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:

# 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):

cd gitops/
sops -d -i apps/production/custom-configs/mas-secret.yaml

5. Datei öffnen und die Werte einfügen

6. Wieder verschlüsseln:

sops -e -i apps/production/custom-configs/mas-secret.yaml

7. Commiten:

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

8. Flux triggern:

flux reconcile kustomization production-apps --with-source

9. Warten, dass MAS Pod neu startet:

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:

# 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:

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

Sollte zurückgeben:

{
  "flows": [
    {
      "stages": ["m.login.sso"]
    }
  ],
  "identity_providers": [
    {
      "id": "authentik",
      "name": "Authentik",
      "icon": "...",
      "brand": "custom"
    }
  ]
}

Falls nicht: ElementWeb Config in Element-Stack aktualisieren:

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

Dann:

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:

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:

# 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:

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)

# 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.