SCIM with LiteLLM

SCIM with LiteLLM

✨ Enterprise: SCIM 지원에는 프리미엄 라이선스가 필요합니다.

ID 제공자(Okta, Azure AD, OneLogin 등)가 LiteLLM에서 사용자와 팀(그룹) 프로비저닝, 업데이트, 디프로비저닝을 자동화할 수 있게 해줍니다. 이 튜토리얼은 IDP를 LiteLLM SCIM Endpoints에 연결하는 단계를 안내합니다.

SCIM을 위한 지원되는 SSO 제공자

LiteLLM SCIM Endpoints에 연결하기 위한 지원 SSO 제공자 목록입니다.

  • Microsoft Entra ID (Azure AD)
  • Okta
  • Google Workspace
  • OneLogin
  • Keycloak
  • Auth0

1. SCIM Tenant URL과 Bearer Token 얻기

LiteLLM에서 Settings > Admin Settings > SCIM으로 이동하세요. 이 페이지에서 SCIM Token을 만들면 IDP가 litellm /scim 엔드포인트에 인증할 수 있어요.

2. IDP를 LiteLLM SCIM Endpoints에 연결

IDP 제공자에서 SSO 애플리케이션으로 이동하고 Provisioning > New provisioning configuration을 선택하세요. 이 페이지에 litellm scim tenant url과 bearer token을 붙여넣으세요. 붙여넣은 뒤 IDP가 LiteLLM SCIM 엔드포인트에 인증할 수 있는지 Test Connection을 클릭하세요.

3. SCIM 연결 테스트

3.1 그룹을 LiteLLM Enterprise App에 할당

IDP 포털에서 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을 자동 생성하게 하는 것입니다.

3.2 SSO를 통해 LiteLLM UI에 로그인

SSO를 통해 LiteLLM UI에 로그인하세요. Entra ID SSO 페이지로 리디렉션될 거예요. 이 SSO 로그인 흐름은 LiteLLM이 Azure Entra ID에서 최신 Groups와 Members를 가져오도록 트리거합니다.

3.3 LiteLLM UI에서 새 팀 확인

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

참고: SCIM을 통해 사용자가 디프로비저닝되면 LiteLLM은 그 사용자가 소유한 모든 virtual key를 차단하고 인증 캐시에서 제거하여 즉시 접근을 취소합니다. 키는 지출 기록을 보존하기 위해 데이터베이스에 남아 있어요. Deactivation and deprovisioning을 참고하세요.

사용자 속성 매핑

LiteLLM은 POST /scim/v2/Users와 PUT /scim/v2/Users/{id}에 제출된 SCIM 사용자 리소스에서 다음 속성을 처리합니다. 표에 나열되지 않은 속성은 무시됩니다.

| SCIM attribute | Stored as | Notes | | userName | user_id | Stored unchanged. If omitted, LiteLLM generates a random UUID. | | emails[0].value | user_email | Only the first email entry is processed, regardless of its primary value. | | name.givenName | user_alias and metadata.scim_metadata.givenName | Used to derive the user alias; displayName is not used during POST or PUT. | | name.familyName | metadata.scim_metadata.familyName | Stored as SCIM metadata. | | groups[].value | teams | Each value is treated as an existing LiteLLM team_id. | | externalId | sso_user_id | Stored only for PUT and PATCH. It remains unset after initial POST provisioning until the first update. | | active | metadata.scim_active | Applied only for PUT and PATCH. A POST request with active: false still creates an active user. | | entitlements, roles | metadata.scim_entitlements, metadata.scim_roles | Preserved for subsequent read responses; these values do not grant LiteLLM permissions. | | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User | metadata.scim_enterprise | Preserved for subsequent read responses. |

displayName은 POST나 PUT으로 처리되지 않습니다. displayName을 대상으로 하는 PATCH 연산은 user_alias를 업데이트하므로 최종 별칭은 가장 최근에 적용된 요청에 달려 있어요.

SCIM 읽기와 쓰기 표현은 다릅니다. GET /scim/v2/Users는 user_email에서 userName과 displayName을 구성하는 반면, 쓰기 연산은 userName을 user_id로 저장합니다. externalId 값은 읽기 응답에 포함되지 않습니다. ID 제공자 조회 워크플로를 지원하기 위해 userName eq 필터는 user_email과 user_id 모두와 일치하므로 Okta 같은 제공자가 라이프사이클 업데이트를 적용하기 전에 이전에 프로비저닝된 사용자를 찾을 수 있어요.

이미 존재하는 사용자 프로비저닝

LiteLLM은 잠재적 충돌을 다음 순서로 평가합니다:

  • userName이 기존 LiteLLM user_id와 일치하면 POST /scim/v2/Users는 409 Conflict를 반환합니다. ID 제공자는 PUT이나 PATCH로 기존 사용자를 업데이트할 수 있어요.
  • userName은 새것이지만 emails[0].value가 기존 사용자와 일치하면 LiteLLM은 중복을 만들지 않고 기존 레코드를 업데이트합니다. user_id를 들어오는 userName으로 교체하고, 제공된 groups로 팀 구성원을 조정하며, user_email, user_alias, teams, metadata를 교체합니다. 엔드포인트는 201을 반환합니다. 기존 키, 구성원, 지출 기록은 업데이트된 레코드와 연결을 유지합니다. 이 이메일 기반 재할당을 막으려면 ID 제공자에 안정적인 userName을 구성하세요.

이 동작은 litellm_settings.scim_upsert_user와 독립적입니다. 그 설정은 그룹 구성원을 해석할 때만 적용됩니다. 기본값 true에서는 그룹에 대한 PUT이나 PATCH 요청이 LiteLLM이 아직 마주치지 않은 멤버 ID에 대해 사용자를 만듭니다. false로 설정하면 요청이 400을 반환하며 사용자를 먼저 생성해야 합니다. 이 설정은 POST /Users의 이메일 기반 매칭에는 영향을 주지 않아요.

proxy admin 역할 할당

기본적으로 새로 프로비저닝된 SCIM 사용자는 litellm_settings.default_internal_user_params.user_role에 구성된 역할을 받습니다. 역할이 구성되지 않으면 LiteLLM은 internal_user_view_only를 할당합니다. 기존 사용자는 현재 역할을 유지합니다.

SCIM 그룹 구성원을 통해 전역 역할을 관리하려면 scim_admin_group을 구성하세요:

config.yaml

litellm_settings:
  scim_admin_group: "litellm-admins"

LiteLLM은 이 설정을 각 그룹의 value와 display 이름과 비교합니다. 일치하는 그룹의 구성원은 proxy_admin 역할을 받고, 다른 모든 사용자는 위에서 설명한 기본 역할을 받습니다. LiteLLM은 모든 SCIM 쓰기에서 이 매핑을 평가하므로 사용자를 구성된 admin 그룹에서 제거하면 다음 동기화에서 사용자의 역할이 바뀝니다. scim_admin_group이 구성되지 않으면 SCIM은 Admin UI나 관리 API를 통해 할당된 역할을 수정하지 않습니다.

비활성화 및 디프로비저닝

PUT 또는 PATCH 요청이 active를 false로 설정하면 LiteLLM은 사용자가 소유한 모든 virtual key를 차단하고 해당 자격 증명을 인증 캐시에서 제거해 즉시 접근을 취소합니다. LiteLLM은 이 연산으로 차단된 키를 기록합니다. 사용자가 재활성화되면 그 키만 차단 해제됩니다. 관리자가 독립적으로 차단한 키는 차단된 채로 남아 있어요. active를 생략한 PUT 요청은 사용자의 현재 활성화 상태를 보존합니다.

DELETE /scim/v2/Users/{id}는 사용자의 팀과 조직 구성원을 제거하고, 관련 초대 링크를 삭제하며, 사용자의 virtual key를 차단하고, 사용자 레코드를 삭제합니다. 키는 과거 지출 데이터를 보존하기 위해 데이터베이스에 남아 있어요.

더 알아보기 (Learn more)