Zum Hauptinhalt springen

Keycloak-Integration

Warnung

Dieses Tutorial ist ein Community-Beitrag und wird vom Open WebUI-Team nicht unterstützt. Es dient lediglich als Demonstration, wie Open WebUI für Ihren spezifischen Anwendungsfall angepasst werden kann. Möchten Sie beitragen? Schauen Sie sich das Tutorial zum Beitragen an.

Diese Anleitung erklärt, wie Sie Open WebUI mit Keycloak für OIDC Single Sign-On (SSO) integrieren.

1. Vorbereitung der Umgebung und Portänderung​

Open WebUI Server Port​

  • Standard-Port: 8080

Keycloak Port-Konfliktproblem​

Keycloak verwendet standardmäßig ebenfalls Port 8080, was zu einem Konflikt führt. Ändern Sie den Keycloak-Port auf 9090.

bin/kc.sh start-dev --http-port=9090

2. Keycloak Realm erstellen​

  1. Öffnen Sie Ihren Browser und rufen Sie https://:9090 auf. Erstellen Sie ein Administratorkonto.
  2. Melden Sie sich in der Admin-Konsole unter https://:9090/admin an.
  3. Klicken Sie im Realm-Dropdown im oberen Bereich auf Realm hinzufügen.
  4. Geben Sie openwebui als Realm-Name ein und klicken Sie auf Erstellen.

create-realm

3. OpenID Connect Client erstellen​

Info

Stellen Sie sicher, dass der Realm openwebui ausgewählt ist. Standardmäßig ist dies master.

select-realm

  1. Stellen Sie sicher, dass der gerade erstellte Realm openwebui ausgewählt ist.
  2. Klicken Sie im linken Menü auf Clients → Client erstellen.
  3. Setzen Sie Client-ID auf open-webui.
  4. Behalten Sie Client-Protokoll als openid-connect bei.
  5. Setzen Sie Zugriffstyp auf confidential und klicken Sie auf Speichern.

access-setting-client

4. Client-Authentifizierung aktivieren und Anmeldedaten abrufen​

Standardmäßig setzt Keycloak 26.x die Client-Authentifizierung auf "Keine", daher muss sie manuell konfiguriert werden.

  1. Gehen Sie zu Clients → open-webui → Einstellungen.
  2. Überprüfen Sie das Dropdown-Menü Client-Authentifikator.
  3. Ändern Sie "Keine" auf Client-ID und Secret und klicken Sie auf Speichern.
  4. Klicken Sie auf die Registerkarte Erweitert.
  5. Klicken Sie im Abschnitt Client-Authentifizierung auf Secret anzeigen und kopieren Sie das Secret.
  6. Fügen Sie dieses Secret in die Variable OAUTH_CLIENT_SECRET in Ihrer .env-Datei ein.

5. Testbenutzer erstellen​

  1. Gehen Sie im linken Menü zu Benutzer → Benutzer hinzufügen.
  2. Füllen Sie Benutzername, E-Mail usw. aus und klicken Sie auf Speichern.
  3. Klicken Sie auf den neu erstellten Benutzer und gehen Sie dann zur Registerkarte Anmeldedaten.
  4. Geben Sie ein neues Passwort ein, deaktivieren Sie Temporär und klicken Sie auf Passwort festlegen.
    • Beispiel: Benutzername testuser, Passwort Test1234!

6. Open WebUI .env konfigurieren​

Fügen Sie die folgenden Variablen zu Ihrer .env-Datei hinzu oder ändern Sie sie.

# Enable OAuth2/OIDC Login
ENABLE_OAUTH_SIGNUP=true

# Keycloak Client Information
OAUTH_CLIENT_ID=open-webui
OAUTH_CLIENT_SECRET=<YOUR_COPIED_SECRET>

# OIDC Discovery Document URL
OPENID_PROVIDER_URL=https://:9090/realms/openwebui/.well-known/openid-configuration

# (Optional) SSO Button Label
OAUTH_PROVIDER_NAME=Keycloak

# (Optional) OAuth Callback URL
OPENID_REDIRECT_URI=https://:8080/oauth/oidc/callback

Starten Sie den Open WebUI-Server nach der Änderung der .env-Datei neu.

7. HTTP vs. HTTPS​

  • HTTP (Entwicklung/Test):
    • Schema: http://
    • Beispiel: https://:9090
  • HTTPS (Produktion empfohlen):
    • Erfordert Keycloak TLS-Einrichtung oder einen Reverse-Proxy mit SSL-Terminierung.
    bin/kc.sh start --https-port=9090 \
      --https-key-store=keystore.jks \
      --https-key-store-password=<password>

8. Integration testen​

  1. Rufen Sie https://:8080 auf. Sie sollten eine Schaltfläche "Mit Keycloak fortfahren" sehen.
  2. Klicken Sie auf die Schaltfläche. Sie sollten zur Keycloak-Anmeldeseite weitergeleitet werden.
  3. Melden Sie sich mit testuser / Test1234! an. Sie sollten erfolgreich zurück zu Open WebUI weitergeleitet werden.

9. Keycloak Gruppen-Mapping konfigurieren​

9.1. Übersicht​

Standardmäßig enthalten Keycloak-Clients keine Gruppeninformationen in Tokens. Befolgen Sie diese Schritte, um Gruppeninformationen zu übermitteln.

9.2. Mapper-Erstellung finden​

  1. Gehen Sie zur Keycloak Admin-Konsole: https://:9090/admin.

  2. Wählen Sie den Realm openwebui aus.

  3. Navigieren Sie zu Clients und wählen Sie den Client open-webui aus.

  4. Gehen Sie zur Registerkarte Client-Scopes.

  5. Wählen Sie den Scope aus, der die Gruppeninformationen enthalten soll (z. B. profile oder open-webui-dedicated).

    scope-client

  6. Gehen Sie in den Details des ausgewählten Scopes zur Registerkarte Mapper.

9.3. Mapper erstellen​

Klicken Sie auf Erstellen oder Builtin hinzufügen, um mit der Erstellung eines neuen Mappers zu beginnen.

9.4. Mapper-Einstellungen​

Konfigurieren Sie den Mapper mit den entsprechenden Einstellungen, um die Gruppenzugehörigkeit einzuschließen.

mappers-setting-group-client

9.5. Speichern und Anwenden​

  • Speichern Sie die Mapper-Konfiguration.
  • Starten Sie den Open WebUI-Server neu, um die Änderungen anzuwenden.

9.6. Open WebUI Umgebungsvariablen konfigurieren​

Fügen Sie diese Variablen zu Ihrer .env-Datei hinzu oder ändern Sie sie

# Enable group synchronization
ENABLE_OAUTH_GROUP_MANAGEMENT=true
# (Optional) Enable Just-In-Time group creation
ENABLE_OAUTH_GROUP_CREATION=true
# The claim key for groups in the token
OAUTH_GROUPS_CLAIM=groups