跳到主要内容

SSO 与 OAuth

SSO 与 OAuth 为 OPL 数据空间提供统一、安全的登录机制。登录异常通常可以归结为少数几类配置问题。

常见问题​

1. 未配置 WebUI URL​

多数 OAuth 流程都需要应用对外地址，也就是 redirect URI。如果没有它，provider 无法把用户正确跳回你的实例。

解决方法：

  • 前往 管理设置 > 通用
  • 确保 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 配置示例​

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
OAUTH_AUTHORIZE_PARAMS={"prompt":"consent","login_hint":"user@example.com"}

Google 额外参数​

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

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 manifest 或 .env 中的变量名是否完全正确
  • 修改后重启后端，让新值生效
注意

Kubernetes / YAML 用户要注意变量名里的尾随空格。例如 'OAUTH_CLIENT_ID ' 会被当成另一个变量名， OPL 数据空间无法识别。

3. 缺少必填变量​

对 OIDC 来说，OPENID_PROVIDER_URL 是必填。

常见示例：

  • Microsoft：
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

不同 provider 常见必填项：

  • 所有 OAuth provider：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. Persistent Config 冲突​

OAuth 配置受两个持久化开关影响：

  1. ENABLE_PERSISTENT_CONFIG
  2. ENABLE_OAUTH_PERSISTENT_CONFIG

默认情况下，OAuth 环境变量通常优先于数据库配置，因为 ENABLE_OAUTH_PERSISTENT_CONFIG=false。但如果你之前在管理面板里保存过 OAuth 配置，后来又把它打开，数据库中的旧值就可能覆盖新环境变量。

常见现象：

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

解决方法：

  • 开发 / 测试环境：保持 ENABLE_OAUTH_PERSISTENT_CONFIG=false
  • 生产环境：
    • 要么统一改用管理面板配置
    • 要么继续让环境变量优先
  • 若想完全清理历史状态，可以删除数据库卷重新启动

示例：

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

5. Provider 侧配置错误​

问题也可能出在身份提供方本身，例如 Google、Okta、Auth0、Azure AD。

需要确认：

  • Redirect URI 与 OPL 数据空间实际地址 完全一致
  • Client ID / Secret 与 OPL 数据空间中填写的值一致
  • Scope 与授权类型已按要求启用

常见回调格式：

OIDC:      https://your-domain/oauth/oidc/callback
Microsoft: https://your-domain/oauth/microsoft/callback
Google:    https://your-domain/oauth/google/callback

6. 反向代理缓存导致 OAuth 异常​

如果你在 Nginx 或其他代理层启用了服务端缓存，而没有排除认证相关路径，OAuth 很容易出现随机失败或循环跳转。

请确保以下路径不走缓存：

  • /api
  • /oauth
  • /callback
  • /login
  • /ws
  • /websocket

Nginx 示例：

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;
}

9. Session 状态不一致 / CSRF 错误​

如果你在 OAuth 回调后看到 state mismatch、CSRF 校验失败、重复跳转或偶发登录失败，优先检查：

  • WEBUI_URL 是否与对外地址完全一致
  • 代理层是否改写了协议、Host 或回调路径
  • HTTPS 场景下 cookie 的 SameSite / Secure 是否设置正确
  • 认证相关端点是否被缓存