跳到主要内容

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 Realm​

  1. 打开浏览器并访问 http://localhost:9090。创建一个管理员账户。
  2. 登录管理控制台：http://localhost:9090/admin。
  3. 从顶部的 Realm 下拉列表中，点击 Add realm。
  4. 输入 openwebui 作为 Realm name，然后点击 Create。

创建 Realm

3. 创建 OpenID Connect 客户端​

信息

确保您已经选择了 openwebui 域。默认域为 master。

选择 Realm

  1. 确保已选中您刚刚创建的 openwebui 域。
  2. 在左侧菜单中，点击 Clients → Create client。
  3. 将 Client ID 设置为 open-webui。
  4. 保持 Client protocol 为 openid-connect。
  5. 将 Access Type 设置为 confidential，然后点击 Save。

客户端访问设置

4. 启用客户端身份验证并获取凭证​

Keycloak 26.x 默认将客户端身份验证 (Client Authentication) 设置为 "None"，因此需要手动进行配置。

  1. 前往 Clients → open-webui → Settings。
  2. 检查 Client Authenticator 下拉列表。
  3. 将 "None" 更改为 Client ID and secret 并点击 Save。
  4. 点击 Advanced 标签页。
  5. 在 Client authentication 部分，点击 Reveal secret 并复制 Secret。
  6. 将此 Secret 粘贴到您的 .env 配置文件中的 OAUTH_CLIENT_SECRET 变量里。

5. 创建测试用户​

  1. 在左侧菜单中，前往 Users → Add user。
  2. 填写 Username、Email 等信息，然后点击 Save。
  3. 点击新创建的用户，然后前往 Credentials 标签页。
  4. 输入新密码，取消勾选 Temporary（临时密码），然后点击 Set Password。
    • 示例：用户名 testuser，密码 Test1234!

6. 配置 Open WebUI .env 配置文件​

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

# 启用 OAuth2/OIDC 登录
ENABLE_OAUTH_SIGNUP=true

# Keycloak 客户端信息
OAUTH_CLIENT_ID=open-webui
OAUTH_CLIENT_SECRET=<您复制的 Secret>

# OIDC 发现文档 URL
OPENID_PROVIDER_URL=http://localhost:9090/realms/openwebui/.well-known/openid-configuration

# (可选) SSO 按钮的文本标签
OAUTH_PROVIDER_NAME=Keycloak

# (可选) OAuth 回调 URL
OPENID_REDIRECT_URI=http://localhost:8080/oauth/oidc/callback

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

7. HTTP 与 HTTPS 对比​

  • HTTP (开发/测试环境):
    • 协议：http://
    • 示例：http://localhost:9090
  • HTTPS (推荐生产环境使用):
    • 需要 Keycloak 配置 TLS，或者使用支持 SSL 卸载的反向代理。
    bin/kc.sh start --https-port=9090 \
  --https-key-store=keystore.jks \
  --https-key-store-password=<密码>

8. 测试集成​

  1. 访问 http://localhost:8080。您应该会看到 "Continue with Keycloak"（继续使用 Keycloak 登录）的按钮。
  2. 点击该按钮。您应该会被重定向到 Keycloak 的登录页面。
  3. 使用 testuser / Test1234! 进行登录。您应该会成功地被重定向回 Open WebUI。

9. 配置 Keycloak 用户组映射​

9.1. 概述​

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

9.2. 查找 Mapper 创建位置​

  1. 前往 Keycloak 管理控制台：http://localhost:9090/admin。

  2. 选择 openwebui 域。

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

  4. 前往 Client scopes 标签页。

  5. 选择将包含用户组信息的 Scope（例如 profile 或 open-webui-dedicated）。

    客户端 Scope 范围

  6. 在所选 Scope 的详情中，前往 Mappers 标签页。

9.3. 创建 Mapper​

点击 Create 或 Add builtin 开始创建新的 Mapper。

9.4. Mapper 设置​

配置 Mapper 以包含用户组成员身份的适当设置。

用户组 Mapper 设置

9.5. 保存与应用​

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

9.6. 配置 Open WebUI 环境变量​

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

# 启用用户组同步
ENABLE_OAUTH_GROUP_MANAGEMENT=true

# (可选) 启用即时 (Just-In-Time) 用户组自动创建
ENABLE_OAUTH_GROUP_CREATION=true

# Token 中代表用户组的 Claim 键名
OAUTH_GROUP_CLAIM=groups
This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.