Skip to main content

排除 OAUTH / SSO 问题

OAUTH 或单点登录 (SSO) 允许您使用现代身份验证方式来保护 Open WebUI，但当用户遇到登录问题时，解决方案通常很简单——只要您知道该往哪里看。大多数情况下，以下关键问题之一就是罪魁祸首。以下是快速排查并修复 SSO 难题的方法！🚦

常见的 OAUTH/SSO 问题及修复方法 🛠️​

1. 管理面板中未配置 WebUI URL 🚪🔒​

大多数 OAUTH 流程需要应用程序的外部 URL（“重定向 URI”），以便提供商知道在登录后将用户发送到何处。如果缺少此项，OAUTH 将无法完成！

✅ 解决方案：

  • 导航至：管理员设置 > 通用
  • 确保您的 WebUI URL 字段已填写，并指向您部署的实例（例如，https://yourwebui.yourdomain.com）
tip

检查是否有拼写错误！OAUTH 非常严格——URL 必须完全匹配，包括 https://。

2. 环境变量配置错误 📝🚫​

这是到目前为止 最常见的 OAUTH 故障原因。如果您拼错、遗漏或设置了错误的环境变量（特别是 OIDC/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

✅ 正确的 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 文件中
  • 更改变量后重启您的后端/应用，以便加载新值
tip

大多数 OAUTH 错误（循环、401、无响应）都是由于环境变量命名错误、完全缺失或使用了过时的变量名称导致的！

3. 缺少必需变量 🚨⚠️​

OIDC 必须设置 OPENID_PROVIDER_URL​

许多用户忘记了这个关键变量。没有它，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