Microsoft SSO: Groups, Members를 LiteLLM과 동기화

Microsoft SSO Groups, Members를 LiteLLM Teams와 동기화해 봐요.

전제 조건

관리자 권한이 있는 Azure Entra ID 계정
Azure Portal에 설정된 LiteLLM Enterprise App
Microsoft Entra ID(Azure AD) 접근

이 튜토리얼의 개요

Entra ID Groups를 LiteLLM Teams에 자동 생성
Entra ID 팀 구성원(membership) 동기화
LiteLLM에 자동 생성되는 새 팀과 사용자에 대한 기본 params 설정

1. Entra ID Groups를 LiteLLM Teams에 자동 생성

이 단계의 목표는 Azure Entra ID의 LiteLLM Enterprise App에 새 Group이 추가될 때 LiteLLM이 LiteLLM DB에 새 팀을 자동으로 생성하게 하는 거예요.

1.1 Entra ID에서 새 그룹 생성

Azure Portal > Groups > New Group으로 이동해 새 그룹을 만드세요.

1.2 그룹을 LiteLLM Enterprise App에 할당

Azure Portal에서 Enterprise Applications > litellm 앱을 선택하세요.

litellm 앱을 선택한 뒤 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에서 최신 Groups와 Members를 가져오도록 트리거합니다.

1.4 LiteLLM UI에서 새 팀 확인

LiteLLM UI에서 Teams로 이동하면 LiteLLM에 자동 생성된 새 팀 Production LLM Evals Group이 보일 거예요.

이것이 어떻게 동작하는가

SSO 사용자가 LiteLLM에 로그인하면:

LiteLLM이 LiteLLM Enterprise App 아래의 Groups를 자동으로 가져옴
LiteLLM Enterprise App에 할당된 Production LLM Evals Group을 발견
LiteLLM이 이 그룹의 ID가 LiteLLM Teams Table에 존재하는지 확인
ID가 없으므로 LiteLLM이 다음 값으로 새 팀을 자동 생성:
- Name: Production LLM Evals Group
- ID: Entra ID 그룹의 ID와 동일

2. Entra ID 팀 구성원 동기화

이 단계에서는 Entra ID의 Production LLM Evals Group에 새 사용자가 추가되면 LiteLLM이 사용자를 LiteLLM DB의 Production LLM Evals Team에 자동으로 추가하게 합니다.

2.1 Entra ID에서 `Production LLM Evals` Group으로 이동

Entra ID에서 Production LLM Evals Group으로 이동하세요.

2.2 Entra ID의 그룹에 구성원 추가

Members > Add members를 선택하세요.

이 단계에서 Production LLM Evals Team에 추가하려는 사용자를 추가해야 해요.

2.3 LiteLLM UI에 새 사용자로 로그인

LiteLLM UI에 새 사용자로 로그인하세요. Entra ID SSO 페이지로 리디렉션될 거예요. 이 SSO 로그인 흐름은 LiteLLM이 Azure Entra ID에서 최신 Groups와 Members를 가져오도록 트리거합니다. 이 단계에서 LiteLLM은 teams, team members를 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 Government Cloud (GCC High)

기본적으로 LiteLLM은 상용 Microsoft Graph 엔드포인트 https://graph.microsoft.com/v1.0에서 그룹 구성원을 동기화해요. Azure Government Cloud GCC High는 Graph를 다른 호스트에서 서빙하므로, MICROSOFT_GRAPH_ENDPOINT를 sovereign cloud 엔드포인트로 설정해서 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 그룹 조회에 사용됩니다. GCC High에 대해서는 MICROSOFT_AUTHORIZATION_ENDPOINT, MICROSOFT_TOKEN_ENDPOINT, MICROSOFT_USERINFO_ENDPOINT로 인증(authorization), 토큰, userinfo 엔드포인트도 재정의하는 것이 좋아요.

3. LiteLLM에 자동 생성되는 새 팀의 기본 params 설정

Azure Entra ID의 LiteLLM Enterprise App에 새 Group이 추가될 때 litellm이 LiteLLM DB에 새 팀을 자동 생성하므로, 생성되는 새 팀의 기본 params를 설정할 수 있어요.

이를 통해 생성되는 새 팀에 기본 예산, 모델 등을 설정할 수 있습니다.

3.1 litellm에 `default_team_params` 설정

litellm config 파일로 이동해 다음 params를 설정하세요.

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로 이동하면 LiteLLM에 자동 생성된 새 팀 Default LiteLLM Prod Team이 보일 거예요.
LiteLLM이 이 새 팀에 기본 params를 설정한다는 점을 참고하세요.

4. 사용자 권한에 Entra ID App Roles 사용

Entra ID에서 App Roles를 사용해 전역 proxy 역할을 직접 할당할 수 있어요. LiteLLM은 SSO 로그인 중 JWT 토큰에서 app roles를 읽고 해당 역할을 사용자에게 할당합니다.

4.1 지원되는 역할

다음 전역 proxy 역할 중 하나를 사용하세요(대소문자 무시):

proxy_admin - 전체 LiteLLM 플랫폼의 관리자
proxy_admin_viewer - 읽기 전용 관리자 접근(모든 키와 비용을 볼 수 있음)
internal_user - 표준 사용자(자신의 키 생성/보기/삭제, 자신의 비용 보기 가능)
internal_user_viewer - 읽기 전용 표준 사용자(자신의 키와 비용 보기 가능)

org_admin을 Entra App Role로 사용하지 마세요. 그 값은 사용자의 전역 역할로 인식되고 저장되지만, Entra 역할 클레임은 조직을 식별하지 않으며 조직 구성원 자격을 만들지 않아요. 그 자체로 조직 관리자 권한을 부여하지 않습니다. 조직 접근 제어를 사용해 각 조직에 사용자를 org_admin으로 개별 추가하세요.

4.2 Entra ID에서 App Roles 만들기

https://portal.azure.com/ 에서 App Registration으로 이동하세요.
App roles > Create app role로 이동하세요.
앱 역할을 구성하세요:
- Display name: Proxy Admin(또는 원하는 표시 이름)
- Value: proxy_admin(위의 지원되는 역할 값 중 하나 사용)
- Description: LiteLLM proxy에 대한 관리자 접근
- Allowed member types: Users/Groups
Apply를 클릭해 역할을 저장하세요.

4.3 사용자를 App Roles에 할당

https://portal.azure.com/ 에서 Enterprise Applications로 이동하세요.
LiteLLM 애플리케이션을 선택하세요.
Users and groups > Add user/group로 이동하세요.
사용자를 선택하고 만든 앱 역할 중 하나에 할당하세요.

4.4 역할 할당 테스트

앱 역할이 할당된 사용자로 SSO를 통해 LiteLLM UI에 로그인하세요.
LiteLLM이 JWT 토큰에서 앱 역할을 자동으로 추출합니다.
사용자에게 데이터베이스에서 해당 LiteLLM 역할이 할당됩니다.
사용자의 권한이 할당된 역할을 반영합니다.

동작 방식:

사용자가 Microsoft SSO로 로그인하면 LiteLLM이 JWT id_token에서 roles 또는 app_roles 클레임을 추출합니다.
어떤 역할이든 유효한 LiteLLM 역할(대소문자 무시)과 일치하면 그 역할이 사용자에게 할당됩니다.
지원되는 전역 역할이 여러 개 있으면 LiteLLM은 가장 높은 권한 역할을 선택합니다: proxy_admin, proxy_admin_viewer, internal_user, 그다음 internal_user_viewer.
이 역할 할당은 LiteLLM 데이터베이스에 유지되며 사용자의 접근 수준을 결정합니다.

비디오 안내

이것은 Microsoft Entra ID에 대한 sso auto-add 설정을 안내합니다. Microsoft Entra ID로 설정하는 방법은 이 영상을 따라 보세요.

더 알아보기 (Learn more)

LiteLLM SSO

Microsoft SSO: Groups, Members를 LiteLLM과 동기화