单点登录 (SSO: OAuth, OIDC, 信任头)

提示

有关所有环境变量的更多信息，请查看环境变量文档页面。强烈建议检查环境变量页面，以获取有关如何设置变量以及预期值的更多详细信息。

建议

在排查 SSO 设置问题时需要帮助吗？查看我们的故障排除指南

仅支持单个 OIDC 提供商

目前，您一次只能通过 OPENID_PROVIDER_URL 配置一个 OpenID Connect (OIDC) 提供商。您不能同时将 Microsoft 和 Google 作为 OIDC 提供商。

但是，社区有一个同时使用两者的解决方法！有关更多详细信息，请参阅我们的双 OAuth 教程。

OAuth 配置概览

环境变量	默认值	描述
`WEBUI_URL`	—	必需。您的公开 WebUI 地址，例如 `http://localhost:8080`。
`ENABLE_OAUTH_PERSISTENT_CONFIG`	`true`	将 OAuth 配置持久化到数据库；对于无状态/容器化环境，请设置为 `false`。
`ENABLE_OAUTH_SIGNUP`	`false`	允许通过 OAuth 登录时创建账户（与 `ENABLE_SIGNUP` 独立）。
`OAUTH_MERGE_ACCOUNTS_BY_EMAIL`	`false`	根据匹配的电子邮件合并 OAuth 登录（注意：如果提供商不验证电子邮件，这可能是不安全的）。
`OAUTH_UPDATE_PICTURE_ON_LOGIN`	`true`	每次登录时从 OAuth 提供商更新用户个人资料图片。
`OAUTH_PICTURE_CLAIM`	`picture`	包含个人资料图片的 claim 字段。设置为空字符串以禁用图片更新（用户将收到默认图标）。
`WEBUI_AUTH_SIGNOUT_REDIRECT_URL`	空	退出登录后将用户重定向到此 URL。例如 `https://your-company.com/logout-success`
`WEBUI_SECRET_KEY`	空	必须设置 - 特别是在集群环境中。否则会出现会话问题和奇怪的 OAuth 问题
`OAUTH_SESSION_TOKEN_ENCRYPTION_KEY`	`WEBUI_SECRET_KEY`	用于加密存储在服务器上的 OAuth 令牌的密钥。必须在集群中的所有实例之间共享。
`OAUTH_CLIENT_INFO_ENCRYPTION_KEY`	`WEBUI_SECRET_KEY`	用于加密存储在服务器上的 OAuth 客户端信息的密钥 - 用于 MCP 服务器的 OAuth 2.1 身份验证。
`ENABLE_OAUTH_ID_TOKEN_COOKIE`	`true`	为了向后兼容。控制是否设置旧版的 `oauth_id_token` cookie。建议设置为 `false`。

注意

关键配置说明：

必须先设置 WEBUI_URL：在启用 OAuth 之前，请先在管理员面板中配置 WEBUI_URL，因为它用于重定向 URI。
持久化配置行为：当 ENABLE_OAUTH_PERSISTENT_CONFIG=true（默认值）时，OAuth 设置在首次启动后存储在数据库中。要在初始设置后更改环境变量，可以：
- 设置 ENABLE_OAUTH_PERSISTENT_CONFIG=false 以始终从环境变量中读取
- 通过管理员面板更新设置，而不是通过环境变量
必需变量：请务必验证您使用的是环境配置文档中确切的变量名称。常见的错误包括使用不存在的变量，如 OIDC_CONFIG。

服务端 OAuth 会话管理

为了解决与大型令牌相关的问题（例如，AD FS 组 claim 超过 cookie 大小限制）并启用自动令牌刷新，Open WebUI 现在支持强大的服务端会话管理系统。

工作原理：

服务端存储： 不再将大型 access_token 和 id_token 值存储在浏览器 cookie 中，而是将整个令牌负载加密并安全地存储在 Open WebUI 数据库的新 oauth_session 表中。
安全会话 Cookie： 用户的浏览器会收到一个名为 oauth_session_id 的小型且安全的 httponly cookie。此 cookie 作为不透明标识符，其本身不包含任何敏感信息。
自动刷新： 当下游服务（如工具或 OpenAI 兼容端点）需要令牌时，后端使用 oauth_session_id 检索令牌。如果令牌已过期或即将过期，系统会自动使用存储的 refresh_token 从提供商处获取新令牌，然后再转发。这确保了服务始终收到有效的令牌并防止静默失败。
简洁的令牌访问： 这种架构为内部工具和其他服务访问用户令牌提供了一种简洁且可靠的方式，而无需脆弱的 cookie 抓取。

该系统默认启用，但可以通过上述环境变量进行微调。

有关更多信息，请查看环境变量文档页面。

Google

要配置 Google OAuth 客户端，请参考 Google 的文档，了解如何为 Web 应用程序 创建 Google OAuth 客户端。允许的重定向 URI 应包含 <open-webui>/oauth/google/callback。

需要以下环境变量：

GOOGLE_CLIENT_ID - Google OAuth 客户端 ID
GOOGLE_CLIENT_SECRET - Google OAuth 客户端密钥
OPENID_PROVIDER_URL - 必须设置此项才能使注销正常工作。（通常设置为 https://accounts.google.com/.well-known/openid-configuration）

Microsoft

要配置 Microsoft OAuth 客户端，请参考 Microsoft 的文档，了解如何为 Web 应用程序 创建 Microsoft OAuth 客户端。允许的重定向 URI 应包含 <open-webui>/oauth/microsoft/callback。此值应用于 MICROSOFT_REDIRECT_URI 环境变量。

目前对 Microsoft OAuth 的支持仅限于单个租户，即单个 Entra 组织或个人 Microsoft 帐户。

需要以下环境变量：

MICROSOFT_CLIENT_ID - Microsoft OAuth 客户端 ID
MICROSOFT_CLIENT_SECRET - Microsoft OAuth 客户端密钥
MICROSOFT_CLIENT_TENANT_ID - Microsoft 租户 ID - 个人账户请使用 9188040d-6c67-4c5b-b112-36a304b66dad
MICROSOFT_REDIRECT_URI - 在您的 Microsoft OAuth 应用程序中配置的重定向 URI。必须设置为 <open-webui>/oauth/microsoft/callback。
OPENID_PROVIDER_URL - 必须设置此项才能使注销正常工作。

Github

要配置 Github OAuth 客户端，请参考 Github 的文档，了解如何为 Web 应用程序 创建 OAuth 应用或 Github 应用。允许的重定向 URI 应包含 <open-webui>/oauth/github/callback。

需要以下环境变量：

GITHUB_CLIENT_ID - Github OAuth 应用客户端 ID
GITHUB_CLIENT_SECRET - Github OAuth 应用客户端密钥

OIDC

可以配置任何支持 OIDC 的身份提供商。需要 email claim。如果可用，将使用 name 和 picture claim。允许的重定向 URI 应包含 <open-webui>/oauth/oidc/callback。

使用以下环境变量：

OAUTH_CLIENT_ID - OIDC 客户端 ID
OAUTH_CLIENT_SECRET - OIDC 客户端密钥
OPENID_PROVIDER_URL - 必需。 OIDC 知名 (well-known) URL，例如 https://accounts.google.com/.well-known/openid-configuration
OAUTH_PROVIDER_NAME - 在 UI 上显示的提供商名称，默认为 SSO
OAUTH_SCOPES - 请求的范围。默认为 openid email profile
OPENID_REDIRECT_URI - 在您的 OIDC 应用程序中配置的重定向 URI。必须设置为 <open-webui>/oauth/oidc/callback。
OAUTH_AUDIENCE - 可选的 audience 值，将作为附加查询参数传递给 OAuth 提供商的授权端点。

注意

常见的 OIDC 错误：

使用不存在的环境变量，如 OIDC_CONFIG 或 WEBUI_OIDC_CLIENT_ID
忘记设置 OPENID_PROVIDER_URL（这对于 OIDC 是强制性的）
使用错误的重定向 URI 格式 - 必须正好是 <您的域名>/oauth/oidc/callback

社区解决方法：多提供商 OAuth

如果您需要同时支持 Microsoft 和 Google，请查看我们的 双 OAuth 配置教程。

OAuth 角色管理

任何可以配置为在访问令牌中返回角色的 OAuth 提供商都可以用于管理 Open WebUI 中的角色。要使用此功能，请将 ENABLE_OAUTH_ROLE_MANAGEMENT 设置为 true。您可以配置以下环境变量来匹配 OAuth 提供商返回的角色：

OAUTH_ROLES_CLAIM - 包含角色的 claim。默认为 roles。也可以是嵌套的，例如 user.roles。
OAUTH_ALLOWED_ROLES - 允许登录的逗号分隔角色列表（接收 Open WebUI 角色 user）。
OAUTH_ADMIN_ROLES - 允许作为管理员登录的逗号分隔角色列表（接收 Open WebUI 角色 admin）。
OAUTH_ROLES_SEPARATOR - 允许为 OAUTH_*_ROLES 变量指定备用分隔符。如果 claim 是字符串且包含该分隔符，它也将按该分隔符拆分。

提示

如果更改已登录用户的角色，他们将需要注销并重新登录才能获得新角色。

OAuth 组管理

任何可以配置为在访问令牌中返回组的 OAuth 提供商都可以用于在用户登录时管理 Open WebUI 中的用户组。要启用此同步，请将 ENABLE_OAUTH_GROUP_MANAGEMENT 设置为 true。

您可以配置以下环境变量：

OAUTH_GROUP_CLAIM - ID/访问令牌中包含用户组数成员身份的 claim。默认为 groups。也可以是嵌套的，例如 user.memberOf。如果 ENABLE_OAUTH_GROUP_MANAGEMENT 为 true，则此项为必需。
ENABLE_OAUTH_GROUP_CREATION - 如果为 true（且 ENABLE_OAUTH_GROUP_MANAGEMENT 也为 true），Open WebUI 将执行 即时 (Just-in-Time, JIT) 组创建。这意味着如果在用户的 OAuth claim 中存在但在系统中尚不存在，它将在 OAuth 登录期间自动创建组。默认为 false。如果为 false，则仅管理现有 Open WebUI 组中的成员身份。

注意

严格的组同步当 ENABLE_OAUTH_GROUP_MANAGEMENT 设置为 true 时，Open WebUI 中的用户组成员身份在每次登录时都会与从其 OAuth claim 中收到的组 严格同步。

用户将被添加到与其 OAuth claim 匹配的 Open WebUI 组中。
如果某些 Open WebUI 组（包括手动创建或在 Open WebUI 中分配的组）未出现在该登录会话的 OAuth claim 中，用户将被从这些组中移除。

确保在您的 OAuth 提供商中正确配置了所有必要的组，并包含在组 claim (OAUTH_GROUP_CLAIM) 中。

注意

管理员用户管理员用户的组成员身份不会通过 OAuth 组管理自动更新。

提示

需要登录才能更新

如果用户的组在 OAuth 提供商中发生更改，他们将需要注销 Open WebUI 并重新登录才能使更改生效。

信任头 (Trusted Header)

Open WebUI 能够将身份验证委托给一个身份验证反向代理，该代理在 HTTP 头中传递用户详细信息。本页面提供了一些配置示例。

危险

错误的配置可能允许用户以 Open WebUI 实例上的任何用户身份进行身份验证。确保仅允许身份验证代理访问 Open WebUI，例如不直接向容器开放任何端口，或设置 HOST=127.0.0.1 使其仅在回环接口上监听。

通用配置

当设置了 WEBUI_AUTH_TRUSTED_EMAIL_HEADER 环境变量时，Open WebUI 将使用指定头的值作为用户的电子邮件地址，处理自动注册和登录。

例如，设置 WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email 并传递 X-User-Email: example@example.com 的 HTTP 头将以电子邮件 example@example.com 对请求进行身份验证。

（可选）您还可以定义 WEBUI_AUTH_TRUSTED_NAME_HEADER 来确定使用信任头创建的任何用户的名称。如果用户已经存在，则此操作无效。如果未设置 WEBUI_AUTH_TRUSTED_NAME_HEADER，则电子邮件地址将用作用户名。

组管理

您可以使用 WEBUI_AUTH_TRUSTED_GROUPS_HEADER 环境变量来同步 Open WebUI 中的用户组。将此变量设置为 HTTP 头的名称，该头将包含经过身份验证用户的逗号分隔组名列表。

当通过 WEBUI_AUTH_TRUSTED_EMAIL_HEADER 对请求进行身份验证，并且设置并存在信任组头时，Open WebUI 将更新用户的组成员身份以匹配头中列出的组。

头的值必须是逗号分隔的组名列表（例如 X-User-Groups: admins,editors,users）。
如果头不存在或为空，则不会更新用户的组成员身份。
用户将被取消分配未在头中出现的组。
通过信任头进行的组创建不是自动的；只会分配 Open WebUI 中现有的组。

Tailscale Serve

Tailscale Serve 允许您在 tailnet 内共享服务，Tailscale 将设置带有请求者电子邮件地址的头 Tailscale-User-Login。

下面是一个示例 serve 配置，以及相应的 Docker Compose 文件，该文件启动了一个 Tailscale sidecar，将 Open WebUI 暴露给带有标签 open-webui 和主机名 open-webui 的 tailnet，并且可以通过 https://open-webui.TAILNET_NAME.ts.net 访问。您需要创建一个具有设备写入权限的 OAuth 客户端，作为 TS_AUTHKEY 传递到 Tailscale 容器中。

tailscale/serve.json
{
    "TCP": {
        "443": {
            "HTTPS": true
        }
    },
    "Web": {
        "${TS_CERT_DOMAIN}:443": {
            "Handlers": {
                "/": {
                    "Proxy": "http://open-webui:8080"
                }
            }
        }
    }
}

docker-compose.yaml
---
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - WEBUI_AUTH_TRUSTED_EMAIL_HEADER=Tailscale-User-Login
      - WEBUI_AUTH_TRUSTED_NAME_HEADER=Tailscale-User-Name
    restart: unless-stopped
  tailscale:
    image: tailscale/tailscale:latest
    environment:
      - TS_AUTH_ONCE=true
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_EXTRA_ARGS=--advertise-tags=tag:open-webui
      - TS_SERVE_CONFIG=/config/serve.json
      - TS_STATE_DIR=/var/lib/tailscale
      - TS_HOSTNAME=open-webui
    volumes:
      - tailscale:/var/lib/tailscale
      - ./tailscale:/config
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
      - sys_module
    restart: unless-stopped

volumes:
  open-webui: {}
  tailscale: {}

注意

如果您在与 Open WebUI 相同的网络上下文中运行 Tailscale，则默认情况下用户将能够直接访问 Open WebUI，而无需通过 Serve 代理。您需要使用 Tailscale 的 ACL 来限制仅访问 443 端口。

带有 Cloudflare Access 的 Cloudflare Tunnel

Cloudflare Tunnel 可以与 Cloudflare Access 配合使用，通过 SSO 保护 Open WebUI。 Cloudflare 对此的文档非常少，但 Cf-Access-Authenticated-User-Email 会设置为经过身份验证用户的电子邮件地址。

下面是一个设置 Cloudflare sidecar 的示例 Docker Compose 文件。配置通过控制面板完成。从控制面板获取隧道令牌，将隧道后端设置为 http://open-webui:8080，并确保选中并配置了 "Protect with Access"。

docker-compose.yaml
---
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - WEBUI_AUTH_TRUSTED_EMAIL_HEADER=Cf-Access-Authenticated-User-Email
    restart: unless-stopped
  cloudflared:
    image: cloudflare/cloudflared:latest
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN}
    command: tunnel run
    restart: unless-stopped

volumes:
  open-webui: {}

oauth2-proxy

oauth2-proxy 是一个身份验证反向代理，它实现了社交 OAuth 提供商和 OIDC 支持。

鉴于潜在配置数量庞大，下面是一个使用 Google OAuth 的潜在设置示例。请参阅 oauth2-proxy 的文档以获取详细设置和任何潜在的安全注意事项。

docker-compose.yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - 'WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-Forwarded-Email'
      - 'WEBUI_AUTH_TRUSTED_NAME_HEADER=X-Forwarded-User'
    restart: unless-stopped
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy:v7.6.0
    environment:
      OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
      OAUTH2_PROXY_UPSTREAMS: http://open-webui:8080/
      OAUTH2_PROXY_PROVIDER: google
      OAUTH2_PROXY_CLIENT_ID: REPLACEME_OAUTH_CLIENT_ID
      OAUTH2_PROXY_CLIENT_SECRET: REPLACEME_OAUTH_CLIENT_ID
      OAUTH2_PROXY_EMAIL_DOMAINS: REPLACEME_ALLOWED_EMAIL_DOMAINS
      OAUTH2_PROXY_REDIRECT_URL: REPLACEME_OAUTH_CALLBACK_URL
      OAUTH2_PROXY_COOKIE_SECRET: REPLACEME_COOKIE_SECRET
      OAUTH2_PROXY_COOKIE_SECURE: "false"
    restart: unless-stopped
    ports:
      - 4180:4180/tcp

Authentik

要配置 Authentik OAuth 客户端，请参考文档了解如何创建应用程序和 OAuth2/OpenID 提供商。允许的重定向 URI 应包含 <open-webui>/oauth/oidc/callback。

在创建提供商时，请记录 App-name、Client-ID 和 Client-Secret，并将其用于 Open WebUI 环境变量：

      - 'ENABLE_OAUTH_SIGNUP=true'
      - 'OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true'
      - 'OAUTH_PROVIDER_NAME=Authentik'
      - 'OPENID_PROVIDER_URL=https://<authentik-url>/application/o/<App-name>/.well-known/openid-configuration'
      - 'OAUTH_CLIENT_ID=<Client-ID>'
      - 'OAUTH_CLIENT_SECRET=<Client-Secret>'
      - 'OAUTH_SCOPES=openid email profile'
      - 'OPENID_REDIRECT_URI=https://<open-webui>/oauth/oidc/callback'

Authelia

Authelia 可以配置为返回一个头，用于信任头身份验证。文档可在此处找到。

由于部署 Authelia 的复杂性，此处不提供示例配置。

OAuth 配置概览​

服务端 OAuth 会话管理​

Google​

Microsoft​

Github​

OIDC​

OAuth 角色管理​

OAuth 组管理​

信任头 (Trusted Header)​

通用配置​

组管理​

Tailscale Serve​

带有 Cloudflare Access 的 Cloudflare Tunnel​

oauth2-proxy​

Authentik​

Authelia​

OAuth 配置概览

服务端 OAuth 会话管理

Google

Microsoft

Github

OIDC

OAuth 角色管理

OAuth 组管理

信任头 (Trusted Header)

通用配置

组管理

Tailscale Serve

带有 Cloudflare Access 的 Cloudflare Tunnel

oauth2-proxy

Authentik

Authelia