跳到主要内容

联邦认证支持

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

  1. OAuth2
    1. Google
    2. Microsoft
    3. Github
    4. OIDC
  2. 受信任的头部

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 适用于大多数提供程序；如果设置为空字符串，所有用户将获得默认的个人资料图片。

Google​

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

需要以下环境变量

  1. GOOGLE_CLIENT_ID - Google OAuth 客户端 ID
  2. GOOGLE_CLIENT_SECRET - Google OAuth 客户端密钥

Microsoft​

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

目前对 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

Github​

要配置 Github OAuth 客户端，请参阅 Github 文档，了解如何为网络应用程序创建 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 客户端密钥

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

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 群组。
  • 如果用户在 Open WebUI 中的任何群组（包括那些在 Open WebUI 中手动创建或分配的群组）未出现在其该次登录会话的 OAuth 声明中，则用户将从这些群组中被移除。

确保所有必要的群组在您的 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 以确定使用受信任头部创建的任何用户的名称。如果用户已存在，则此项无效。

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:
      - 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，则默认情况下用户无需通过 Serve 代理即可直接访问 Open WebUI。您需要使用 Tailscale 的 ACL 来限制访问仅限于端口 443。

Cloudflare Tunnel 与 Cloudflare Access​

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

下面是一个设置 Cloudflare sidecar 的示例 Docker Compose 文件。配置通过仪表盘完成。从仪表盘获取隧道令牌，将隧道后端设置为 http://open-webui:8080，并确保勾选并配置了“使用 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 提供程序。允许的重定向 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 的复杂性，未提供示例配置。