Skip to main content

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

create-realm

3. 创建 OpenID Connect 客户端

提示

确保您已选择 openwebui realm。默认值为 master

select-realm

  1. 确保已选择您刚刚创建的 openwebui realm。
  2. 在左侧菜单中,点击 ClientsCreate client
  3. Client ID 设置为 open-webui
  4. 保持 Client protocolopenid-connect
  5. Access Type 设置为 confidential 并点击 Save

access-setting-client

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

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

  1. 转到 Clientsopen-webuiSettings
  2. 检查 Client Authenticator 下拉菜单。
  3. 将 "None" 更改为 Client ID and secret 并点击 Save
  4. 点击 Advanced 选项卡。
  5. Client authentication 部分,点击 Reveal secret 并复制密钥 (secret)。
  6. 将此密钥粘贴到 .env 文件中的 OAUTH_CLIENT_SECRET 变量中。

5. 创建测试用户

  1. 在左侧菜单中,转到 UsersAdd user
  2. 填写 UsernameEmail 等,然后点击 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=<您复制的密钥>

# 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 vs. 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=<password>

8. 测试集成

  1. 访问 http://localhost:8080。您应该看到一个 "Continue with Keycloak" 按钮。
  2. 点击该按钮。您应该被重定向到 Keycloak 登录页面。
  3. 使用 testuser / Test1234! 登录。您应该成功重定向回 Open WebUI。

9. 配置 Keycloak 组映射 (Group Mapping)

9.1. 概述

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

9.2. 查找映射器 (Mapper) 创建

  1. 转到 Keycloak 管理控制台:http://localhost:9090/admin

  2. 选择 openwebui realm。

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

  4. 转到 Client scopes 选项卡。

  5. 选择将包含组信息的范围 (scope)(例如 profileopen-webui-dedicated)。

    scope-client

  6. 在所选范围的详细信息中,转到 Mappers 选项卡。

9.3. 创建映射器

点击 CreateAdd builtin 开始创建新的映射器。

9.4. 映射器设置

配置映射器以包含组成员身份。

mappers-setting-group-client

9.5. 保存并应用

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

9.6. 配置 Open WebUI 环境变量

.env 文件中添加或修改这些变量:


# 启用组同步
ENABLE_OAUTH_GROUP_MANAGEMENT=true

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

# 令牌中组的 claim 键
OAUTH_GROUP_CLAIM=groups