🔗 Okta OIDC SSO 集成

注意

本教程为社区贡献，Open WebUI 团队不提供官方支持。它仅作为如何针对您的特定使用场景自定义 Open WebUI 的演示。想要贡献？请查看贡献教程。

概述

本操作文档概述了将 Okta OIDC 单点登录 (SSO) 与 Open WebUI 集成所需的步骤。它还涵盖了基于 Okta 群组成员身份管理 Open WebUI 用户群组的可选功能，包括即时 (Just-in-Time, 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 的现有应用程序。

   

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 时将需要它们。

   

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

2. 向 ID Token 添加群组声明

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

1. 在管理控制台 (Admin Console) 中，前往 Applications > Applications 并选择您的 OIDC 客户端应用。
2. 前往 Sign On 选项卡，然后在 OpenID Connect ID Token 部分中点击 Edit。
3. 在 Group claim type 部分，选择 Filter。
4. 在 Group claims filter 部分：
   • 输入 groups as the claim name (or use the default if present).
   • 从下拉菜单中选择 Matches regex。
   • 在 regex 字段中输入 .*。这将包含该用户所属的所有群组。如果需要，您可以使用更具体的正则表达式。
5. 点击 Save。
6. 点击 Back to applications 链接。
7. 在您的应用程序的 More 按钮下拉菜单中，点击 Refresh Application Data。

有关更高级的群组声明配置，请参阅关于自定义 token和群组函数的 Okta 文档。

3. 应用 MFA（例如 Google Authenticator）

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

1. 配置 Authenticator：

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

2. 创建并应用 Sign-On 策略：

   • 前往 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"。
     • 确保在 "AND Possession factor constraints are" 下包含了您期望的因素（例如 Google Authenticator）。
   • 最后，将此策略分配给您的 Open WebUI 应用程序。前往 Applications > Applications，选择您的 OIDC 应用，然后在 Sign On 选项卡下，选择您创建的策略。

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

重新认证频率

默认情况下，为了提高用户体验，Okta 的 Sign-On 策略可能不会在来自同一设备或浏览器的每次登录时都提示进行 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"

# 登录按钮上显示的名称（例如 “Login with Okta”）
OAUTH_PROVIDER_NAME="Okta"

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

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

# 仅当您在 Okta 中配置了 Groups Claim 时才设置为 “true”（步骤 2）
# 并且希望在登录时根据 Okta 群组来管理 Open WebUI 群组。
# 这将同步现有群组。用户将被添加/移出 Open WebUI 群组
# 以匹配其 Okta 群组声明。
# ENABLE_OAUTH_GROUP_MANAGEMENT="true"

# 仅在 ENABLE_OAUTH_GROUP_MANAGEMENT 为 true 时需要。
# ID token 中包含群组信息的声明名称（必须与 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）。

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

群组成员管理

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

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

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

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

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

# 示例：生成强安全密钥（例如使用 openssl rand -hex 32）
WEBUI_SECRET_KEY="YOUR_UNIQUE_AND_SECURE_SECRET_KEY"

如果此密钥在所有节点之间不一致，那么当用户的会话被路由到不同的节点时，用户可能会被迫重新登录，因为由一个节点签名的会话 token 在另一个节点上将无效。默认情况下，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 登录页面。您应该会看到一个标有 “Login with 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/Redirect URI Mismatch： 仔细检查您的 Okta 应用程序中的 Sign-in redirect URI 是否与 <your-open-webui-url>/oauth/oidc/callback 完全匹配。

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

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

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

• 咨询 Okta 开发者文档。