本教程是社区贡献,不受 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 应用
- 登录到您的 Okta 管理控制台。
- 导航到 应用 > 应用。
- 创建一个新的 OIDC - OpenID Connect 应用(选择 Web 应用 作为类型)或选择现有应用以用于 Open WebUI。
- 在设置期间或在应用的常规设置选项卡中,配置登录重定向 URI。添加您的 Open WebUI 实例的 URI,后面加上
/oauth/oidc/callback
。示例:https://your-open-webui.com/oauth/oidc/callback
。 - 记录应用常规选项卡中提供的客户端 ID和客户端密钥。您将在 Open WebUI 配置中使用这些信息。
- 确保在分配选项卡下,将正确的用户或组分配给此应用。
2. 向 ID 令牌添加组声明
(可选) 为了在 Open WebUI 中根据 Okta 组自动管理组,您需要配置 Okta 以在 ID 令牌中发送用户的组成员信息。如果您只需要 SSO 登录并希望在 Open WebUI 中手动管理组,可以跳过此部分。
- 在管理控制台,转到 应用 > 应用,并选择您的 OIDC 客户端应用。
- 转到登录选项卡,并在OpenID Connect ID Token部分点击编辑。
- 在组声明类型部分,选择过滤器。
- 在组声明过滤器部分:
- 输入
groups
作为声明名称(或使用默认值)。 - 在下拉菜单中选择匹配正则。
- 在正则字段中输入
.*
。这将包括用户所属的所有组。如果需要,可以使用更具体的正则。
- 输入
- 点击保存。
- 点击返回到应用链接。
- 在应用的更多按钮下拉菜单中,点击 刷新应用数据。
有关更高级的组声明配置,参考 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"
# 可选功能:启用 Just-in-Time (JIT) 创建,如果 Okta 声明中存在但 Open WebUI 中不存在这些组。
# 需要 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
)。
如果还