跳到主要内容

SSO（OAuth、OIDC、Trusted Header）

信息

所有相关环境变量的完整说明请查看 Environment Variable Configuration。

提示

如果你在排查 SSO 问题，请直接查看 SSO 故障排查。

当前只支持一个 OIDC Provider

目前通过 OPENID_PROVIDER_URL 一次只能配置一个 OIDC 提供方。也就是说，不能同时把 Microsoft 和 Google 都作为标准 OIDC provider 接入。

如果你确实需要双 OAuth 提供方，可以参考社区方案：Dual OAuth Tutorial。

OAuth 配置总览​

环境变量默认值说明
WEBUI_URL—必填，你的公开 WebUI 地址
ENABLE_OAUTH_PERSISTENT_CONFIGtrue是否把 OAuth 配置持久化到数据库
ENABLE_OAUTH_SIGNUPfalse是否允许通过 OAuth 登录时自动创建账号
OAUTH_MERGE_ACCOUNTS_BY_EMAILfalse是否按邮箱合并账号
OAUTH_UPDATE_PICTURE_ON_LOGINfalse登录时是否同步更新头像
OAUTH_PICTURE_CLAIMpicture头像字段名
WEBUI_AUTH_SIGNOUT_REDIRECT_URL空登出后的重定向地址
WEBUI_SECRET_KEY空必须设置，尤其在多副本环境中
OAUTH_SESSION_TOKEN_ENCRYPTION_KEYWEBUI_SECRET_KEY用于加密服务端存储的 OAuth token
OAUTH_CLIENT_INFO_ENCRYPTION_KEYWEBUI_SECRET_KEY用于加密 OAuth client 信息
ENABLE_OAUTH_ID_TOKEN_COOKIEtrue是否设置旧版 oauth_id_token cookie
ENABLE_OAUTH_TOKEN_EXCHANGEfalse启用 token exchange 端点
ENABLE_OAUTH_BACKCHANNEL_LOGOUTfalse启用 OIDC Back-Channel Logout
OAUTH_MAX_SESSIONS_PER_USER10每个用户每个 provider 最大并发 OAuth session 数
关键配置注意事项
  1. 先配置 WEBUI_URL，再启用 OAuth，否则 redirect URI 会出错
  2. 当 ENABLE_OAUTH_PERSISTENT_CONFIG=true 时，首次启动后 OAuth 配置会写入数据库。后续若改环境变量，要么把它设为 false，要么在 管理员面板 中直接改
  3. 一定要使用官方文档中存在的变量名，不要误用不存在的名字，例如 OIDC_CONFIG

服务端 OAuth Session 管理​

为了解决大 token（例如 AD FS 返回超大 group claim）和自动 token 刷新的问题， OPL 数据空间现在采用更稳妥的服务端 Session 管理：

  1. access_token / id_token 不再主要依赖浏览器 cookie 存储，而是加密后存放在服务端数据库的 oauth_session 表中
  2. 浏览器只拿到一个很小的 oauth_session_id 安全 cookie
  3. 支持多设备并发登录，同一用户在第二台设备登录不会踢掉第一台设备
  4. 当下游服务需要 token 时，后端会根据 session 读取并在必要时自动刷新 token
  5. 这样内部工具和服务就可以稳定、安全地获取用户 OAuth token

这套机制默认启用，可通过上面的环境变量进行调优。

OAuth Token Exchange​

OPL 数据空间支持 OAuth Token Exchange：外部应用可以把已经拿到的 OAuth provider access token 换成 OPL 数据空间自己的 JWT session token。

适合场景包括：

  • CLI 工具
  • 外部服务
  • 已经完成 IdP 登录的脚本或自动化流程

启用方式：

ENABLE_OAUTH_TOKEN_EXCHANGE=true

详细行为请看 ENABLE_OAUTH_TOKEN_EXCHANGE。

OIDC Back-Channel Logout​

OPL 数据空间支持 OIDC Back-Channel Logout，允许身份提供方在不依赖浏览器跳转的情况下，直接通过服务端通知 OPL 数据空间用户已登出。

启用方式：

ENABLE_OAUTH_BACKCHANNEL_LOGOUT=true

启用后会开放：

  • POST /oauth/backchannel-logout
注意

如果想完整执行 JWT 撤销，Redis 基本是必须的。

  • 有 Redis：可以同步撤销相关 JWT 并删除 OAuth session
  • 无 Redis：只能删除服务端 OAuth session，已发出的 JWT 仍会继续有效直到过期

常见 Provider​

Tailscale Serve​

如果你的目标是同时解决私网暴露、HTTPS 和 SSO，可以优先查看 Tailscale 教程。它适合不想把 OPL 数据空间直接暴露到公网，但又希望远程团队安全访问的场景。

Google​

Google OAuth 需要：

  1. GOOGLE_CLIENT_ID
  2. GOOGLE_CLIENT_SECRET
  3. OPENID_PROVIDER_URL（为了正确处理 logout，通常为 https://accounts.google.com/.well-known/openid-configuration）

允许的 redirect URI 应包含：

  • <open-webui>/oauth/google/callback

可选参数：

  • GOOGLE_OAUTH_AUTHORIZE_PARAMS

例如：

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

Microsoft​

Microsoft OAuth 需要：

  1. MICROSOFT_CLIENT_ID
  2. MICROSOFT_CLIENT_SECRET
  3. MICROSOFT_CLIENT_TENANT_ID
  4. MICROSOFT_REDIRECT_URI
  5. OPENID_PROVIDER_URL

redirect URI 必须是：

  • <open-webui>/oauth/microsoft/callback

Token 刷新与 offline_access​

如果你希望 OPL 数据空间能自动刷新 Microsoft access token，需要把 scope 配成：

MICROSOFT_OAUTH_SCOPE=openid email profile offline_access

否则当 access token 过期后，像 MCP tool server、OneDrive / SharePoint 访问、头像自动刷新等能力会失败。

Entra ID 角色映射

如果你想使用 Entra ID app roles 来控制谁是 admin、谁是 user，还需要结合下文的 OAuth Role Management 一起配置。

GitHub​

GitHub OAuth 需要：

  1. GITHUB_CLIENT_ID
  2. GITHUB_CLIENT_SECRET

redirect URI 应包含：

  • <open-webui>/oauth/github/callback

通用 OIDC​

任何支持 OIDC 的身份提供方都可以接入。必须能提供 email claim，name 和 picture 则是可选增强信息。

常用变量：

  1. OAUTH_CLIENT_ID
  2. OAUTH_CLIENT_SECRET
  3. OPENID_PROVIDER_URL（必填）
  4. OAUTH_PROVIDER_NAME
  5. OAUTH_SCOPES
  6. OPENID_REDIRECT_URI
  7. OAUTH_AUDIENCE
常见 OIDC 配置错误
  • 使用了不存在的变量，例如 OIDC_CONFIG、WEBUI_OIDC_CLIENT_ID
  • 忘记配置 OPENID_PROVIDER_URL
  • redirect URI 写错，标准格式必须是 <your-domain>/oauth/oidc/callback

OAuth Role Management​

如果 OAuth provider 会在 token 中返回 roles， OPL 数据空间就可以据此决定用户角色。

启用方式：

ENABLE_OAUTH_ROLE_MANAGEMENT=true

相关变量：

  1. OAUTH_ROLES_CLAIM
  2. OAUTH_ALLOWED_ROLES
  3. OAUTH_ADMIN_ROLES
  4. OAUTH_ROLES_SEPARATOR
信息

如果你改了某个已登录用户的 OAuth 角色，他需要重新登录才能拿到新角色。

OAuth Group Management​

如果 provider 会在 token 中返回 group 信息， OPL 数据空间可以在登录时同步用户组。

启用方式：

ENABLE_OAUTH_GROUP_MANAGEMENT=true

相关变量：

  1. OAUTH_GROUP_CLAIM
  2. ENABLE_OAUTH_GROUP_CREATION
  3. OAUTH_GROUP_DEFAULT_SHARE
严格同步

启用 OAuth Group Management 后，用户在 OPL 数据空间中的组成员关系会在每次登录时严格与 OAuth claim 同步：

  • claim 中出现的组会被加入
  • claim 中不存在的组会被移除

因此请确保 IdP 中的组配置是完整且正确的。