跳至主要內容

✨ 管理 UI 的 SSO

企業版功能

SSO需要 LiteLLM 企業版授權。立即開始 30 天免費試用或預約展示。 查看企業版完整功能。

自 v1.76.0 起，SSO 對最多 5 位使用者免費。超過後則需要企業授權。

用法（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://your-proxy-domain.com

步驟 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。只要重新登入即可恢復正常。

自動將 SSO 使用者加入團隊（OIDC）​

對於 OIDC 提供者（Okta、Google、Generic SSO），您可以將身分提供者傳回的 token 中某個宣告，帶入使用者的 team_ids。每次 SSO 登入時，LiteLLM 會讀取該宣告，並將使用者加入每個符合的團隊成員。

步驟 1：將 LiteLLM 指向包含團隊 ID 的宣告​

config.yaml
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  litellm_jwtauth:
    team_ids_jwt_field: "groups" # any claim; dot notation works for nested claims, e.g. "resource_access.myapp.groups"

這假設來自您提供者的 token 會像這樣：

{
  ...,
  "groups": ["team_id_1", "team_id_2"]
}

如果您不確定提供者傳送了什麼，請使用 SSO debug 流程 檢查收到的宣告。

步驟 2：在 LiteLLM 上建立團隊​

宣告值必須與 LiteLLM 上已存在團隊的 team_id 相符。OIDC 宣告不會自動建立團隊，且沒有對應團隊的宣告值會被略過。

Create team with team_id matching the SSO group value
curl -X POST '<PROXY_BASE_URL>/team/new' \
-H 'Authorization: Bearer <PROXY_MASTER_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "team_alias": "team_1",
    "team_id": "team_id_1"
}'

步驟 3：測試 SSO 流程​

透過 SSO 登入，並在 UI（Internal Users 頁面）上驗證使用者的團隊成員資格。這裡有一個 影片導覽。

某些提供者只會在 access token 中包含 groups 宣告，而不會在 userinfo 回應中包含。在這種情況下，請透過 ui_access_mode 設定該宣告，這也會解碼 access token。請注意，此格式也會將 UI 登入限制為指定群組的成員：

config.yaml
general_settings:
  ui_access_mode:
    type: "restricted_sso_group"
    restricted_sso_group: "<group required for UI access>"
    sso_group_jwt_field: "groups"

對於 Microsoft Entra ID，群組成員資格則改由 Microsoft Graph API 讀取；請依照 此教學。對於 SAML，團隊 ID 來自 assertion 屬性；請參閱 SAML SSO。

限制建立個人金鑰​

如果您想阻止使用者建立個人金鑰（沒有團隊的金鑰），請使用此功能。這會在 /key/generate 上強制執行，因此同時適用於 Admin UI 與直接 API 呼叫

在您的 litellm config.yaml 中設定 key_generation_settings

litellm_settings:
  key_generation_settings:
    personal_key_generation:
      allowed_user_roles: ["proxy_admin"]

所有選項請參閱 限制金鑰產生

在 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. 在 proxy 上啟用 debug 路由

debug 路由預設為停用，並會回傳 404。設定下列環境變數並重新啟動 proxy（除錯完成後請再取消設定）：

Environment variable
ENABLE_SSO_DEBUG="true"
  1. 在您的 SSO 提供者中將 /sso/debug/callback 加入為重新導向 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 路由。

  1. 檢視 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、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →