跳到主要内容

Keycloak

注意

本教程是社区贡献内容，不属于 OPL 数据空间官方支持范围。它主要用于演示如何按你的环境接入 Keycloak。

本指南介绍如何把 OPL 数据空间接入 Keycloak，实现基于 OIDC 的单点登录。

1. 环境准备与端口调整​

OPL 数据空间默认端口​

  • 默认端口：8080

Keycloak 端口冲突​

Keycloak 默认也使用 8080，因此本地测试时通常要把它改到 9090：

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

2. 创建 Keycloak Realm​

  1. 在浏览器中打开 http://localhost:9090
  2. 创建管理员账号
  3. 登录管理控制台 http://localhost:9090/admin
  4. 点击顶部 realm 下拉 → Add realm
  5. 将 Realm name 设为 openwebui，然后点击 Create

create-realm

3. 创建 OpenID Connect Client​

信息

请确认你当前选中的是 openwebui realm，而不是默认的 master。

select-realm

  1. 确保当前 realm 为 openwebui
  2. 在左侧菜单中进入 Clients → Create client
  3. Client ID 填 open-webui
  4. Client protocol 保持 openid-connect
  5. Access Type 选择 confidential
  6. 点击 Save

access-setting-client

4. 启用客户端认证并获取密钥​

Keycloak 26.x 默认把 Client Authentication 设为 “None”，需要手动改：

  1. 进入 Clients → open-webui → 设置
  2. 找到 Client Authenticator
  3. 从 None 改成 Client ID and secret
  4. 点击 Save
  5. 打开 Advanced 标签页
  6. 在 Client authentication 区块中点击 Reveal secret
  7. 复制这个 secret，填入 OPL 数据空间的 OAUTH_CLIENT_SECRET

5. 创建测试用户​

  1. 左侧菜单进入 Users → Add user
  2. 填写 Username、Email 等信息并保存
  3. 打开该用户的 Credentials 标签
  4. 设置密码，取消 Temporary

例如：

  • Username：testuser
  • Password：Test1234!

6. 配置 OPL 数据空间的 .env​

在 .env 中加入或修改以下变量：

ENABLE_OAUTH_SIGNUP=true

OAUTH_CLIENT_ID=open-webui
OAUTH_CLIENT_SECRET=<YOUR_COPIED_SECRET>

OPENID_PROVIDER_URL=http://localhost:9090/realms/openwebui/.well-known/openid-configuration

OAUTH_PROVIDER_NAME=Keycloak
OPENID_REDIRECT_URI=http://localhost:8080/oauth/oidc/callback

修改后需要重启 OPL 数据空间。

7. HTTP 与 HTTPS​

  • 开发 / 测试环境：可直接用 http://
  • 生产环境：建议用 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
  2. 页面上应该会出现 “Continue with Keycloak” 按钮
  3. 点击后会跳转到 Keycloak 登录页
  4. 使用 testuser / Test1234! 登录
  5. 成功后会被重定向回 OPL 数据空间

9. 配置 Keycloak 的组映射​

9.1 概览​

默认情况下，Keycloak 不会自动把用户组信息放进 token。若你希望 OPL 数据空间同步组信息，需要手动添加 mapper。

9.2 定位 mapper 配置入口​

  1. 打开 http://localhost:9090/admin
  2. 选择 openwebui realm
  3. 进入 Clients
  4. 选择 open-webui client
  5. 打开 Client scopes
  6. 选择要承载 group 信息的 scope，例如 profile 或专用 scope
  7. 进入该 scope 的 Mappers 标签页

scope-client

9.3 创建 mapper​

点击 Create 或 Add builtin，新增 group mapper。

9.4 设置 mapper​

按需要配置 mapper，使 token 中包含 group membership。

mappers-setting-group-client

9.5 保存并生效​

  • 保存 mapper 配置
  • 重启 OPL 数据空间

9.6 配置 OPL 数据空间环境变量​

在 .env 中加入：

ENABLE_OAUTH_GROUP_MANAGEMENT=true
ENABLE_OAUTH_GROUP_CREATION=true
OAUTH_GROUP_CLAIM=groups

这样 OPL 数据空间就会从 token 的 groups claim 中读取组信息，并按需自动创建组。