如何配置Open-WebUI与Keycloak的单点登录（SSO）

一、Keycloak身份提供商配置 #

1. 创建专属Realm #

登录Keycloak管理员控制台，点击左上角Realm下拉菜单，选择「Create Realm」，输入Realm名称（比如open-web-ui-realm），确认保存。

2. 配置Open-WebUI客户端 #

进入刚创建的Realm，左侧导航栏选「Clients」→「Create client」：

• Client type 选择「OpenID Connect」
• Client ID 填写open-web-ui-client（可自定义，后续要和Open-WebUI配置一致）
• 输入客户端名称后保存

3. 调整客户端核心设置 #

进入客户端详情页面：

• Access type 设为「confidential」（需要令牌交换必须选这个）
• Valid redirect URIs 填入Open-WebUI的回调地址，比如http://localhost:3000/auth/callback/keycloak（根据你的实际部署地址修改）
• Web origins 填*或者Open-WebUI的具体域名，保存设置

4. 准备测试用户（可选） #

左侧导航栏「Users」→「Add user」，填写用户名、邮箱，切换到「Credentials」标签设置登录密码，确保用户状态为启用。

5. 记录Keycloak端点信息 #

进入Realm Settings → Endpoints → OpenID Endpoint Configuration，复制以下几个关键URL备用：

• Authorization endpoint
• Token endpoint
• JWKS URI

二、Open-WebUI与Keycloak集成配置 #

1. 修改Open-WebUI配置文件 #

根据部署方式调整配置：

• Docker部署：在docker-compose.yml的environment块中添加环境变量
• 本地部署：找到项目根目录的.env文件，添加配置项

2. 添加OIDC相关配置 #

# 启用OIDC认证
AUTH_OIDC_ENABLED=true
# 登录入口显示的名称
AUTH_OIDC_PROVIDER_NAME=Keycloak
# 和Keycloak客户端的Client ID一致
AUTH_OIDC_CLIENT_ID=open-web-ui-client
# Keycloak客户端的密钥（在Clients → 你的客户端 → Credentials标签获取）
AUTH_OIDC_CLIENT_SECRET=your-keycloak-client-secret
# Keycloak的OpenID配置地址，格式为http://<keycloak地址>/realms/<你的realm>/.well-known/openid-configuration
AUTH_OIDC_DISCOVERY_URL=http://localhost:8080/realms/open-web-ui-realm/.well-known/openid-configuration
# 请求的权限范围
AUTH_OIDC_SCOPE=openid profile email
# 和Keycloak中设置的Valid redirect URIs完全一致
AUTH_OIDC_REDIRECT_URI=http://localhost:3000/auth/callback/keycloak

3. 重启服务生效 #

重启Open-WebUI服务，让配置生效。打开Open-WebUI页面，应该能看到Keycloak的登录选项。

三、认证与令牌交换处理 #

1. 核心流程说明 #

• 用户点击Open-WebUI的Keycloak登录按钮，跳转至Keycloak授权页面
• 用户输入Keycloak账号密码，验证通过后Keycloak返回授权码到Open-WebUI的回调地址
• Open-WebUI携带授权码、客户端ID/密钥，向Keycloak令牌端点请求访问令牌和ID令牌
• Open-WebUI通过JWKS URI获取公钥，验证令牌签名，确认身份后创建用户会话

2. 用户信息与角色映射 #

• Open-WebUI会自动解析ID令牌中的用户信息（如sub、name、email），同步到系统用户
• 如需自定义属性映射，可在Keycloak客户端的「Mappers」标签添加映射规则，比如将Keycloak用户角色同步到Open-WebUI

3. 常见问题排查 #

• 授权码无效：检查Keycloak客户端的Valid redirect URIs是否和Open-WebUI的回调地址完全匹配（包括HTTP/HTTPS、端口）
• 令牌验证失败：确认AUTH_OIDC_DISCOVERY_URL正确，Keycloak的JWKS URI可正常访问
• 客户端密钥错误：核对Keycloak客户端Credentials标签下的Client secret，不要复制其他字段
• 用户无权限登录：检查Keycloak用户是否属于目标Realm，且客户端未设置额外权限限制

内容的提问来源于stack exchange，提问作者Ousmane Sow