SSO 与 OAuth

OAuth 和 Single Sign-On（SSO）为 Open WebUI 提供安全认证。当登录出现问题时，通常都能在下面这些常见原因中找到答案。

常见 OAuth/SSO 问题

1. WebUI URL 未配置

大多数 OAuth 流程都需要应用的外部 URL（redirect URI），这样提供商才能在登录后把用户重定向回来。如果缺失，OAuth 无法完成。

解决方法：

前往：Admin Settings > General
确认 WebUI URL 已填写，并且指向你的真实部署地址（例如 https://yourwebui.yourdomain.com）

提示

注意拼写错误——OAuth 非常严格。URL 必须完全匹配，包括 https://。

2. 环境变量配置错误

这是 OAuth 失效的最常见原因。环境变量拼写错误、缺失，或使用了错误名称，都会让认证无法工作。

常见环境变量错误：

❌ 人们经常误用的不存在变量：

OIDC_CONFIG → 应使用 OPENID_PROVIDER_URL
WEBUI_OIDC_CLIENT_ID → 应使用 OAUTH_CLIENT_ID
WEBUI_ENABLE_SSO → 应使用 ENABLE_OAUTH_SIGNUP
WEBUI_AUTH_TYPE → 这个变量不存在——请改用提供商对应的变量
OPENID_CLIENT_ID → 应使用 OAUTH_CLIENT_ID
OPENID_CLIENT_SECRET → 应使用 OAUTH_CLIENT_SECRET

✅ 正确的 OIDC 变量：

# OIDC 必需
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret
OPENID_PROVIDER_URL=https://your-provider/.well-known/openid-configuration
ENABLE_OAUTH_SIGNUP=true

# 可选但推荐
OAUTH_PROVIDER_NAME=Your Provider Name
OAUTH_SCOPES=openid email profile
OPENID_REDIRECT_URI=https://your-domain/oauth/oidc/callback

# 可选：以 JSON 对象传入提供商特定的 authorize 参数
OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com"}

✅ Google 特有的可选 authorize 参数：

GOOGLE_OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com","hd":"example.com"}

✅ 正确的 Microsoft 变量：

MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret
MICROSOFT_CLIENT_TENANT_ID=your_tenant_id
OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration
ENABLE_OAUTH_SIGNUP=true

解决方法：

始终以官方环境变量配置文档为准
逐项检查你的部署环境：
- 确认所有必需环境变量都按文档中的精确名字设置
- 如果你是自托管，请确认这些变量已出现在 Docker Compose、Kubernetes manifest 或 .env 文件中
修改变量后，请重启后端/应用，使新值生效

信息

如果你的提供商在 /authorize 步骤需要额外参数（例如 prompt、login_hint、domain_hint 或 resource），请通过 OAUTH_AUTHORIZE_PARAMS 以 JSON 对象形式传入。

对于 Google 特定定制项，也可以使用 GOOGLE_OAUTH_AUTHORIZE_PARAMS。

提示

大多数 OAuth 错误（循环、401、无响应）都源于环境变量名称错误、完全缺失，或沿用了旧变量名。

注意

Kubernetes/YAML 用户注意： 小心环境变量名尾部的空格。在 YAML 中，如果你把键写成 'OAUTH_CLIENT_ID '（引号内尾部带空格），最终设置出来的变量名就真的是 OAUTH_CLIENT_ID ，Open WebUI 不会识别。请确保环境变量名末尾没有任何空白字符：

# ❌ 错误：引号内尾部多了空格
- name: 'OAUTH_CLIENT_ID '
  value: your_client_id

# ✅ 正确：没有尾部空格
- name: OAUTH_CLIENT_ID
  value: your_client_id

3. 缺少必需变量

OPENID_PROVIDER_URL 对 OIDC 是必需的

很多用户会忘记这个关键变量。缺少它时，OIDC 无法工作。

✅ Microsoft Entra ID：

OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration

✅ Google：

OPENID_PROVIDER_URL=https://accounts.google.com/.well-known/openid-configuration

✅ Authentik：

OPENID_PROVIDER_URL=https://your-authentik-domain/application/o/your-app-name/.well-known/openid-configuration

按提供商分类的其他必需变量：

所有 OAuth 提供商： WEBUI_URL、ENABLE_OAUTH_SIGNUP=true
Microsoft： MICROSOFT_CLIENT_ID、MICROSOFT_CLIENT_SECRET、MICROSOFT_CLIENT_TENANT_ID
Google： GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET
OIDC： OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET、OPENID_PROVIDER_URL

4. 持久化配置冲突

重要： Open WebUI 中有两个与 OAuth 相关的持久化设置：

ENABLE_PERSISTENT_CONFIG（默认 true）——控制所有设置（包括 OAuth）在写入数据库后，是否优先从数据库加载，而不是从环境变量读取。
ENABLE_OAUTH_PERSISTENT_CONFIG（默认 false）——这是针对 OAuth 设置的额外开关。当它为 false 时，即使 ENABLE_PERSISTENT_CONFIG 为 true，所有以 oauth. 开头的配置路径也不会从数据库加载。

默认情况下，因为 ENABLE_OAUTH_PERSISTENT_CONFIG=false，OAuth 环境变量会优先于数据库值。但如果你之前通过 Admin Panel 配过 OAuth，而后面又把 ENABLE_OAUTH_PERSISTENT_CONFIG 设为 true，那么数据库里的旧值就会重新接管。

症状：

修改环境变量后，重启仍然不生效
之前能登录，改了配置后突然失效
重新配置后出现 “No token found in localStorage”

解决方法：

开发/测试环境： 保持 ENABLE_OAUTH_PERSISTENT_CONFIG=false（默认就是如此），确保始终从环境变量读取
生产环境： 二选一：
- 通过 Admin Panel 配置 OAuth，而不是依赖环境变量；或
- 保持 ENABLE_OAUTH_PERSISTENT_CONFIG=false（默认），让 OAuth 仍以环境变量为准
彻底重来： 删除数据库 volume，用正确配置重新启动

📌 Docker Compose 示例：

environment:
  - ENABLE_OAUTH_PERSISTENT_CONFIG=false
  - OAUTH_CLIENT_ID=your_client_id
  - OAUTH_CLIENT_SECRET=your_secret
  - OPENID_PROVIDER_URL=your_provider_url

5. 提供商侧 OAuth 配置错误

有时问题不在 Open WebUI，而在身份提供商（如 Google、Okta、Auth0、Azure AD）的应用注册与 Open WebUI 配置不一致。

解决方法：

确认你的应用已在 OAuth 提供商端正确注册，并检查：
- Redirect URI 与真实部署地址完全一致
  - OIDC: https://your-domain/oauth/oidc/callback
  - Microsoft: https://your-domain/oauth/microsoft/callback
  - Google: https://your-domain/oauth/google/callback
- Client ID / secret 与环境中填写的值一致
- Scopes 与允许的 grant types（例如 authorization_code）符合 Open WebUI 需求
查看提供商日志——很多应用注册错误会在那里给出明确原因

📌 Redirect URI 格式示例：

✅ Correct: https://ai.company.com/oauth/oidc/callback
❌ Wrong: https://ai.company.com/oauth/callback/oidc
❌ Wrong: https://ai.company.com/callback

提示

如果不确定，就重新检查提供商应用注册，并在需要时重新生成 client secret。

6. 服务端缓存问题

如果你在使用 Nginx（或其他反向代理）时启用了服务端缓存，OAuth endpoint 可能会出现随机、间歇性的登录问题，而且通常很难排查。

解决方法：

在 NGINX（或其他代理）配置中：
- 确认不要缓存以下 endpoint：
  - /api、/oauth、/callback、/login、/ws、/websocket
- 任何关键登录/认证 endpoint 都必须保持未缓存状态
修改后重新加载代理配置

NGINX 示例：

# 为登录 / OAuth / websocket endpoint 关闭缓存
location ~* ^/(api|oauth|callback|login|ws|websocket) {
    proxy_no_cache 1;
    proxy_cache_bypass 1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    proxy_set_header Accept-Encoding "";
}

注意

永远不要缓存 OAuth 或登录 endpoint。缓存会导致旧 token 被重复返回，或破坏会话，最终引发难以预测的认证错误。

常见问题： 反向代理里的 cookie 设置，尤其是 HttpOnly 与 SameSite，可能会干扰 OAuth 认证流程。

症状：

“No token found in localStorage”
登录成功后却不断重定向循环
认证似乎成功了，但立刻又跳回登录页

解决方法：

对于 NGINX Proxy Manager：

# 删除或调整有问题的 cookie 设置

# ❌ 问题配置：
# proxy_cookie_path / "/; Secure; HttpOnly; SameSite=None";

# ✅ 更合理的配置：
proxy_cookie_flags ~ secure samesite=lax;
# 或者彻底移除 cookie 篡改逻辑

WEBUI_SESSION_COOKIE_SAME_SITE=lax
WEBUI_AUTH_COOKIE_SAME_SITE=lax
WEBUI_SESSION_COOKIE_SECURE=true  # 如果你使用 HTTP，请改为 false
WEBUI_AUTH_COOKIE_SECURE=true     # 如果你使用 HTTP，请改为 false

8. 网络超时问题

OAuth 提供商有时响应较慢，导致认证握手阶段超时。

症状：

日志中出现 httpcore.ReadTimeout
出现 CSRF Warning! State not equal in request and response
OAuth 登录偶发性失败

解决方法：

AIOHTTP_CLIENT_TIMEOUT=600
AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST=30

9. Session State 不匹配（CSRF 错误）

OAuth 重定向过程中，如果 session cookie 没有被正确保留，就会出现这类错误。

症状：

CSRF Warning! State not equal in request and response
日志中出现 mismatching_state
认证看似成功，但最后又跳回登录页

解决方法：

检查 Cookie 域名配置：

WEBUI_URL=https://your-exact-domain.com  # 必须完全匹配；也请检查 admin panel 中是否保存了不同值

检查 Session 配置：

WEBUI_SECRET_KEY=your_very_secure_random_key_here
OAUTH_SESSION_TOKEN_ENCRYPTION_KEY=another_secure_key_here

10. 负载均衡器与多实例问题

在多实例部署中，如果 OAuth 会话没有正确同步，就会失败。

集群部署所需配置：

REDIS_URL=redis://your-redis:6379/0
WEBSOCKET_REDIS_URL=redis://your-redis:6379/0
WEBUI_SECRET_KEY=same_on_all_instances
OAUTH_SESSION_TOKEN_ENCRYPTION_KEY=same_on_all_instances
ENABLE_WEBSOCKET_SUPPORT=true
WEBSOCKET_MANAGER=redis

11. 提供商特定配置问题

Microsoft Entra ID 常见问题：

问题： 错把通用 OIDC 变量当成 Microsoft 专属配置使用。

✅ 正确的 Microsoft 配置：

MICROSOFT_CLIENT_ID=your_azure_app_id
MICROSOFT_CLIENT_SECRET=your_azure_app_secret
MICROSOFT_CLIENT_TENANT_ID=your_tenant_id
MICROSOFT_OAUTH_SCOPE=openid email profile
MICROSOFT_REDIRECT_URI=https://your-domain/oauth/microsoft/callback
OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration
ENABLE_OAUTH_SIGNUP=true

Authentik 常见问题：

问题： provider URL 格式错误。

✅ 正确的 Authentik 配置：

OAUTH_CLIENT_ID=your_authentik_client_id
OAUTH_CLIENT_SECRET=your_authentik_client_secret
OPENID_PROVIDER_URL=https://your-authentik-domain/application/o/your-app-slug/.well-known/openid-configuration
OAUTH_PROVIDER_NAME=Authentik
OAUTH_SCOPES=openid email profile

高级排查建议

检查 token 存储方式

较新的 Open WebUI 已从基于 URL 的 token 方案迁移到基于 cookie 的方案。如果你遇到认证问题：

彻底清空浏览器 cookies 和缓存
打开浏览器开发者工具检查：
- 是否存在 oauth_session_id cookie（新方式）
- 是否还残留 oauth_id_token cookie（旧方式）
- cookie 的 domain 与 path 是否正确

调试 OAuth 流程

开启 debug 日志，并按流程逐步跟踪：

GLOBAL_LOG_LEVEL=DEBUG

# 重点观察：
# 1. GET /oauth/{provider}/login - 应返回 302 redirect
# 2. 用户在 provider 端完成认证
# 3. GET /oauth/{provider}/callback?code=... - 应返回 200 或继续 redirect
# 4. 用户最终进入已登录状态

数据库调试

检查用户账号是否真的被创建：

# 进入容器
docker exec -it your-openwebui-container sh

# 检查用户数据（按你的数据目录路径调整）
ls -la /app/backend/data/

不经过反向代理直接测试

如果你使用了反向代理，请临时绕过它直接测试 OAuth：

临时直接暴露 Open WebUI 端口
把 OAuth 提供商中的 redirect URI 改成这个直连地址
测试认证流程
如果此时可用，问题就出在你的代理配置上

小提示：先看日志

先看后端日志和浏览器网络错误。第一条错误通常就最接近根因。
如果你不确定到底是哪一侧有问题，可以用浏览器隐私窗口重新登录，并观察哪些请求被拦截或失败。

需要重点关注的日志信息：

OAuth callback error: mismatching_state → Session/cookie 问题
httpcore.ReadTimeout → 网络超时问题
The email or password provided is incorrect → 往往说明 OAuth 已完成，但 session 没有建立成功
回调 URL 返回 404 → Redirect URI 配置错误

总结清单 ✅

问题	修复方式
🔗 WebUI URL 缺失或错误	在 admin panel 中设置正确的 WebUI URL
📝 环境变量拼写错误或缺失	对照官方文档逐项检查；不要使用 `OIDC_CONFIG` 这类不存在的变量
🚨 缺少 OPENID_PROVIDER_URL	OIDC 必需项，指向提供商的 `.well-known/openid-configuration`
🔄 持久化配置冲突	设 `ENABLE_OAUTH_PERSISTENT_CONFIG=false`，或统一改用 admin panel 配置
🏢 提供商侧配置错误	核对应用注册、URI、client ID 与 secret
🧊 代理缓存干扰	把所有 OAuth endpoint 排除在服务端缓存之外
🍪 Cookie 配置问题	检查反向代理 cookie 设置与相关 env vars
⏱️ 超时问题	提高 `AIOHTTP_CLIENT_TIMEOUT` 等超时设置
🔐 CSRF / session 问题	检查 `WEBUI_SECRET_KEY` 与会话配置
🔀 多实例问题	配置 Redis 与共享密钥
仍未解决？	开启 debug 日志、绕过代理测试、复查 provider 配置

只要同时把 OAuth 提供商和 Open WebUI 环境配置正确，并确保关键登录 endpoint 不被缓存，绝大多数 SSO/OAuth 登录问题都能被消除。

Token 撤销依赖 Redis

如果没有 Redis，退出登录并不会撤销 JWT token——它们会一直有效直到过期（默认：4 周）。对 SSO/OAuth 部署来说，这一点尤其重要，因为你可能需要在用户离职等场景下快速撤销访问权限。没有 Redis 时，密码修改和管理员停用账号也无法让已签发 token 立即失效。

对于生产环境中的 SSO 部署，请配置 Redis，或缩短 JWT_EXPIRES_IN 来降低暴露窗口。更多信息请参阅 Token 撤销和 Redis 教程。

本内容仅供参考，不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议以了解适用条款。

常见 OAuth/SSO 问题​

1. WebUI URL 未配置​

2. 环境变量配置错误​

❌ 人们经常误用的不存在变量：​

✅ 正确的 OIDC 变量：​

✅ Google 特有的可选 authorize 参数：​

✅ 正确的 Microsoft 变量：​

3. 缺少必需变量​

OPENID_PROVIDER_URL 对 OIDC 是必需的​

按提供商分类的其他必需变量：​

4. 持久化配置冲突​

症状：​

5. 提供商侧 OAuth 配置错误​

6. 服务端缓存问题​

7. Cookie 配置问题​

症状：​

对于 NGINX Proxy Manager：​

环境变量中的 cookie 设置：​

8. 网络超时问题​

症状：​

9. Session State 不匹配（CSRF 错误）​

症状：​

10. 负载均衡器与多实例问题​

集群部署所需配置：​

11. 提供商特定配置问题​

Microsoft Entra ID 常见问题：​

Authentik 常见问题：​

高级排查建议​

检查 token 存储方式​

调试 OAuth 流程​

数据库调试​

不经过反向代理直接测试​

小提示：先看日志​

需要重点关注的日志信息：​

总结清单 ✅​

常见 OAuth/SSO 问题

1. WebUI URL 未配置

2. 环境变量配置错误

❌ 人们经常误用的不存在变量：

✅ 正确的 OIDC 变量：

✅ Google 特有的可选 authorize 参数：

✅ 正确的 Microsoft 变量：

3. 缺少必需变量

OPENID_PROVIDER_URL 对 OIDC 是必需的

按提供商分类的其他必需变量：

4. 持久化配置冲突

症状：

5. 提供商侧 OAuth 配置错误

6. 服务端缓存问题

7. Cookie 配置问题

症状：

对于 NGINX Proxy Manager：

环境变量中的 cookie 设置：

8. 网络超时问题

症状：

9. Session State 不匹配（CSRF 错误）

症状：

10. 负载均衡器与多实例问题

集群部署所需配置：

11. 提供商特定配置问题

Microsoft Entra ID 常见问题：

Authentik 常见问题：

高级排查建议

检查 token 存储方式

调试 OAuth 流程

数据库调试

不经过反向代理直接测试

小提示：先看日志

需要重点关注的日志信息：

总结清单 ✅