跳至主要內容

Microsoft SSO：使用 LiteLLM 同步群組、成員

使用 LiteLLM Teams 同步 Microsoft SSO 群組、成員。



先決條件​

  • 具備管理權限的 Azure Entra ID 帳戶
  • 已在您的 Azure 入口網站中設定好的 LiteLLM Enterprise App
  • 可存取 Microsoft Entra ID（Azure AD）

本教學概覽​

  1. 在 LiteLLM Teams 上自動建立 Entra ID 群組
  2. 同步 Entra ID 團隊成員資格
  3. 為 LiteLLM 上自動建立的新團隊與使用者設定預設參數

1. 在 LiteLLM Teams 上自動建立 Entra ID 群組​

在這一步中，我們的目標是：當 Azure Entra ID 中的 LiteLLM Enterprise App 新增了群組時，讓 LiteLLM 自動在 LiteLLM DB 中建立一個新團隊。

1.1 在 Entra ID 中建立新群組​

前往 您的 Azure 入口網站 > 群組 > 新增群組。建立一個新群組。

1.2 將群組指派給您的 LiteLLM Enterprise App​

在您的 Azure 入口網站中，前往 Enterprise Applications > 選取您的 litellm app



選取您的 litellm app 後，點擊 Users and Groups > Add user/group


現在選取您在步驟 1.1 建立的群組，並將其新增至 LiteLLM Enterprise App。此時我們已將 Production LLM Evals Group 新增至 LiteLLM Enterprise App。接下來的步驟是讓 LiteLLM 在新使用者登入時，自動在 LiteLLM DB 中建立 Production LLM Evals Group。

1.3 透過 SSO 登入 LiteLLM UI​

透過 SSO 登入 LiteLLM UI。您應該會被重新導向至 Entra ID SSO 頁面。這個 SSO 登入流程會觸發 LiteLLM 從 Azure Entra ID 取得最新的群組與成員。

1.4 在 LiteLLM UI 上查看新團隊​

在 LiteLLM UI 中，前往 Teams，您應該會看到新團隊 Production LLM Evals Group 已由 LiteLLM 自動建立。

這是如何運作的​

當 SSO 使用者登入 LiteLLM 時：

  • LiteLLM 會自動擷取 LiteLLM Enterprise App 底下的群組
  • 它會找出指派給 LiteLLM Enterprise App 的 Production LLM Evals Group
  • LiteLLM 會檢查這個群組的 ID 是否存在於 LiteLLM Teams Table 中
  • 由於該 ID 不存在，LiteLLM 會自動建立一個新團隊，包含：
    • 名稱：Production LLM Evals Group
    • ID：與 Entra ID 群組的 ID 相同

2. 同步 Entra ID 團隊成員資格​

在這一步中，當 Entra ID 中的 Production LLM Evals 群組新增使用者時，LiteLLM 會自動將使用者加入 LiteLLM DB 中的 Production LLM Evals 團隊。

2.1 前往 Entra ID 中的 Production LLM Evals 群組​

前往 Entra ID 中的 Production LLM Evals 群組。

2.2 在 Entra ID 中將成員加入群組​

選取 Members > Add members

在這個階段，您應該加入您想要新增至 Production LLM Evals 團隊的使用者。

2.3 以新使用者身分登入 LiteLLM UI​

以新使用者身分登入 LiteLLM UI。您應該會被重新導向至 Entra ID SSO 頁面。這個 SSO 登入流程會觸發 LiteLLM 從 Azure Entra ID 取得最新的群組與成員。在這個步驟中，LiteLLM 會將其團隊、團隊成員與 Entra ID 中可用的內容進行同步

2.4 在 LiteLLM UI 上查看團隊成員資格​

在 LiteLLM UI 中，前往 Teams，您應該會看到新團隊 Production LLM Evals Group。由於您現在是 Entra ID 中 Production LLM Evals Group 的成員，因此您應該會在 LiteLLM UI 上看到新團隊 Production LLM Evals Group。

2.5 Azure 政府雲端（GCC High）​

預設情況下，LiteLLM 會從商業版 Microsoft Graph 端點 https://graph.microsoft.com/v1.0 同步群組成員資格。Azure Government Cloud GCC High 會從不同的主機提供 Graph，因此請設定 MICROSOFT_GRAPH_ENDPOINT，將 LiteLLM 指向主權雲端端點。

GCC High Graph endpoint
export MICROSOFT_GRAPH_ENDPOINT="https://graph.microsoft.us/v1.0"

未設定時，LiteLLM 會使用 https://graph.microsoft.com/v1.0，因此商業雲端部署不需要變更。此端點會在 SSO 登入期間用於 /me/memberOf 群組查詢，以及 Enterprise Application service principal 群組查詢。您可能也會想透過 MICROSOFT_AUTHORIZATION_ENDPOINT、MICROSOFT_TOKEN_ENDPOINT 和 MICROSOFT_USERINFO_ENDPOINT 來覆寫 GCC High 的授權、權杖與 userinfo 端點。

3. 為 LiteLLM 上自動建立的新團隊設定預設參數​

由於當 Azure Entra ID 中的 LiteLLM Enterprise App 新增群組時，litellm 會自動在 LiteLLM DB 中建立新團隊，因此我們可以為新建立的團隊設定預設參數。

這可讓您為新建立的團隊設定預設預算、模型等。

3.1 在 litellm 上設定 default_team_params​

前往您的 litellm 設定檔並設定下列參數

litellm config with default_team_params
litellm_settings:
  default_team_params:             # Applied to all /team/new calls (including SSO auto-created teams) when the field is not explicitly set
    max_budget: 100                # Optional[float]: $100 budget for the team
    budget_duration: 30d           # Optional[str]: 30 days budget_duration for the team
    models: ["gpt-5.6-luna"]      # Optional[List[str]]: models for the team (only applied to SSO auto-created teams)
    team_member_permissions:       # Optional[List[str]]: permissions granted to non-admin team members
      - "/team/daily/activity"     # Allow members to view team usage

3.2 在 LiteLLM 上自動建立新團隊​

  • 在這一步中，您應該在 Azure Entra ID 的 LiteLLM Enterprise App 新增一個新群組（就像我們在步驟 1.1 所做的）。我們將在 Azure Entra ID 中稱這個群組為 Default LiteLLM Prod Team。
  • 使用您的設定啟動 litellm proxy server
  • 透過 SSO 登入 LiteLLM UI
  • 前往 Teams，您應該會看到新團隊 Default LiteLLM Prod Team 已由 LiteLLM 自動建立
  • 請注意，LiteLLM 會為這個新團隊設定預設參數。

4. 使用 Entra ID App Roles 進行使用者權限設定​

您可以直接透過 App Roles 從 Entra ID 指派全域代理角色。LiteLLM 會在 SSO 登入期間從 JWT token 讀取 app roles，並將對應的角色指派給使用者。

4.1 支援的角色​

請使用以下其中一個全域代理角色（不區分大小寫）：

  • proxy_admin - 整個 LiteLLM 平台的管理員
  • proxy_admin_viewer - 唯讀管理員存取權（可檢視所有金鑰與支出）
  • internal_user - 標準使用者（可建立／檢視／刪除自己的金鑰，並檢視自己的支出）
  • internal_user_viewer - 唯讀標準使用者（可檢視自己的金鑰與支出）

請勿將 org_admin 用作 Entra App Role。此值會被識別並儲存為使用者的全域角色，但 Entra role claim 不會識別組織或建立組織成員資格。它本身不會授予組織管理員權限。請依照 organization access control 針對每個組織，另外將使用者加入為 org_admin。

4.2 在 Entra ID 中建立 App Roles​

  1. 前往 https://portal.azure.com/ 上的 App Registration

  2. 前往 App roles > Create app role

  3. 設定 app role：

    • Display name: Proxy Admin（或您偏好的顯示名稱）
    • Value: proxy_admin（使用上述其中一個支援的角色值）
    • Description: LiteLLM proxy 的管理員存取權
    • Allowed member types: Users/Groups

  4. 點擊 Apply 以儲存角色

4.3 將使用者指派給 App Roles​

  1. 前往 https://portal.azure.com/ 上的 Enterprise Applications
  2. 選取您的 LiteLLM 應用程式
  3. 前往 Users and groups > Add user/group
  4. 選取使用者並將其指派給您建立的其中一個 app role

4.4 測試角色指派​

  1. 以已指派 app role 的使用者身分透過 SSO 登入 LiteLLM UI
  2. LiteLLM 會自動從 JWT token 中擷取 app role
  3. 該使用者會在資料庫中被指派對應的 LiteLLM 角色
  4. 使用者的權限會反映其被指派的角色

運作方式：

  • 當使用者透過 Microsoft SSO 登入時，LiteLLM 會從 JWT id_token 中擷取 roles 或 app_roles claim
  • 如果任何角色符合有效的 LiteLLM 角色（不區分大小寫），系統就會將該角色指派給使用者
  • 如果存在多個支援的全域角色，LiteLLM 會選擇權限最高的角色：proxy_admin、proxy_admin_viewer、internal_user，然後是 internal_user_viewer
  • 此角色指派會持續保存在 LiteLLM 資料庫中，並決定使用者的存取層級

影片逐步說明​

此內容說明如何設定 sso 自動新增以支援 Microsoft Entra ID

請跟著這段影片了解如何使用 Microsoft Entra ID 設定此功能

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