Skip to main content
warning

本教程由社区贡献，不属于 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 应用程序，并设置一个组声明 (groups claim) 以将组信息传递给 Open WebUI。

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

  1. 登录您的 Okta 管理控制台 (Admin Console)。

  2. 导航至 Applications > Applications。

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

    Okta 创建应用

  4. 在设置过程中或在应用程序的 General 设置选项卡中，配置 Sign-in redirect URIs。添加 Open WebUI 实例的 URI，后跟 /oauth/oidc/callback。例如：https://your-open-webui.com/oauth/oidc/callback。

  5. 记下应用程序 General 选项卡上提供的 Client ID 和 Client secret。您在配置 Open WebUI 时将需要这些信息。

    Okta 客户端密钥

  6. 确保在 Assignments 选项卡下为该应用程序分配了正确的用户或组。

2. 向 ID 令牌添加组声明 (Groups Claim)​

(可选) 要启用基于 Okta 组在 Open WebUI 中进行自动组管理，您需要配置 Okta 以在 ID 令牌中发送用户的组成员身份。如果您只需要 SSO 登录并更愿意在 Open WebUI 中手动管理组，可以跳过此部分。

  1. 在管理控制台中，转到 Applications > Applications 并选择您的 OIDC 客户端应用。
  2. 转到 Sign On 选项卡，点击 OpenID Connect ID Token 部分中的 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 关于自定义令牌和组函数的文档。

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

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

  1. 配置验证器 (Authenticator)：

    • 在 Okta 管理控制台中，导航至 Security > Authenticators。
    • 点击 Add Authenticator 并添加 Google Authenticator。
    • 在设置过程中，您可以将 "User verification" 设置为 "Required" 以增强安全性。

  2. 创建并应用登录策略 (Sign-On Policy)：

    • 转到 Security > Authenticators，然后点击 Sign On 选项卡。
    • 点击 Add a policy 以创建新策略（例如 "WebUI MFA Policy"）。
    • 在刚刚创建的策略中，点击 Add rule。
    • 配置规则：
      • 将 "IF User's IP is" 设置为 "Anywhere"。
      • 将 "THEN Access is" 设置为 "Allowed after successful authentication"。
      • 在 "AND User must authenticate with" 下，选择 "Password + Another factor"。
      • 确保您想要的因素（例如 Google Authenticator）包含在 "AND Possession factor constraints are" 下。
    • 最后，将此策略分配给您的 Open WebUI 应用程序。转到 Applications > Applications，选择您的 OIDC 应用，并在 Sign On 选项卡下选择您创建的策略。

现在，当用户登录 Open WebUI 时，他们将被要求提供 Okta 密码以及来自 Google Authenticator 的额外验证码。

note

重新认证频率 默认情况下，Okta 的登录策略可能不会在每次从同一设备或浏览器登录时都提示 MFA，以改善用户体验。如果您要求每个会话都进行 MFA，可以在创建的策略规则中调整此设置。查找 "Prompt for re-authentication" 设置并将其设置为 "Every sign-in attempt"。

配置 Open WebUI​

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


# --- OIDC 核心设置 ---

# 如果您希望用户能够通过 Okta 创建帐户，请启用 OAuth 注册
# ENABLE_OAUTH_SIGNUP="true"

# 您的 Okta 应用程序的 Client ID
OAUTH_CLIENT_ID="YOUR_OKTA_CLIENT_ID"

# 您的 Okta 应用程序的 Client Secret
OAUTH_CLIENT_SECRET="YOUR_OKTA_CLIENT_SECRET"

# 您的 Okta 组织的 OIDC 发现 URL
# 格式：https://<your-okta-domain>/.well-known/openid-configuration
# 或者对于特定的授权服务器：https://<your-okta-domain>/oauth2/<auth-server-id>/.well-known/openid-configuration
OPENID_PROVIDER_URL="YOUR_OKTA_OIDC_DISCOVERY_URL"

# 登录按钮上显示的名称（例如 "使用 Okta 登录"）
OAUTH_PROVIDER_NAME="Okta"

# 要请求的作用域（默认通常足够）
# OAUTH_SCOPES="openid email profile groups" # 如果不是默认值，请确保包含 'groups'

# --- OAuth 组管理（可选） ---

# 仅当您在 Okta 中配置了组声明（第 2 步）
# 并且希望在登录时根据 Okta 组管理 Open WebUI 组时，才设置为 "true"。
# 这将同步现有组。用户将被添加到 Open WebUI 组或从中移除，
# 以匹配其 Okta 组声明。
# ENABLE_OAUTH_GROUP_MANAGEMENT="true"

# 仅当 ENABLE_OAUTH_GROUP_MANAGEMENT 为 true 时才需要。
# ID 令牌中包含组信息的声明名称（必须与 Okta 配置匹配）
# OAUTH_GROUP_CLAIM="groups"

# 可选：如果组在 Okta 声明中存在但在 Open WebUI 中不存在，则启用即时 (JIT) 创建组。
# 需要 ENABLE_OAUTH_GROUP_MANAGEMENT="true"。
# 如果设置为 false（默认），则仅同步现有组。
# 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。

warning

组成员身份管理 当 ENABLE_OAUTH_GROUP_MANAGEMENT 设置为 true 时，用户的 Open WebUI 组成员身份将在每次登录时与从其 Okta 声明中接收到的组严格同步。这意味着：

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

请确保在 Okta 中正确配置并分配了所有必要的组，并将其包含在组声明中。

info

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

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


# 示例：生成一个强大的密钥（例如使用 openssl rand -hex 32）
WEBUI_SECRET_KEY="YOUR_UNIQUE_AND_SECURE_SECRET_KEY"

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

tip

禁用标准登录表单

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

ENABLE_LOGIN_FORM="false"
danger

重要前提条件 将 ENABLE_LOGIN_FORM="false" 需要同时设置 ENABLE_OAUTH_SIGNUP="true"。如果您在未启用 OAuth 注册的情况下禁用登录表单，用户（包括管理员）将无法登录。 在禁用标准登录表单之前，请确保至少配置了一个 OAuth 提供程序并启用了 ENABLE_OAUTH_SIGNUP。