SSO 与 OAuth

OAuth 和单点登录（Single Sign-On, SSO）为 Open WebUI 提供了安全的身份验证。当遇到登录故障时，通常是由以下常见问题之一引起的。

常见的 OAuth/SSO 问题

1. WebUI URL 未配置

大多数 OAuth 流程都要求配置应用程序的外部 URL（即“重定向 URI / redirect URI”），以便授权服务商在用户登录成功后知道将用户引流回何处。如果此项配置缺失，OAuth 流程将无法正常走完。

解决方案：

导航至：Admin Settings（管理员设置） > General（常规）
确保您的 WebUI URL 字段已被正确填写，并精准指向您已部署的实例地址（例如 https://yourwebui.yourdomain.com）

提示

请仔细检查是否存在拼写错误——OAuth 的校验极其严苛。URL 地址必须 100% 精准匹配，包括 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 参数：

# 可选：作为 JSON 传入的额外 Google /authorize 参数
GOOGLE_OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com","hd":"example.com"}

✅ 正确的 Microsoft 变量：

# 使用这些变量来对接 Microsoft Entra ID
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 清单或 .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 时，任何配置路径以 oauth. 开头的 OAuth 设置都不会从数据库中加载，即便此时 ENABLE_PERSISTENT_CONFIG 处于 true 状态。

在默认情况下，因为 ENABLE_OAUTH_PERSISTENT_CONFIG 默认为 false，所以您的 OAuth 环境变量始终会优先于数据库配置生效。但如果您在此前曾通过管理员面板手动配置过 OAuth，这些配置可能会被写入数据库，并在后续如果您手动把 ENABLE_OAUTH_PERSISTENT_CONFIG 调为 true 时被重新载入。

具体表现与症状：

更改了环境变量并重启后，新变量完全没有生效。
身份验证在最开始是可以用的，但在修改了某些配置后突然失效。
重新配置后，前端或日志抛出 "No token found in localStorage"（未在 localStorage 中找到 Token）报错。

解决方案：

针对开发/测试环境：请确保设置 ENABLE_OAUTH_PERSISTENT_CONFIG=false（此为默认状态），以强制每次都读取最新的环境变量。
针对生产环境：选择以下操作之一：
- 彻底废弃环境变量，完全在 Admin Panel（管理员面板）中手动录入和管理 OAuth 配置，或者
- 将 ENABLE_OAUTH_PERSISTENT_CONFIG 保持在默认的 false 状态，以强制使环境变量配置始终拥有最高优先级。
全新开始：如果您想彻底清理，可以删除对应的数据库挂载卷并带着正确的参数重新拉起服务。

📌 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 等）端的注册配置与您的 WebUI 实例不匹配。

解决方案：

仔细核对您在 OAuth 授权服务商控制台上注册的应用程序信息。确认以下项：
- Redirect URIs（重定向回调地址）必须与您实际部署的 WebUI 域名 100% 精确一致：
  - OIDC：https://your-domain/oauth/oidc/callback
  - Microsoft：https://your-domain/oauth/microsoft/callback
  - Google：https://your-domain/oauth/google/callback
- 客户端 ID（Client ID）和密钥（Client Secret）必须与您的环境变量保持一致。
- Scopes（作用域）和允许的授权类型（例如 authorization_code 授权码模式）已根据 Open WebUI 的规范被开启。
查看提供商控制台输出的日志——配置有误的客户端请求通常会在授权商端产生非常直观的错误提示信息。

📌 重定向 URI 格式对比参考：

✅ 正确格式: https://ai.company.com/oauth/oidc/callback
❌ 错误格式: https://ai.company.com/oauth/callback/oidc
❌ 错误格式: https://ai.company.com/callback

提示

如果不确定配置是否有效，请重新检查提供商端的注册表单，或者必要时重新生成一组 Client Secret 密钥。

6. 服务端缓存问题

如果您在前端配置了 Nginx（或其他反向代理）并且开启了服务端缓存，可能会干扰 OAuth 回调的正常工作。这经常表现为登录行为莫名其妙失败，并且极难复现和排查。

解决方案：

在您的 Nginx（或代理）配置文件中：
- 请务必将以下接口地址排除在服务端缓存机制之外：
  - /api、/oauth、/callback、/login、/ws、/websocket
- 任何核心的登录、鉴权和 WebSocket 连接入口绝对不能被缓存！
修改配置文件后，请重新载入（Reload）您的代理服务配置。

Nginx 排除缓存配置参考示例：

# 为登录、OAuth、WebSocket 接口禁用代理缓存
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 回调及登录接口。缓存这些地址会导致下发过期的 Token 或使会话数据被污染，从而引发完全不可预测的认证异常。

常见技术故障：反向代理服务器关于 Cookie 的相关参数设置可能会阻断 OAuth 的正常流转，特别是 Cookie 的 HttpOnly 以及 SameSite 属性。

具体表现与症状：

报 "No token found in localStorage"（未在 localStorage 中发现 Token）错误。
在身份验证通过后，页面陷入无休止的回调重定向循环。
授权看似成功，但界面在瞬间又被重新踢回到登录页面。

解决方案：

针对 NGINX Proxy Manager：

# 移除或调整可能存在冲突的 Cookie 参数配置

# ❌ 易引发故障的配置：
# proxy_cookie_path / "/; Secure; HttpOnly; SameSite=None";

# ✅ 更好的兼容性配置：
proxy_cookie_flags ~ secure samesite=lax;

# 或者干直接移除去除所有的 Cookie 干预指令

# 推荐的 OAuth 兼容性 Cookie 变量配置
WEBUI_SESSION_COOKIE_SAME_SITE=lax
WEBUI_AUTH_COOKIE_SAME_SITE=lax
WEBUI_SESSION_COOKIE_SECURE=true  # 如果没有配置 HTTPS 证书而仅使用纯 HTTP，请将其设为 false
WEBUI_AUTH_COOKIE_SECURE=true     # 如果没有配置 HTTPS 证书而仅使用纯 HTTP，请将其设为 false

8. 网络超时问题

外部的 OAuth 授权服务商的节点响应缓慢，会导致 Open WebUI 在执行认证握手时触发超时报错。

具体表现与症状：

后端日志中输出 httpcore.ReadTimeout 超时报错。
日志输出 CSRF Warning! State not equal in request and response（CSRF 警告：请求与响应中的状态值不一致）。
用户使用 OAuth 登录时偶尔成功，偶尔失败。

解决方案：

# 调大 OAuth 的连接超时上限
AIOHTTP_CLIENT_TIMEOUT=600         # 这里建议配置为极大的数值，因为执行时间长的推理模型（如某些大模型推理时间长达 5 分钟以上）也共用此超时变量
AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST=30

9. 会话状态不匹配（CSRF 错误）

在 OAuth 重定向和页面跳转流转中，会话 Cookie（Session Cookies）可能未能被浏览器妥善维系。

具体表现与症状：

日志输出 CSRF Warning! State not equal in request and response。
后端报错输出 mismatching_state。
界面提示授权已成功，但转头就被拉回到了初始登录页。

解决方案：

核对 Cookie 作用域及域名配置：

# 确保下发 Cookie 时作用于正确的域名下
WEBUI_URL=https://your-exact-domain.com  # 必须与真实访问的域名完全吻合 - 请同时核实管理员面板里是否配了不一致的值

会话加密参数校验：

# 确认会话秘钥配置牢靠且未发生漂移
WEBUI_SECRET_KEY=your_very_secure_random_key_here
OAUTH_SESSION_TOKEN_ENCRYPTION_KEY=another_secure_key_here

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

在集群或多副本的多实例部署下，如果在各实例间无法实时同步会话，OAuth 验证在流向不同容器时会发生报错。

集群环境所需的配置：

# 必须引入 Redis 执行会话全局同步（多实例部署的刚需）
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

# 为集群环境开启 WebSocket 协议支持
ENABLE_WEBSOCKET_SUPPORT=true
WEBSOCKET_MANAGER=redis

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

Microsoft Entra ID 常见问题：

核心痛点：使用了通用的 OIDC 环境变量，而没有使用 Microsoft 专属的专用变量。

✅ 针对 Microsoft 的正确变量配置：

# 请配置 Microsoft 专属的环境变量，切勿混用通用的 OIDC 变量
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

# 保证 Microsoft 架构工作正常的其他配对变量
OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration
ENABLE_OAUTH_SIGNUP=true

Authentik 常见问题：

核心痛点：提供的授权服务商配置 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 存取 Token”。如果登录失效：

彻底清理您浏览器的 Cookie 以及本地缓存。
检查浏览器开发者工具（Developer Tools）中的存储：
- 寻找名为 oauth_session_id 的 Cookie（此为全新推荐的鉴权方案）。
- 检查是否存在 oauth_id_token 的 Cookie（此为已被弃用的旧版方案）。
- 核对这些 Cookie 下发的 Domain（域名）和 Path（路径）是否完美对应。

调试 OAuth 流程

将日志级别调高，全面追踪 OAuth 请求的每一个呼吸：

# 激活最高级别的 DEBUG 日志
GLOBAL_LOG_LEVEL=DEBUG

# 随后重点盯防日志中的这四步生命周期：
# 1. 发起 GET /oauth/{provider}/login - 应该正确返回 302 临时重定向
# 2. 用户在跳转后的授权服务商页面完成登录
# 3. 回调接收 GET /oauth/{provider}/callback?code=... - 应该返回 200 成功或正确的重定向
# 4. 用户账号完成校验并成功进入主界面

数据库调试

验证 OAuth 回调时是否有成功将账号数据持久化落库：

# 进入您的 Open WebUI 容器内部
docker exec -it your-openwebui-container sh

# 核实数据存放目录下的文件状态（请根据您的具体存储路径调整）
ls -la /app/backend/data/

脱离反向代理进行测试

如果不确定是不是反向代理在从中作梗，请跳过反向代理直接测试 WebUI：

临时将 Open WebUI 的宿主机物理端口直接对外暴露。
将您 OAuth 授权控制台上的回调 URI 改为指向这一物理端口。
跳过 Nginx 等代理，直接用纯 IP+端口进行登录调试。
如果此模式下能够成功登录，说明问题绝对出在反向代理的拦截规则上。

专业建议：检查日志

始终将后端容器的日志与浏览器控制台的网络流（Network）报错结合起来判定。第一个抛出的异常往往就是引发整个雪崩的根源。
如果分不清是哪一端出了问题，使用无痕浏览器（Incognito）窗口尝试登录，这能帮您过滤掉一切历史脏缓存和旧的 Cookie 干扰。

重点关注的关键日志信息：

OAuth callback error: mismatching_state → 大概率是 Session 状态或 Cookie 发生冲突。
httpcore.ReadTimeout → 服务器与授权服务商之间的网络延迟过大发生超时。
The email or password provided is incorrect → 通常表明 OAuth 已经顺利闭环，但由于会话握手失败没能正常建立 Session。
404 错误出现在回调接口上 → 授权商端的回调 URI（Redirect URI）注册写错了。

总结核对清单 ✅

引发的具体故障	对应的排查与修复方案
🔗 WebUI URL 缺失或配置有误	请在 Admin Settings 面板中补全正确的 WebUI 物理域名
📝 环境变量存在拼写错误或不存在	严格比对文档，避免使用已被弃用的旧版参数（如 `OIDC_CONFIG`）
🚨 缺失 OPENID_PROVIDER_URL 变量	OIDC 的必填项——必须配为授权商的 `.well-known/openid-configuration` 配置页
🔄 本地与数据库持久化配置发生冲突	配置 `ENABLE_OAUTH_PERSISTENT_CONFIG=false` 以强制以环境变量为尊
🏢 授权提供商端控制台注册写错	再次检查提供商控制台中的 redirect URIs、Client ID 以及 Secret 是否一致
🧊 反向代理缓存机制横加干涉	将 OAuth 以及 login 相关的这几个回调接口彻底划入反代免缓存白名单
🍪 浏览器 Cookie 传递被掐断	检查您的反代服务器对 Cookie 属性（HttpOnly/Secure）的干写行为
⏱️ 网络偶发性断开超时	手动调高 `AIOHTTP_CLIENT_TIMEOUT` 等超时容忍阈值
🔐 CSRF 或会话无法确立	重点审计 `WEBUI_SECRET_KEY` 的配置，并确认跨域配置无误
🔀 多实例部署下鉴权失败	必须拉起 Redis 进行会话同步，并统筹好所有容器的 WEBUI_SECRET_KEY 秘钥
依然没有头绪？	开启 DEBUG 级别日志，脱离反代直连物理端口，核实身份提供商控制台日志

通过细心核对身份提供商端的注册表单、打通 Open WebUI 的网络环境变量，并让所有的登录接口与反代缓存完全隔离，您可以极其轻松地根治 99% 的 SSO/OAuth 登录顽疾。

Token 吊销需要 Redis 支持

若未接入 Redis 服务，用户的登出（Sign out）行为将无法使已生成的 JWT Token 彻底失效 —— 在过期期限截止前（默认长达 4 周），这些 Token 依然可以被用来合法调取接口。对于企业级 SSO/OAuth 部署，这会制造重大的网络安全隐患（例如离职员工在被禁用系统账号后，其设备上的 Token 在短期内依然能够连通后台）。在此架构下，仅靠修改密码或管理员单方面禁用账号同样无法立刻撤销已发出的 Token。

对于需要高安全性的 SSO 生产部署，请务必配置 Redis，或者大幅缩短 JWT_EXPIRES_IN（Token 生效期）的参数。详情请参阅系统加固指南-Token 吊销以及 Redis 部署指南。

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.

常见的 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. 会话状态不匹配（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. 会话状态不匹配（CSRF 错误）

具体表现与症状：

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

集群环境所需的配置：

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

Microsoft Entra ID 常见问题：

Authentik 常见问题：

高级故障排查技巧

检查 Token 存储方式

调试 OAuth 流程

数据库调试

脱离反向代理进行测试

专业建议：检查日志

重点关注的关键日志信息：

总结核对清单 ✅