跳至主要內容

✨ 管理 UI 的 SSO

資訊

自 v1.76.0 起，SSO 對最多 5 位使用者免費。

資訊

✨ SSO 適用於 LiteLLM Enterprise

Enterprise 定價

取得免費 7 天試用金鑰

用法（Google、Microsoft、Okta 等）​

影片導覽​

步驟 1：在 Okta 中建立 OIDC 應用程式​

在您的 Okta 管理主控台中，建立新的 OIDC Web Application。如需詳細操作說明，請參閱 Okta 關於建立 OIDC app integrations 的指南。

設定應用程式時：

  • 登入重新導向 URI：https://<your-proxy-base-url>/sso/callback
  • 登出重新導向 URI（選用）：https://<your-proxy-base-url>

建立 app 後，請從應用程式的 General 分頁複製您的 Client ID 和 Client Secret：

步驟 2：將使用者指派給應用程式​

請確認使用者已在 Assignments 分頁中指派到 app。如果已啟用 Federation Broker Mode，您可能需要先停用它，才能手動指派使用者。

步驟 3：設定環境變數​

設定下列環境變數。兩個 Okta authorization server 之間唯一的差異在於端點 URL：

Org Authorization Server（適用於所有 Okta 方案，無需額外 SKU）：

GENERIC_CLIENT_ID="<your-client-id>"
GENERIC_CLIENT_SECRET="<your-client-secret>"
GENERIC_AUTHORIZATION_ENDPOINT="https://<your-okta-domain>/oauth2/v1/authorize"
GENERIC_TOKEN_ENDPOINT="https://<your-okta-domain>/oauth2/v1/token"
GENERIC_USERINFO_ENDPOINT="https://<your-okta-domain>/oauth2/v1/userinfo"
PROXY_BASE_URL="https://<your-proxy-base-url>"

Custom Authorization Server（需要 Okta API Access Management SKU）：

GENERIC_CLIENT_ID="<your-client-id>"
GENERIC_CLIENT_SECRET="<your-client-secret>"
GENERIC_AUTHORIZATION_ENDPOINT="https://<your-okta-domain>/oauth2/default/v1/authorize"
GENERIC_TOKEN_ENDPOINT="https://<your-okta-domain>/oauth2/default/v1/token"
GENERIC_USERINFO_ENDPOINT="https://<your-okta-domain>/oauth2/default/v1/userinfo"
PROXY_BASE_URL="https://<your-proxy-base-url>"
提示

您可以在 https://<your-okta-domain>/.well-known/openid-configuration 找到所有 OAuth 端點

步驟 3a：設定 Access Policy（僅限 Custom Authorization Server）​

如果您使用的是 Custom Authorization Server，則必須設定 Access Policy。若未設定，使用者將會收到 no_matching_policy 錯誤。如果您使用的是 Org Authorization Server，請略過此步驟。

  1. 前往 Security → API
  1. 選取 default authorization server（或您的自訂 server）
  1. 點擊 Access Policies 分頁，建立一個指派給您的 LiteLLM app 的新 policy
  2. 新增一條允許 Authorization Code grant type 的規則

更多詳細資訊請參閱 Okta 的 Access Policy 文件。

步驟 4：設定 Okta 安全性設定​

建議為 Okta 使用 GENERIC_CLIENT_STATE 以防止 CSRF 攻擊：

GENERIC_CLIENT_STATE="random-string"

PKCE（Proof Key for Code Exchange） — 如果您的 Okta 應用程式設定為需要 PKCE，請透過設定以下項目啟用：

GENERIC_CLIENT_USE_PKCE="true"

LiteLLM 會在 OAuth flow 期間自動處理 PKCE 參數的產生與驗證。

步驟 5：測試 SSO flow​

  1. 啟動您的 LiteLLM proxy
  2. 前往 https://<your-proxy-base-url>/ui
  3. 點擊 SSO 登入按鈕
  4. 使用 Okta 驗證，並確認您已重新導向回 LiteLLM

疑難排解​

錯誤原因解決方法
redirect_uri error未設定 Redirect URI在 Okta 的 Sign-in redirect URIs 中新增 <proxy_base_url>/sso/callback
access_denied使用者未指派給 app在 Assignments 分頁中指派該使用者
no_matching_policy缺少 Access Policy（僅限 Custom Authorization Server）在 Authorization Server 中建立 Access Policy（請參閱步驟 3a）

預設登入、登出 URL​

某些 SSO 提供者需要特定的登入與登出 redirect url。您可以輸入以下值。

  • Login: <your-proxy-base-url>/sso/key/generate
  • Logout: <your-proxy-base-url>

以下是要在 proxy 上設定登出 url 的環境變數

PROXY_LOGOUT_URL="https://www.google.com"

步驟 3. 在您的 .env 中設定 PROXY_BASE_URL​

請將此設定於您的 .env（如此 proxy 才能設定正確的 redirect url）

PROXY_BASE_URL=https://litellm-api.up.railway.app

步驟 4. 測試流程​

限制 SSO 下的電子郵件子網域​

如果您使用 SSO，並且只想允許具有特定子網域的使用者——例如（@berri.ai 電子郵件帳號）——存取 UI，請這樣做：

export ALLOWED_EMAIL_DOMAINS="berri.ai"

這會先檢查從 SSO 收到的使用者 email 是否包含此網域，然後才允許存取。

設定 Proxy Admin​

在啟用 SSO 時設定 Proxy Admin。啟用 SSO 後，使用者的 user_id 會從 SSO 提供者取得。若要設定 Proxy Admin，您需要從 UI 複製 user_id，並將它設定到您的 .env 中，作為 PROXY_ADMIN_ID。

步驟 1：從 UI 複製您的 ID​

步驟 2：在您的 .env 中將其設定為 PROXY_ADMIN_ID​

export PROXY_ADMIN_ID="116544810872468347480"

這會將 LiteLLM_UserTable 中的使用者角色更新為 proxy_admin。

如果您打算變更此 ID，請透過 API /user/update 或 UI（Internal Users 頁面）更新使用者角色。

步驟 3：查看所有 proxy keys​

資訊

如果您沒有看到所有 keys，這可能是因為快取的 token。只要重新登入即可恢復正常。

在 Admin UI 上停用 Default Team​

如果您想在 Admin UI 上隱藏 Default Team，請使用這個設定

將套用以下邏輯

  • 如果已指派 team，則不顯示 Default Team
  • 如果未指派 team，則應該顯示 Default Team

在您的 litellm config.yaml 中設定 default_team_disabled: true

general_settings:
  master_key: sk-1234
  default_team_disabled: true # OR you can set env var PROXY_DEFAULT_TEAM_DISABLED="true"

在 SSO 開啟時使用 Username、Password​

如果您需要在 SSO 開啟時透過 username/password 存取 UI，請前往 /fallback/login。此路由將允許您使用 username/password 憑證登入。

限制 UI 存取​

您可以將 UI 存取限制為僅管理員——包含您（proxy_admin）以及您授予僅檢視存取權的人（proxy_admin_viewer），以查看 global spend。

步驟 1. 設定 'admin_only' 存取

general_settings:
    ui_access_mode: "admin_only"

步驟 2. 邀請僅檢視使用者

自訂品牌 Admin UI​

在 LiteLLM Admin UI 上使用您公司的自訂品牌識別 我們允許您：

  • 自訂 UI Logo
  • 自訂 UI 色彩配置

我們允許您傳入本機圖片或您的圖片之 http/https url

在您的 env 中設定 UI_LOGO_PATH。我們建議使用託管圖片，這樣設定與設定 / 除錯會容易很多

託管圖片的設定範例

UI_LOGO_PATH="https://litellm-logo-aws-marketplace.s3.us-west-2.amazonaws.com/berriai-logo-github.png"

本機圖片的設定範例（在您的容器內）

UI_LOGO_PATH="ui_images/logo.jpg"

或直接從 Admin UI 設定您的 logo：​

設定自訂色彩主題​

{
    "brand": {
      "DEFAULT": "teal",
      "faint": "teal",
      "muted": "teal",
      "subtle": "teal",
      "emphasis": "teal",
      "inverted": "teal"
    }
}

  • 部署 LiteLLM Proxy Server

疑難排解​

"The 'redirect_uri' parameter must be a Login redirect URI in the client app settings" 錯誤​

當 redirect URI 設定不正確時，這個錯誤常見於 Okta 和其他 SSO 提供者。

問題​

Your request resulted in an error. The 'redirect_uri' parameter must be a Login redirect URI in the client app settings

解決方案​

1. 確認您已在 .env 中設定 PROXY_BASE_URL 且包含 protocol

請確認您的 PROXY_BASE_URL 包含完整的 URL 與 protocol（http:// 或 https://）：

# ✅ Correct - includes https://
PROXY_BASE_URL=https://litellm.platform.com

# ✅ Correct - includes http://
PROXY_BASE_URL=http://litellm.platform.com

# ❌ Incorrect - missing protocol
PROXY_BASE_URL=litellm.platform.com

2. 針對 Okta，請確認已設定 GENERIC_CLIENT_STATE，且如有需要已設定 PKCE

請參閱 Okta SSO — 步驟 4：設定 Okta 安全性設定 以了解 GENERIC_CLIENT_STATE 與 PKCE 設定的詳細資訊。

常見設定問題​

Base URL 中缺少 Protocol​

# This will cause redirect_uri errors
PROXY_BASE_URL=mydomain.com

# Fix: Add the protocol
PROXY_BASE_URL=https://mydomain.com

備援登入​

如果您需要在 SSO 開啟時透過 username/password 存取 UI，請前往 /fallback/login。此路由將允許您使用 username/password 憑證登入。

偵錯 SSO JWT 欄位​

如果您需要檢查 LiteLLM 從您的 SSO 提供者收到的 JWT 欄位，請依照以下說明。本指南將帶您設定一個 debug callback，以便在 SSO 流程期間檢視 JWT 資料。


  1. 在您的 SSO 提供者中新增 /sso/debug/callback 作為 redirect URL

在您的 SSO 提供者設定中，新增以下 URL 作為新的 redirect（callback）URL：

Redirect URL
http://<proxy_base_url>/sso/debug/callback

  1. 在瀏覽器中前往 debug 登入頁面

    在您的瀏覽器中前往以下 URL：

    URL to navigate to
    https://<proxy_base_url>/sso/debug/login

    這將啟動標準的 SSO 流程。您將被重新導向至 SSO 提供者的登入畫面，並在成功驗證後，被重新導向回 LiteLLM 的 debug callback 路由。

  2. 檢視 JWT 欄位

重新導向後，您應該會看到名為 "SSO Debug Information" 的頁面。此頁面會顯示從您的 SSO 提供者收到的 JWT 欄位（如上圖所示）

進階​

透過 Azure App Roles 管理使用者角色​

在 Azure Entra ID 中定義使用者權限，以集中管理角色。使用者登入時，LiteLLM 會根據您的 Azure 設定自動指派角色——不需要在 LiteLLM 中手動管理角色。

步驟 1：在 Azure App Registration 上建立 App Roles​

  1. 前往您在 https://portal.azure.com/ 上的 App Registration
  2. 前往 App roles > Create app role
  3. 使用 支援的 LiteLLM 角色 之一來設定 app role：
    • Display name：Admin Viewer（或您偏好的顯示名稱）
    • Value：proxy_admin_viewer（必須與其中一個 LiteLLM role value 完全一致）
  4. 點擊 Apply 以儲存角色
  5. 對您要使用的每個 LiteLLM 角色重複上述步驟

支援的 LiteLLM role values（請參閱 完整角色文件）：

  • proxy_admin - 完整管理員存取權
  • proxy_admin_viewer - 唯讀管理員存取權
  • internal_user - 可建立／檢視／刪除自己的 keys
  • internal_user_viewer - 可檢視自己的 keys（唯讀）

步驟 2：將使用者指派給應用程式角色​

  1. 前往 https://portal.azure.com/ 的 Enterprise Applications
  2. 選取您的 LiteLLM 應用程式
  3. 前往 Users and groups > Add user/group
  4. 選取使用者
  5. 在 Select a role 下，選擇您建立的應用程式角色（例如，proxy_admin_viewer）
  6. 點擊 Assign 以儲存

步驟 3：登入並驗證​

  1. 透過 SSO 登入 LiteLLM UI
  2. LiteLLM 會自動從 JWT token 擷取應用程式角色
  3. 使用者將被指派對應的角色（您可以在 UI 中透過檢查使用者個人資料下拉選單來驗證）

注意： 來自 Entra ID 的角色將優先於 LiteLLM 資料庫中的任何現有角色。這可確保您的 SSO 提供者是使用者角色的權威來源。

🚅
LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →