跳到主要内容

联邦认证支持

Open WebUI 支持多种形式的联邦认证：

  1. OAuth2
    1. Google
    2. Microsoft
    3. Github
    4. OIDC
  2. 可信头部
信息

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

危险

目前，您一次只能配置一个 OAuth 提供商。您无法同时将 Microsoft 和 Google 配置为提供商。

OAuth​

OAuth 通常有以下几个全局配置选项：

  1. ENABLE_OAUTH_SIGNUP - 如果为 true，则允许通过 OAuth 登录时创建账户。这与 ENABLE_SIGNUP 不同。
  2. OAUTH_MERGE_ACCOUNTS_BY_EMAIL - 允许登录与 OAuth 提供商提供的电子邮件地址匹配的账户。
    • 这被认为是不安全的，因为并非所有 OAuth 提供商都验证电子邮件地址，这可能导致账户被劫持。
  3. OAUTH_UPDATE_PICTURE_ON_LOGIN - 如果为 true，用户登录时将更新 OAuth 提供的个人资料图片。
    • 如果通过将 OAUTH_PICTURE_CLAIM 设置为空字符串来禁用 OAuth 图片声明，则此配置将被忽略。
  4. OAUTH_PICTURE_CLAIM - 可用于自定义或禁用个人资料图片存储。默认值 picture 适用于大多数提供商；如果设置为空字符串，所有用户都将获得默认人物个人资料图片。
  5. WEBUI_AUTH_SIGNOUT_REDIRECT_URI - 可选地设置，用于在用户退出登录后将其转发到特定的 URI。

Google​

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

需要以下环境变量：

  1. GOOGLE_CLIENT_ID - Google OAuth 客户端 ID
  2. GOOGLE_CLIENT_SECRET - Google OAuth 客户端密钥
  3. OPENID_PROVIDER_URL - 必须设置此项才能使登出正常工作。

Microsoft​

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

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

需要以下环境变量：

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

Github​

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

需要以下环境变量：

  1. GITHUB_CLIENT_ID - Github OAuth App 客户端 ID
  2. GITHUB_CLIENT_SECRET - Github OAuth App 客户端密钥
  3. OPENID_PROVIDER_URL - 必须设置此项才能使登出正常工作。

OIDC​

任何支持 OIDC 的认证提供商都可以配置。email 声明是必需的。如果可用，则使用 name 和 picture 声明。允许的重定向 URI 应包含 <open-webui>/oauth/oidc/callback。

使用以下环境变量：

  1. OAUTH_CLIENT_ID - OIDC 客户端 ID
  2. OAUTH_CLIENT_SECRET - OIDC 客户端密钥
  3. OPENID_PROVIDER_URL - OIDC 知名 URL，例如 https://#/.well-known/openid-configuration
  4. OAUTH_PROVIDER_NAME - 在 UI 上显示的提供商名称，默认为 SSO
  5. OAUTH_SCOPES - 要请求的范围。默认为 openid email profile
  6. OPENID_REDIRECT_URI - 在您的 OIDC 应用程序中配置的重定向 URI。此项必须设置为 <open-webui>/oauth/oidc/callback。

OAuth 角色管理​

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

  1. OAUTH_ROLES_CLAIM - 包含角色的声明。默认为 roles。也可以是嵌套的，例如 user.roles。
  2. OAUTH_ALLOWED_ROLES - 允许登录（获得 Open WebUI user 角色）的角色的逗号分隔列表。
  3. OAUTH_ADMIN_ROLES - 允许作为管理员登录（获得 Open WebUI admin 角色）的角色的逗号分隔列表。
信息

如果更改已登录用户的角色，他们需要先退出登录再重新登录才能获得新角色。

OAuth 群组管理​

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

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

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

当 ENABLE_OAUTH_GROUP_MANAGEMENT 设置为 true 时，Open WebUI 中用户的群组成员身份会在每次登录时与他们的 OAuth 声明中收到的群组进行严格同步。

  • 用户将被添加到与他们的 OAuth 声明匹配的 Open WebUI 群组。
  • 如果用户的 OAuth 声明中不存在某个登录会话的群组（包括在 Open WebUI 中手动创建或分配的群组），用户将被从 Open WebUI 中的任何此类群组中移除。

确保所有必要的群组在您的 OAuth 提供商中正确配置，并包含在群组声明（OAUTH_GROUP_CLAIM）中。

管理员用户

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

更新需要重新登录

如果用户的群组在 OAuth 提供商中发生更改，他们需要退出 Open WebUI 并重新登录才能反映这些更改。

可信头部​

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 并传递 HTTP 头部 X-User-Email: example@example.com 将使用电子邮件 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 边车，将 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:
      - HOST=127.0.0.1
      - 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 Tunnel 与 Cloudflare Access​

Cloudflare Tunnel 可与 Cloudflare Access 结合使用以通过 SSO 保护 Open WebUI。Cloudflare 对此文档描述很少，但 Cf-Access-Authenticated-User-Email 会设置为已认证用户的电子邮件地址。

下面是一个设置 Cloudflare 边车的 Docker Compose 文件示例。配置通过仪表板完成。从仪表板获取隧道令牌，将隧道后端设置为 http://open-webui:8080，并确保勾选并配置“Protect with Access”（使用 Access 保护）。

docker-compose.yaml
---
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    volumes:
      - open-webui:/app/backend/data
    environment:
      - HOST=127.0.0.1
      - 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:
      - 'HOST=127.0.0.1'
      - '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 Provider。允许的重定向 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 的复杂性，此处不提供示例配置。