跳到主要内容

Keycloak 集成

警告

本教程由社区贡献，不获得 Open WebUI 团队的支持。它仅作为演示，说明如何根据您的特定用例定制 Open WebUI。想要贡献？请查看贡献教程。

本指南介绍了如何将 Open WebUI 与 Keycloak 集成以实现 OIDC 单点登录 (SSO)。

1. 环境准备与端口更改​

Open WebUI 服务器端口​

  • 默认端口: 8080

Keycloak 端口冲突问题​

Keycloak 默认也使用端口 8080，这会导致冲突。请将 Keycloak 端口更改为 9090。

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

2. 创建 Keycloak 领域​

  1. 打开浏览器并访问 https://:9090。创建一个管理员账户。
  2. 登录到管理员控制台 https://:9090/admin。
  3. 在顶部的领域下拉菜单中，点击添加领域。
  4. 输入 openwebui 作为领域名称，然后点击创建。

create-realm

3. 创建 OpenID Connect 客户端​

信息

请确保已选择 openwebui 领域。默认是 master。

select-realm

  1. 确保您刚刚创建的 openwebui 领域已被选中。
  2. 在左侧菜单中，点击客户端 → 创建客户端。
  3. 将客户端 ID 设置为 open-webui。
  4. 将客户端协议保持为 openid-connect。
  5. 将访问类型设置为 confidential，然后点击保存。

access-setting-client

4. 启用客户端认证并获取凭据​

默认情况下，Keycloak 26.x 将客户端认证设置为“无”，因此需要手动配置。

  1. 转到客户端 → open-webui → 设置。
  2. 检查客户端认证器下拉菜单。
  3. 将“无”更改为客户端 ID 和密钥，然后点击保存。
  4. 点击高级选项卡。
  5. 在客户端认证部分，点击显示密钥并复制密钥。
  6. 将此密钥粘贴到 .env 文件中的 OAUTH_CLIENT_SECRET 变量。

5. 创建测试用户​

  1. 在左侧菜单中，转到用户 → 添加用户。
  2. 填写用户名、电子邮件等信息，然后点击保存。
  3. 点击新创建的用户，然后转到凭据选项卡。
  4. 输入新密码，取消勾选临时，然后点击设置密码。
    • 示例：用户名 testuser，密码 Test1234!

6. 配置 Open WebUI .env 文件​

在您的 .env 文件中添加或修改以下变量。

# 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

修改 .env 文件后，请重启 Open WebUI 服务器。

7. HTTP 与 HTTPS​

  • HTTP（开发/测试）:
    • 方案：http://
    • 示例：https://:9090
  • HTTPS（生产环境推荐）:
    • 需要配置 Keycloak TLS 或带有 SSL 终止的反向代理。
    bin/kc.sh start --https-port=9090 \
      --https-key-store=keystore.jks \
      --https-key-store-password=<password>

8. 测试集成​

  1. 访问 https://:8080。您应该会看到一个“使用 Keycloak 继续”按钮。
  2. 点击该按钮。您应该会被重定向到 Keycloak 登录页面。
  3. 使用 testuser / Test1234! 登录。您应该会成功重定向回 Open WebUI。

9. 配置 Keycloak 组映射​

9.1. 概述​

默认情况下，Keycloak 客户端不会在令牌中包含组信息。请按照以下步骤传递组信息。

9.2. 定位映射器创建​

  1. 转到 Keycloak 管理控制台：https://:9090/admin。

  2. 选择 openwebui 领域。

  3. 导航到客户端并选择 open-webui 客户端。

  4. 转到客户端范围选项卡。

  5. 选择将包含组信息的范围（例如，profile 或 open-webui-dedicated）。

    scope-client

  6. 在所选范围的详细信息中，转到映射器选项卡。

9.3. 创建映射器​

点击创建或添加内置以开始创建新的映射器。

9.4. 映射器设置​

使用适当的设置配置映射器以包含组成员资格。

mappers-setting-group-client

9.5. 保存并应用​

  • 保存映射器配置。
  • 重启 Open WebUI 服务器以应用更改。

9.6. 配置 Open WebUI 环境变量​

在您的 .env 文件中添加或修改这些变量

# 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