跳到主要内容
警告

本教程由社区贡献，不获得 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. 导航到应用程序 > 应用程序。

  3. 要么创建一个新的OIDC - OpenID Connect应用程序（选择Web 应用程序作为类型），要么选择一个您希望用于 Open WebUI 的现有应用程序。

    Okta Create App

  4. 在设置期间或应用程序的通用设置选项卡中，配置登录重定向 URI。添加您的 Open WebUI 实例的 URI，后跟/oauth/oidc/callback。示例：https://your-open-webui.com/oauth/oidc/callback。

  5. 记下应用程序通用选项卡上提供的客户端 ID和客户端密钥。您将需要这些信息进行 Open WebUI 配置。

    Okta Client Key

  6. 确保在分配选项卡下将正确的用户或群组分配给此应用程序。

2. 将群组声明添加到 ID 令牌​

（可选）要根据 Okta 群组在 Open WebUI 中启用自动群组管理，您需要配置 Okta 以在 ID 令牌中发送用户的群组会员资格。如果您只需要 SSO 登录并更喜欢在 Open WebUI 中手动管理群组，则可以跳过此部分。

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

如需更高级的群组声明配置，请参阅 Okta 关于自定义令牌和群组功能的文档。

3. 应用 MFA（例如，Google Authenticator）​

为了增强安全性，您可以对通过 Okta 登录 Open WebUI 的用户强制执行多因素身份验证 (MFA)。本示例演示了如何将 Google Authenticator 设置为附加因素。

  1. 配置身份验证器:

    • 在 Okta 管理控制台中，导航到安全 > 身份验证器。
    • 点击添加身份验证器并添加Google Authenticator。
    • 在设置期间，您可以将“用户验证”设置为“必需”以增强安全性。

  2. 创建并应用登录策略:

    • 转到安全 > 身份验证器，然后点击登录选项卡。
    • 点击添加策略以创建新策略（例如，“WebUI MFA 策略”）。
    • 在您刚刚创建的策略中，点击添加规则。
    • 配置规则
      • 将“如果用户 IP 是”设置为“任意位置”。
      • 将“则访问是”设置为“成功身份验证后允许”。
      • 在“并且用户必须使用”下，选择“密码 + 另一个因素”。
      • 确保您的所需因素（例如，Google Authenticator）包含在“并且拥有因素限制是”下。
    • 最后，将此策略分配给您的 Open WebUI 应用程序。转到应用程序 > 应用程序，选择您的 OIDC 应用程序，然后在登录选项卡下，选择您创建的策略。

现在，当用户登录 Open WebUI 时，他们将被要求提供其 Okta 密码和 Google Authenticator 的附加验证码。

重新身份验证频率

默认情况下，Okta 的登录策略可能不会在每次从同一设备或浏览器登录时提示 MFA，以改善用户体验。如果您要求每个会话都进行 MFA，您可以在您创建的策略规则中调整此设置。查找“提示重新身份验证”设置，并将其设置为“每次登录尝试”。

配置 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）。

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

群组会员资格管理

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

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

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

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

当跨多个节点（例如，在 Kubernetes 集群中或负载均衡器后）部署 Open WebUI 时，确保会话持久性对于提供无缝的用户体验至关重要，尤其是在 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"设置为需要同时设置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 错误请求/重定向 URI 不匹配：仔细检查 Okta 应用程序中的登录重定向 URI是否与<您的 Open WebUI URL>/oauth/oidc/callback完全匹配。

  • 群组未同步：验证OAUTH_GROUP_CLAIM环境变量是否与 Okta ID 令牌设置中配置的声明名称匹配。确保用户在群组更改后已注销并重新登录 - 需要登录流程才能更新 OIDC。请记住，管理员群组不会同步。

  • 配置错误：查看 Open WebUI 服务器日志以获取与 OIDC 配置相关的详细错误消息。

  • 请参阅官方Open WebUI SSO 文档。

  • 查阅Okta 开发者文档。