Open WebUI SSO einrichten: OIDC mit Entra ID, Keycloak und Authentik

SSO für Open WebUI nicht selbst einrichten? Die KI-Plattform von WZ-IT ist Open WebUI als Managed Service: eigene Instanz, Modelle in Deutschland bei deutschen Anbietern und SSO sind im Monatspreis ab 149,90 € netto enthalten. KI-Plattform ansehen · Anbindung gemeinsam klären

Open WebUI meldet Nutzer über OpenID Connect (OIDC) an einem Identitätsanbieter an. Die Konfiguration besteht aus wenigen Umgebungsvariablen und scheitert in der Praxis an Details: einer Redirect-URI, die um ein Zeichen abweicht, einem Claim, der nicht im Token steht, oder einem ersten Login, der den falschen Account zum Administrator macht. Dieser Leitfaden führt durch die Einrichtung mit Microsoft Entra ID und Keycloak, ordnet Authentik und ZITADEL ein und endet mit einer Prüfliste. Grundlage sind die Open-WebUI-Dokumentation, der Quellcode von Open WebUI v0.12.4 und die Dokumentation der Identitätsanbieter. Stand 28. Oktober 2026.

Inhaltsverzeichnis

• Welcher Anmeldeweg passt
• Vor dem ersten Login festlegen
• Basiskonfiguration
• Microsoft Entra ID
• Keycloak
• Authentik und ZITADEL
• Rollen und Gruppen
• SCIM und Offboarding
• Notfallzugang und Passwort-Login
• Mehrere Replicas und Reverse Proxy
• Typische Fehlerbilder
• Prüfliste nach der Einrichtung
• SSO und Lizenz bei WZ-IT
• Stand und Methodik
• Unser Vorgehen bei WZ-IT
• Weiterführende Guides

Welcher Anmeldeweg passt

Es lässt sich nur ein OIDC-Anbieter gleichzeitig konfigurieren, und der Microsoft-Provider unterstützt einen einzelnen Mandanten (SSO-Dokumentation). Beim Trusted Header darf Open WebUI nur für den Proxy erreichbar sein: Wer den Header selbst setzen kann, meldet sich als beliebiger Nutzer an. Der Rest des Leitfadens behandelt OIDC.

Vor dem ersten Login festlegen

1. Lokalen Administrator zuerst anlegen. Der erste Account einer frischen Instanz wird Administrator, auch wenn er über SSO entsteht: Der Code vergibt die Rolle admin, sobald nach dem Anlegen genau ein Nutzer existiert. WEBUI_ADMIN_EMAIL und WEBUI_ADMIN_PASSWORD legen den Account beim ersten Start an und schalten die Selbstregistrierung ab (Umgebungsvariablen).
2. WEBUI_URL vor dem ersten SSO-Login setzen. Die Variable ist eine persistente Einstellung: Spätere Änderungen der Umgebungsvariable greifen nicht mehr, nur der Admin-Bereich oder ENABLE_PERSISTENT_CONFIG=false.
3. WEBUI_SECRET_KEY fest vergeben. Er signiert die Sitzungstoken und verschlüsselt OAuth-Tokens. Ein automatisch erzeugter Schlüssel liegt im Container; wird dieser neu angelegt, sind alle Sitzungen ungültig.
4. Redirect-URI explizit setzen. Ohne OPENID_REDIRECT_URI leitet Open WebUI sie aus der Anfrage ab; hinter einem Proxy, der die URL verändert, weicht sie dann vom Eintrag im Identitätsanbieter ab.

Basiskonfiguration

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:v0.12.4   # Version festhalten
    environment:
      WEBUI_URL: "https://chat.example.com"
      WEBUI_SECRET_KEY: "${WEBUI_SECRET_KEY}"
      ENABLE_OAUTH_SIGNUP: "true"
      OAUTH_PROVIDER_NAME: "Keycloak"
      OAUTH_CLIENT_ID: "open-webui"
      OAUTH_CLIENT_SECRET: "${OAUTH_CLIENT_SECRET}"
      OPENID_PROVIDER_URL: "https://id.example.com/realms/firma/.well-known/openid-configuration"
      OPENID_REDIRECT_URI: "https://chat.example.com/oauth/oidc/callback"
      OAUTH_SCOPES: "openid email profile"

Microsoft Entra ID

1. App registrieren. Plattform "Web", Redirect-URI https://chat.example.com/oauth/microsoft/callback. Microsoft verlangt https (Ausnahme: localhost) und unterscheidet Groß- und Kleinschreibung im Pfad (Redirect-URI-Regeln).
2. Client-Secret anlegen. Die Laufzeit beträgt höchstens 24 Monate, Microsoft empfiehlt weniger als 12 (Anmeldeinformationen). Läuft das Secret ab, kann sich niemand mehr anmelden; Ablaufdatum und Erneuerung gehören in den Betriebskalender.
3. Berechtigungen: delegiert openid, email und profile mit Administratorzustimmung. Der Scope offline_access kommt in MICROSOFT_OAUTH_SCOPE hinzu; in Entra braucht er keine weitere Konfiguration. Ohne ihn scheitert nach etwa einer Stunde die Erneuerung der Tokens; betroffen sind Modellverbindungen mit OAuth und SharePoint-Zugriffe, der Chat selbst nicht (SSO-Dokumentation).

MICROSOFT_CLIENT_ID=<Anwendungs-ID>
MICROSOFT_CLIENT_SECRET=<Client-Secret>
MICROSOFT_CLIENT_TENANT_ID=<Verzeichnis-ID>
MICROSOFT_REDIRECT_URI=https://chat.example.com/oauth/microsoft/callback
MICROSOFT_OAUTH_SCOPE=openid email profile offline_access
ENABLE_OAUTH_SIGNUP=true

OPENID_PROVIDER_URL ist für Microsoft nicht erforderlich: Anmeldung und Abmeldung nutzen die Discovery-URL des Mandanten (SSO-Dokumentation, Fehlersuche). Die Community-Anleitung zur Gruppensynchronisation setzt sie dennoch als "Required for logout to work properly" (https://login.microsoftonline.com/<Verzeichnis-ID>/v2.0/.well-known/openid-configuration).

Zugriff begrenzen. Eine registrierte App steht standardmäßig allen Nutzern des Mandanten offen. Mit "Zuweisung erforderlich" kommen nur zugewiesene Nutzer und Gruppen durch, Globale Administratoren ausgenommen (Microsoft). Zusammen mit ENABLE_OAUTH_SIGNUP=true bekäme sonst jede Person des Mandanten ein Konto. Die Zuweisung von Gruppen (statt einzelner Nutzer) setzt Entra ID P1 oder P2 voraus, verschachtelte Gruppen werden dabei nicht berücksichtigt (Microsoft).

Rollen über App-Rollen. App-Rollen admin und user anlegen und Gruppen zuweisen; Entra schreibt sie in den Claim roles (Microsoft). In Open WebUI genügt ENABLE_OAUTH_ROLE_MANAGEMENT=true; die Standardwerte OAUTH_ROLES_CLAIM=roles, OAUTH_ALLOWED_ROLES=user,admin und OAUTH_ADMIN_ROLES=admin passen dazu.

Gruppen mit Fallstricken. Der Claim groups enthält standardmäßig Objekt-IDs, und ein JWT trägt höchstens 200 Gruppen; für große Organisationen empfiehlt Microsoft "Der Anwendung zugewiesene Gruppen" (Optionale Claims). Eine Auflösung per Graph-Abfrage bei Überschreitung enthält Open WebUI nicht (geprüft in utils/oauth.py). Klartextnamen liefern groupMembershipClaims: ApplicationGroup und die Eigenschaft cloud_displayname, die nur in dieser Kombination wirkt.

E-Mail-Claim. Open WebUI benötigt email. Microsoft nennt den Wert nicht garantiert korrekt und änderbar und rät, ihn nie für Autorisierung zu verwenden (Claims-Referenz). OAUTH_MERGE_ACCOUNTS_BY_EMAIL sollte deshalb nur befristet aktiv sein, etwa für die Übernahme lokaler Konten.

Keycloak

1. Client im eigenen Realm anlegen (nicht in master): Typ OpenID Connect, Client authentication an (vertraulicher Client), Standard Flow an. Die Redirect-URI https://chat.example.com/oauth/oidc/callback wird exakt und groß-/kleinschreibungssensitiv verglichen; Platzhalter sind nur am Ende des Musters möglich, der vollständige Platzhalter * gehört nicht in die Produktion (Keycloak). Das Secret steht im Reiter "Credentials".
2. Discovery-URL: https://id.example.com/realms/<Realm>/.well-known/openid-configuration (Keycloak, Endpunkte). Die Variablen entsprechen der Basiskonfiguration.

Rollen: Realm-Rollen stehen standardmäßig im Claim realm_access.roles, aber nur im Access Token und im Introspection-Endpunkt (Keycloak, Token-Rollen). Open WebUI liest die Claims aus ID-Token und Userinfo. Im Mapper "realm roles" muss deshalb "Add to ID token" aktiv sein; dann gilt OAUTH_ROLES_CLAIM=realm_access.roles (geschachtelte Pfade sind erlaubt) mit OAUTH_ADMIN_ROLES=admin.

Gruppen: Mapper "Group Membership" mit dem Claim-Namen groups und aktivem "Add to ID token". "Full group path" ist standardmäßig an und liefert Werte wie /engineering; für Namen ohne Schrägstrich abschalten (Mapper-Quellcode). Danach ENABLE_OAUTH_GROUP_MANAGEMENT=true.

Authentik und ZITADEL

Authentik: Anwendung mit OAuth2/OpenID-Provider, Redirect-URI vom Typ "Strict" auf /oauth/oidc/callback, Discovery unter https://<Authentik>/application/o/<Slug>/.well-known/openid-configuration. Rollen entstehen aus Application Entitlements und einem Scope-Mapping roles; dazu OAUTH_SCOPES="openid email profile roles" (Authentik, Support-Level: Community). Das dortige Beispiel schaltet Login-Formular und Passwort-Login ab und entfernt damit den lokalen Notfallzugang.

ZITADEL: Anwendungstyp Web; ZITADEL empfiehlt PKCE (ZITADEL), in Open WebUI mit OAUTH_CODE_CHALLENGE_METHOD=S256. Discovery: <Instanz>/.well-known/openid-configuration. Der Rollen-Claim urn:zitadel:iam:org:project:roles ist ein Objekt (Rolle zu Organisation) (ZITADEL, Claims); Open WebUI liest Listen oder Zeichenketten. Die ZITADEL-Dokumentation zeigt eine Action (Actions V1), die Rollen als flache Liste mit Werten der Form Projekt-ID:Rolle in einen eigenen Claim schreibt; Actions V1 sollen in ZITADEL V5 auslaufen, neue Umsetzungen gehören auf Actions V2 (ZITADEL, Migration).

Rollen und Gruppen

Die Gruppensynchronisation ist strikt: Wer in Open WebUI manuell einer Gruppe zugeordnet wurde, die nicht im Claim steht, verliert die Mitgliedschaft beim nächsten Login, auch Administratoren. Lokale Gruppen lassen sich mit OAUTH_BLOCKED_GROUPS ausnehmen. Rollen- und Gruppenwechsel gelten erst nach erneuter Anmeldung (Dokumentation). Wie Gruppen Rechte tragen, beschreibt die Seite zu Gruppen.

SCIM und Offboarding

Open WebUI dokumentiert SCIM 2.0 für die Bereitstellung von Nutzern und Gruppen (SCIM-Dokumentation). Aktiviert wird es mit SCIM_ENABLED=true, einem zufälligen SCIM_TOKEN und SCIM_AUTH_PROVIDER (microsoft oder oidc); die Basis-URL lautet https://chat.example.com/api/v1/scim/v2/. Laut Dokumentation setzt active: false die Rolle auf pending und beendet die laufenden WebSocket-Verbindungen, ein pending-Konto wird von API und WebSocket abgewiesen; Administratoren lassen sich über SCIM weder löschen noch herabstufen, und lokal angelegte Konten sind für SCIM unsichtbar. Auf v0.12.0 scheiterte der SSO-Login von SCIM-Nutzern mit 401, ab v0.12.1 ist das behoben. Einen Lizenzvorbehalt für SCIM nennen weder die SCIM-Seite noch die Lizenzseite, und routers/scim.py enthält keine Lizenzprüfung; verbindlich bleibt der Lizenztext. Entra gleicht Anwendungen außerhalb der Galerie etwa alle 40 Minuten ab (Microsoft).

Ohne SCIM bleibt ein gesperrtes Konto in Open WebUI zugriffsfähig, bis das Sitzungstoken abläuft. JWT_EXPIRES_IN steht auf vier Wochen. Ohne Redis widerruft ein Abmelden einzelne Tokens nicht, und auch der Back-Channel-Logout (ENABLE_OAUTH_BACKCHANNEL_LOGOUT) braucht Redis (Fehlersuche SSO). Für das Offboarding bleiben drei Wege: SCIM, Redis mit Back-Channel-Logout oder eine kurze Laufzeit von Stunden bis wenigen Tagen. Administratoren beenden alle Sitzungen eines Kontos über "Sign out all devices".

Notfallzugang und Passwort-Login

Die Dokumentation knüpft ENABLE_PASSWORD_AUTH=false an aktiviertes ENABLE_OAUTH_SIGNUP und funktionierendes SSO und empfiehlt es für reine SSO-Instanzen mit öffentlichem Zugang (Umgebungsvariablen). Ein belastbarer Zwischenstand: Selbstregistrierung aus, Formular ausgeblendet, ein lokaler Administrator mit langem Passwort im Tresor. Open WebUI bietet eine Zwei-Faktor-Anmeldung per Authenticator-App; SSO-Logins lassen sich davon ausnehmen, wenn der Identitätsanbieter bereits einen zweiten Faktor erzwingt. /auth?form=true und /api/v1/auths/signin sollten nur aus dem Admin-Netz erreichbar sein, etwa über VPN oder NetBird. Die vollständige Sperre ENABLE_PASSWORD_AUTH=false ist ein zweiter Schritt, den ein Test bei abgeschaltetem Identitätsanbieter absichert.

Mehrere Replicas und Reverse Proxy

• WEBUI_SECRET_KEY identisch auf allen Replicas, sonst Login-Schleifen, 401-Fehler und "Error decrypting tokens". OAUTH_SESSION_TOKEN_ENCRYPTION_KEY übernimmt standardmäßig denselben Wert.
• Externe PostgreSQL-Datenbank statt SQLite, Redis (REDIS_URL, WEBSOCKET_MANAGER=redis) und eine externe Vektordatenbank (Skalierung).
• Der Proxy cacht /api, /oauth und /ws nicht und reicht WebSocket-Header durch. Cookies mit SameSite=lax; bei langsamen Anbietern hilft OAUTH_TIMEOUT.

Typische Fehlerbilder

Prüfliste nach der Einrichtung

• Login mit Standardnutzer, Administrator und nicht berechtigter Person; die letzte wird abgewiesen.
• Neue Nutzer erhalten die erwartete Rolle, nicht ungewollt pending.
• Gruppen stimmen nach erneuter Anmeldung; Entfernen im Identitätsanbieter wirkt beim nächsten Login.
• Lokaler Notfall-Administrator: Passwort im Tresor, Zwei-Faktor aktiv, Zugriffsweg getestet und auf das Admin-Netz begrenzt.
• ENABLE_SIGNUP=false; Entscheidung zu Login-Formular und ENABLE_PASSWORD_AUTH dokumentiert.
• WEBUI_SECRET_KEY persistent und gesichert, bei Replicas identisch; Image-Version gepinnt.
• Ablaufdatum des Client-Secrets im Kalender, Erneuerung geübt.
• Offboarding-Test: Konto im Identitätsanbieter sperren und messen, wann der Zugriff endet.
• MFA am Identitätsanbieter erzwungen (Conditional Access beziehungsweise Keycloak-Authentifizierungsflow).

SSO und Lizenz bei WZ-IT

Bei der KI-Plattform ist SSO in jedem Paket im Monatspreis enthalten (Anmeldung per Microsoft Entra ID, Google oder Keycloak; Pakete ab 149,90 € netto je Monat, abhängig von der Nutzerzahl). Bei einer Open-WebUI-Instanz in anderer Umgebung bindet WZ-IT je nach Umgebung Keycloak oder Authentik an und plant SSO, Gruppen und Rollen gemeinsam mit dem Kunden; vorhandene Identity Provider können nach Schnittstellenprüfung übernommen werden. Laut Lizenzseite des Herstellers ist die Anbindung von SSO und LDAP ohne Enterprise-Lizenz erlaubt, solange das Open-WebUI-Branding unverändert sichtbar bleibt (Lizenzseite). Die Einordnung steht im Beitrag Open WebUI Lizenz 2026 und ist keine Rechtsberatung. WZ-IT betreibt Open WebUI im Original-Branding.

Stand und Methodik

Geprüft am 28. Oktober 2026 gegen die Open-WebUI-Dokumentation, den Quellcode von open-webui/open-webui v0.12.4 (25. Oktober 2026; utils/oauth.py, routers/auths.py, routers/scim.py), die Microsoft-Learn-Seiten, die Keycloak-Dokumentation samt Mapper-Quellcode sowie die Seiten von Authentik und ZITADEL. Die LICENSE-Datei wurde zuletzt am 14. April 2026 geändert. Die Konfigurationen sind aus Dokumentation und Code abgeleitet, keine Mitschrift eines Testlaufs. Nicht behandelt: Okta, Google, GitHub, LDAP.

Unser Vorgehen bei WZ-IT

Die Reihenfolge einer Anbindung: Rollen und Gruppen im Identitätsanbieter festlegen, bevor die erste Anmeldung läuft, den lokalen Administrator mit Zwei-Faktor-Anmeldung einrichten und den Offboarding-Weg prüfen, also den Zeitpunkt, zu dem der Zugriff nach Sperrung eines Kontos endet. Dazu gehören ein festes WEBUI_SECRET_KEY, ein gepinnter Versionsstand und der Test des Notfallzugangs.

Weiterführende Guides

• Open WebUI als lokale KI-Appliance produktiv betreiben - Betrieb, Backup, Updates und Monitoring
• Open WebUI Lizenz 2026 - Branding-Klausel und Enterprise-Lizenz
• Open WebUI vs. LibreChat - Vergleich der beiden Oberflächen
• Sicherer Fernzugriff auf lokale KI - VPN und NetBird für Admin-Pfade
• RAG-Berechtigungen - was Gruppen bei Wissensquellen leisten
• Keycloak, Authentik, ZITADEL und Open WebUI - Expertise-Seiten

Open WebUI mit SSO produktiv betreiben? Die KI-Plattform enthält SSO im Monatspreis ab 149,90 € netto. Termin vereinbaren