本教程為社群貢獻,未經 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 中的相關群組。如果您也啟用了即時群組創建 (ENABLE_OAUTH_GROUP_CREATION
),在 Okta 聲明中存在但 Open WebUI 中缺失的群組將在登入時自動創建。
先決條件
- 新建或現有的 Open WebUI 實例。
- 具備創建和配置應用程式管理權限的 Okta 帳戶。
- 了解 OIDC、Okta 應用程式配置和 Open WebUI 環境變數的基本知識。
配置 Okta
首先,您需要在 Okta 組織中配置 OIDC 應用程式,並設置群組聲明以將群組資訊傳遞給 Open WebUI。
1. 在 Okta 中創建/配置 OIDC 應用程式
- 登錄您的 Okta 管理控制台。
- 導航至 Applications > Applications。
- 創建新的 OIDC - OpenID Connect 應用程式(選擇 Web Application 作為類型),或選擇您希望用於 Open WebUI 的現有應用程式。
- 在設置過程中或應用程式的 General 設置頁面中,配置 Sign-in redirect URIs。新增您的 Open WebUI 實例的 URI,後接
/oauth/oidc/callback
。例如:https://your-open-webui.com/oauth/oidc/callback
。 - 記下應用程式 General 頁面上提供的 Client ID 和 Client secret。這些將用於配置 Open WebUI。
- 確保在 Assignments 頁面中正確分配了該應用程式的使用者或群組。
2. 向 ID Token 添加群組聲明
(可選) 若要根據 Okta 群組啟用 Open WebUI 的自動群組管理,您需要配置 Okta 將使用者的群 組成員資格發送到 ID token。如果您僅需要 SSO 登入,並希望在 Open WebUI 內手動管理群組,可跳過本節。
- 在管理控制台中,轉到 Applications > Applications,選擇您的 OIDC 客戶端應用程式。
- 轉到 Sign On 頁面,在 OpenID Connect ID Token 部分點擊 Edit。
- 在 Group claim type 部分,選擇 Filter。
- 在 Group claims filter 部分:
- 輸入
groups
作為聲明名稱(或使用預設值,如果已存在)。 - 下拉選單中選擇 Matches regex。
- 在正則表示式欄位中輸入
.*
。這將包含用戶所屬的所有群組。如有需要,可以使用更具針對性的正則表示式。
- 輸入
- 點擊 Save。
- 點擊 Back to applications 連結。
- 在應用程式的 More 按鈕下拉菜單中,點選 Refresh Application Data。
如需更高階的群組聲明配置,請參閱 Okta 關於自定義 Token 和 群組功能 的文件。
配置 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"
# 請求的範圍 (預設通常足夠)
# 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 token 中包含群組信息的聲明名稱(必須與 Okta 配置匹配)
# OAUTH_GROUP_CLAIM="groups"
# 可選:啟用即時創建(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
)。
要同時啟用來自 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(單點登錄)時。將 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 實例。
核驗
- 瀏覽到您的 Open WebUI 登錄頁面。您應該會看到一個標記為"通過 Okta 登錄"(或您為
OAUTH_PROVIDER_NAME
設置的其他名稱)的按鈕。 - 點擊按鈕並通過 Okta 登錄流程進行身份驗證。
- 驗證成功後,您應該會重新定向回 Open WebUI 並登錄。
- 如果
ENABLE_OAUTH_GROUP_MANAGEMENT
為 true,以非管理用戶身份登錄。他們在 Open WebUI 中的群組應嚴格反映其當前在 Okta 中的群組成員身份(任何在 Okta 聲明中未出現的群組的成員身份將被移除)。如果ENABLE_OAUTH_GROUP_CREATION
也為 true,用戶在 Okta 聲明中的任何群組如果之前未出現在 Open WebUI 中現在應該已自動創建。請注意,管理員用戶的群組不會通過 SSO 自動更新。 - 如果遇到問題,請檢查 Open WebUI 伺服器日誌是否有任何與 OIDC 或群組相關的錯誤。
故障排除
- 400 壞請求/重定向 URI 不匹配:請仔細檢查您的 Okta 應用中的登錄重定向 URI是否與
<your-open-webui-url>/oauth/oidc/callback
完全匹配。 - **群組未同步:**驗證
OAUTH_GROUP_CLAIM
環境變量是否與 Okta ID Token 設置中配置的聲明名稱匹配。確保用戶在群組更改後登出並重新登錄——需要一個登錄流程來更新 OIDC。請記住管理員群組不會同步。 - 配置錯誤: 檢查 Open WebUI 伺服器日誌以獲取與 OIDC 配置相關的詳細錯誤訊息。
- 參考官方的 Open WebUI SSO 文檔。
- 諮詢 Okta 開發者文檔。