跳到主要内容
警告

本教程由社区贡献，Open WebUI 团队不提供支持。它仅作为演示如何为特定用例自定义 Open WebUI 的示例。想要贡献？请查看贡献教程。

🔗 Okta OIDC 单点登录 (SSO) 集成

概述​

本文档页面概述了将 Okta OIDC 单点登录 (SSO) 与 Open WebUI 集成所需的步骤。它还涵盖了基于 Okta 群组成员资格管理 Open WebUI 用户群组的可选功能，包括即时 (JIT) 群组创建。按照这些步骤操作，用户将能够使用他们的 Okta 凭据登录 Open WebUI。如果您选择启用群组同步 (ENABLE_OAUTH_GROUP_MANAGEMENT)，用户在登录时将根据其 Okta 群组自动分配到 Open WebUI 中相应的群组。如果您还启用 JIT 群组创建 (ENABLE_OAUTH_GROUP_CREATION)，则 Okta 声明中存在但在 Open WebUI 中缺失的群组将在登录期间自动创建。

先决条件​

  • 一个新的或现有的 Open WebUI 实例。
  • 具有创建和配置应用程序的管理员权限的 Okta 账户。
  • 对 OIDC、Okta 应用程序配置和 Open WebUI 环境变量有基本了解。

设置 Okta​

首先，您需要在您的 Okta 组织内配置一个 OIDC 应用程序，并设置一个群组声明，以便将群组信息传递给 Open WebUI。

1. 在 Okta 中创建/配置 OIDC 应用程序​

  1. 登录您的 Okta 管理控制台。
  2. 导航到 Applications > Applications (应用程序 > 应用程序)。
  3. 创建一个新的 OIDC - OpenID Connect 应用程序（选择 Web Application 作为类型），或者选择一个您希望用于 Open WebUI 的现有应用程序。
  4. 在设置过程中或应用程序的General（通用）设置选项卡中，配置Sign-in redirect URIs（登录重定向 URI）。添加您的 Open WebUI 实例的 URI，后跟 /oauth/oidc/callback。示例：https://your-open-webui.com/oauth/oidc/callback。
  5. 记下应用程序的General（通用）选项卡上提供的Client ID（客户端 ID）和Client secret（客户端密钥）。您将在 Open WebUI 配置中用到这些信息。
  6. 确保在Assignments（分配）选项卡下将正确的用户或群组分配给此应用程序。

2. 在 ID 令牌中添加群组声明​

（可选）为了在 Open WebUI 中基于 Okta 群组启用自动群组管理，您需要配置 Okta 在 ID 令牌中发送用户的群组成员资格信息。如果您只需要 SSO 登录并希望在 Open WebUI 中手动管理群组，可以跳过此部分。

  1. 在管理控制台中，转到 Applications > Applications，然后选择您的 OIDC 客户端应用程序。
  2. 转到 Sign On（登录）选项卡，并在 OpenID Connect ID Token（OpenID Connect ID 令牌）部分点击 Edit（编辑）。
  3. 在 Group claim type（群组声明类型）部分，选择 Filter（过滤器）。
  4. 在 Group claims filter（群组声明过滤器）部分
    • 输入 groups 作为声明名称（如果存在，也可以使用默认值）。
    • 从下拉菜单中选择 Matches regex（匹配正则表达式）。
    • 在正则表达式字段中输入 .*。这将包含用户所属的所有群组。如果需要，您可以使用更具体的正则表达式。
  5. 点击 Save（保存）。
  6. 点击 Back to applications（返回应用程序）链接。
  7. 在您的应用程序的 More（更多）按钮下拉菜单中，点击 Refresh Application Data（刷新应用程序数据）。

有关更高级的群组声明配置，请参阅 Okta 文档关于定制令牌和群组函数的部分。

配置 Open WebUI​

要在 Open WebUI 中启用 Okta OIDC SSO，您需要设置以下核心环境变量。如果您希望启用可选的群组管理功能，则需要额外的变量。

# --- OIDC Core Settings ---
# Enable OAuth signup if you want users to be able to create accounts via Okta
# ENABLE_OAUTH_SIGNUP="true"

# Your Okta application's Client ID
OAUTH_CLIENT_ID="YOUR_OKTA_CLIENT_ID"

# Your Okta application's Client Secret
OAUTH_CLIENT_SECRET="YOUR_OKTA_CLIENT_SECRET"

# Your Okta organization's OIDC discovery URL
# Format: https://<your-okta-domain>/.well-known/openid-configuration
# Or for a specific authorization server: https://<your-okta-domain>/oauth2/<auth-server-id>/.well-known/openid-configuration
OPENID_PROVIDER_URL="YOUR_OKTA_OIDC_DISCOVERY_URL"

# Name displayed on the login button (e.g., "Login with Okta")
OAUTH_PROVIDER_NAME="Okta"

# Scopes to request (default is usually sufficient)
# OAUTH_SCOPES="openid email profile groups" # Ensure 'groups' is included if not default

# --- OAuth Group Management (Optional) ---
# Set to "true" only if you configured the Groups Claim in Okta (Step 2)
# and want Open WebUI groups to be managed based on Okta groups upon login.
# This syncs existing groups. Users will be added/removed from Open WebUI groups
# to match their Okta group claims.
# ENABLE_OAUTH_GROUP_MANAGEMENT="true"

# Required only if ENABLE_OAUTH_GROUP_MANAGEMENT is true.
# The claim name in the ID token containing group information (must match Okta config)
# OAUTH_GROUP_CLAIM="groups"

# Optional: Enable Just-in-Time (JIT) creation of groups if they exist in Okta claims but not in Open WebUI.
# Requires ENABLE_OAUTH_GROUP_MANAGEMENT="true".
# If set to false (default), only existing groups will be synced.
# ENABLE_OAUTH_GROUP_CREATION="false"

请将 YOUR_OKTA_CLIENT_ID、YOUR_OKTA_CLIENT_SECRET 和 YOUR_OKTA_OIDC_DISCOVERY_URL 替换为您 Okta 应用程序配置中的实际值。

要启用基于 Okta 声明的群组同步，请设置 ENABLE_OAUTH_GROUP_MANAGEMENT="true" 并确保 OAUTH_GROUP_CLAIM 与在 Okta 中配置的声明名称匹配（默认为 groups）。

要也启用自动即时 (JIT) 创建 Okta 中存在但在 Open WebUI 中尚未存在的群组，请设置 ENABLE_OAUTH_GROUP_CREATION="true"。如果您只想管理 Open WebUI 中已存在的群组的成员资格，可以将其保留为 false。

群组成员资格管理

当 ENABLE_OAUTH_GROUP_MANAGEMENT 设置为 true 时，用户在 Open WebUI 中的群组成员资格将与他们在每次登录时从 Okta 声明中接收到的群组进行严格同步。这意味着

  • 用户将被添加到与其 Okta 声明匹配的 Open WebUI 群组中。
  • 如果某些 Open WebUI 群组（包括在 Open WebUI 中手动创建或分配的群组）在用户该次登录会话的 Okta 声明中不存在，则用户将从这些群组中移除。

确保所有必需的群组在 Okta 中已正确配置和分配，并包含在群组声明中。

多节点部署中的会话持久性

在跨多个节点部署 Open WebUI（例如，在 Kubernetes 集群中或负载均衡器后面）时，确保会话持久性对于提供流畅的用户体验至关重要，特别是在使用 SSO 时。请在所有 Open WebUI 实例上将 WEBUI_SECRET_KEY 环境变量设置为相同且唯一的安全值。

# Example: Generate a strong secret key (e.g., using openssl rand -hex 32)
WEBUI_SECRET_KEY="YOUR_UNIQUE_AND_SECURE_SECRET_KEY"

如果此密钥在所有节点上不一致，则当用户的会话被路由到不同的节点时，他们可能被迫重新登录，因为一个节点签名的会话令牌在另一个节点上无效。默认情况下，Docker 镜像在首次启动时生成一个随机密钥，这不适用于多节点设置。

禁用标准登录表单

如果您希望仅允许通过 Okta（以及可能配置的其他 OAuth 提供商）进行登录，可以通过设置以下环境变量来禁用标准的电子邮件/密码登录表单：

ENABLE_LOGIN_FORM="false"
重要先决条件

将 ENABLE_LOGIN_FORM="false" 设置为 false 需要同时设置 ENABLE_OAUTH_SIGNUP="true"。如果您禁用登录表单而不启用 OAuth 注册，用户（包括管理员）将无法登录。在禁用标准登录表单之前，请确保至少配置了一个 OAuth 提供商并且已启用 ENABLE_OAUTH_SIGNUP。

设置这些环境变量后，请重新启动您的 Open WebUI 实例。

验证​

  1. 导航到您的 Open WebUI 登录页面。您应该会看到一个标有“使用 Okta 登录”的按钮（或者您为 OAUTH_PROVIDER_NAME 设置的名称）。
  2. 点击按钮并通过 Okta 登录流程进行身份验证。
  3. 成功通过身份验证后，您应该会被重定向回 Open WebUI 并已登录。
  4. 如果 ENABLE_OAUTH_GROUP_MANAGEMENT 为 true，请以非管理员用户身份登录。他们在 Open WebUI 中的群组现在应该严格反映他们在 Okta 中的当前群组成员资格（任何不在 Okta 声明中的群组成员资格都将被移除）。如果 ENABLE_OAUTH_GROUP_CREATION 也为 true，则用户 Okta 声明中存在但之前在 Open WebUI 中不存在的任何群组现在应该已自动创建。请注意，管理员用户的群组不会通过 SSO 自动更新。
  5. 如果您遇到问题，请查看 Open WebUI 服务器日志，查找任何与 OIDC 或群组相关的错误消息。

故障排除​

  • 400 Bad Request/重定向 URI 不匹配：仔细检查您的 Okta 应用程序中的 Sign-in redirect URI（登录重定向 URI）是否与 <您的 Open WebUI URL>/oauth/oidc/callback 完全匹配。
  • 群组未同步：验证 OAUTH_GROUP_CLAIM 环境变量是否与 Okta ID 令牌设置中配置的声明名称匹配。确保用户在群组更改后已退出并重新登录 - 更新 OIDC 需要重新走一遍登录流程。请记住管理员群组不会同步。
  • 配置错误：查看 Open WebUI 服务器日志，查找与 OIDC 配置相关的详细错误消息。
  • 请参阅官方的Open WebUI SSO 文档。
  • 查阅Okta 开发者文档。