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 应用程序并设置组声明以将组信息传递给 Open WebUI。

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

  1. 登录到您的 Okta 管理控制台。
  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 令牌​

（可选） 要在 Open WebUI 中基于 Okta 组启用自动组管理，您需要配置 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 关于自定义令牌和组函数的文档。

配置 Open WebUI​

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

# --- OIDC 核心设置 ---
# 如果您希望用户能够通过 Okta 创建账户，请启用 OAuth 注册
# ENABLE_OAUTH_SIGNUP="true"

# 您的 Okta 应用程序的客户端 ID
OAUTH_CLIENT_ID="YOUR_OKTA_CLIENT_ID"

# 您的 Okta 应用程序的客户端密钥
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）时设置为 "true"
# 并且希望在登录时基于 Okta 组管理 Open WebUI 组。
# 这同步现有组。用户将被添加/移除到 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）。

要还启用存在于 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 中正确配置和分配，并包含在组声明中。

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

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

# 示例：生成强密钥（例如，使用 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 Bad Request/重定向 URI 不匹配： 仔细检查您的 Okta 应用程序中的 Sign-in redirect URI 是否完全匹配 <your-open-webui-url>/oauth/oidc/callback。
  • 组未同步： 验证 OAUTH_GROUP_CLAIM 环境变量是否与 Okta ID 令牌设置中配置的声明名称匹配。确保用户在组更改后已注销并重新登录 - 需要登录流程来更新 OIDC。请记住管理员组不会同步。
  • 配置错误： 查看 Open WebUI 服务器日志以获取与 OIDC 配置相关的详细错误消息。
  • 参考官方 Open WebUI SSO 文档。
  • 查阅 Okta 开发者文档。