Zum Hauptinhalt springen

🔐 Fehlerbehebung bei OAUTH / SSO-Problemen

OAUTH oder Single Sign-On (SSO) ermöglicht es Ihnen, Open WebUI mit moderner Authentifizierung zu sichern. Wenn Benutzer jedoch auf Anmeldeprobleme stoßen, ist die Lösung oft einfach – wenn Sie wissen, wo Sie suchen müssen. Meistens ist eines der folgenden Schlüsselprobleme die Ursache. Hier erfahren Sie, wie Sie diese schnell aufspüren und SSO-Probleme beheben! 🚦

Häufige OAUTH/SSO-Probleme und wie man sie behebt 🛠️​

1. WebUI-URL nicht im Admin-Panel konfiguriert 🚪🔒​

Die meisten OAUTH-Flows erfordern die externe URL der Anwendung („Redirect URI“), damit der Anbieter weiß, wohin er die Benutzer nach der Anmeldung weiterleiten soll. Wenn diese fehlt, kann OAUTH nicht abgeschlossen werden!

✅ Lösung

  • Navigieren Sie zu: Admin-Einstellungen > Allgemein
  • Stellen Sie sicher, dass Ihr Feld WebUI URL ausgefüllt ist und auf Ihre bereitgestellte Instanz verweist (z. B. https://yourwebui.yourdomain.com) 📌 Tipp: Achten Sie auf Tippfehler! OAUTH ist streng – URLs müssen exakt übereinstimmen, einschließlich https://.

2. Falsche Konfiguration der Umgebungsvariablen 📝🚫​

Dies ist mit Abstand die häufigste Ursache für OAUTH-Fehler. Wenn Sie eine Umgebungsvariable falsch schreiben, weglassen oder die falsche setzen (insbesondere für OIDC/OAUTH-Konfigurationen), kann die Authentifizierung nicht funktionieren.

✅ Lösungen

  • Überprüfen Sie Ihre Bereitstellungsumgebung
    • Stellen Sie sicher, dass alle erforderlichen Umgebungsvariablen gesetzt sind (siehe Dokumentation für Namen wie OIDC_CONFIG, OAUTH_CLIENT_ID usw.)
    • Wenn Sie selbst hosten, bestätigen Sie, dass diese Variablen in Ihrer Docker Compose-, Kubernetes-Manifest- oder .env-Datei vorhanden sind.
  • Starten Sie Ihr Backend/Ihre App nach der Änderung von Variablen neu, damit die neuen Werte geladen werden.

📌 Tipp: Die meisten OAUTH-Fehler (Schleifen, 401er, Nichtreagieren) sind auf eine falsch konfigurierte oder gänzlich fehlende Umgebungsvariable zurückzuführen!

3. OAUTH-Fehlkonfiguration auf der Anbieterseite 🏢🔗​

Manchmal liegt das Problem beim Identitätsanbieter (z. B. Google, Okta, Auth0, Azure AD), der nicht mit der Einrichtung Ihrer WebUI übereinstimmt.

✅ Lösungen

  • Verifizieren Sie, dass Ihre Anwendung korrekt beim OAUTH-Anbieter registriert ist. Bestätigen Sie
    • Redirect URIs stimmen exakt mit Ihrer bereitgestellten WebUI-Adresse überein
    • Client ID und Secret stimmen mit den in Ihren Umgebungseinstellungen angegebenen Werten überein
    • Scopes und erlaubte Grant-Typen (z. B. authorization_code) sind wie von Open WebUI gefordert eingestellt
  • Überprüfen Sie die Protokolle des Anbieters – falsch konfigurierte Apps zeigen dort oft klare Fehlermeldungen.

📌 Tipp: Im Zweifelsfall überprüfen Sie Ihre Anbieterregistrierung erneut und generieren Sie Client-Secrets bei Bedarf neu.

4. Serverseitiges Caching (Ein versteckter Stolperstein!) 🧊🚦​

Ein neues und kniffliges Problem: Wenn Sie NGINX (oder einen anderen Reverse-Proxy) mit serverseitigem Caching verwenden, können OAUTH-Endpunkte fehlschlagen. Das Ergebnis ist nicht immer ein Totalausfall – oft erleben Benutzer zufällige oder „komische“ Anmeldefehler, die fast unmöglich zu debuggen sind.

✅ Lösungen

  • In Ihrer NGINX (oder Proxy)-Konfiguration
    • Stellen Sie sicher, dass Sie die folgenden Endpunkte vom serverseitigen Caching ausschließen
      • /api, /oauth, /callback, /login, /ws, /websocket
    • Jeder kritische Login-/Auth-Endpunkt muss un-gecached bleiben!
  • Laden Sie die Proxy-Konfiguration nach Änderungen neu.

📌 Warnung: Cachen Sie niemals OAUTH- oder Login-Endpunkte! Caching kann die Sitzung „vergiften“ oder veraltete Tokens liefern, was zu bizarren Authentifizierungsfehlern führt.

🧪 Profi-Tipp: Überprüfen Sie immer die Logs​

  • Schauen Sie sich die Backend-Logs und Browser-Netzwerkfehler an. Der erste Fehler weist normalerweise auf die Fehlkonfiguration hin (Redirect-URI-Mismatch, fehlende/ungültige Variable, Anbieterseitenfehler oder Caching).
  • Wenn Sie unsicher sind, welche Seite das Problem verursacht, versuchen Sie, sich von einem Inkognito-Browserfenster aus anzumelden und achten Sie auf blockierte oder fehlgeschlagene Anfragen.

Zusammenfassende Checkliste ✅​

ProblemBehebung
🔗 WebUI-URL fehlt oder ist falschKorrekte WebUI-URL im Admin-Panel setzen
📝 Tippfehler oder fehlende UmgebungsvariableAlle OAUTH/SSO-Umgebungsvariablen überprüfen und setzen
🏢 Anbieter falsch konfiguriertApp-Registrierung, URIs & Client-IDs/Secrets bestätigen
🧊 Proxy-Caching störtOAUTH-Endpunkte von allen serverseitigen Caches ausschließen
Immer noch fest?Logs überprüfen und ohne Caches testen

Durch sorgfältige Konfiguration SOWOHLS Ihres OAUTH-Anbieters ALS AUCH Ihrer WebUI-Umgebung – und indem Sie kritische Login-Endpunkte vor Caching schützen – werden Sie nahezu alle SSO/OAUTH-Anmeldeprobleme beseitigen. Lassen Sie nicht zu, dass ein Tippfehler oder ein verstecktes Cache Ihre Benutzer vom nahtlosen, sicheren KI-Zugang abhält! 🦾