역할 기반 접근 제어

역할 기반 접근 제어 (Role-based Access Controls, RBAC)

LiteLLM의 RBAC가 조직, 팀, 내부 사용자 역할을 기반으로 어떻게 동작하는지 알아봐요.

출처: 문서

본문

RBAC(역할 기반 접근 제어)는 Organizations(조직), Teams(팀), Internal User Roles(내부 사용자 역할)을 기반으로 해요.

개념

Organizations는 Teams를 담는 최상위 엔티티예요.
Team - 여러 Internal Users의 모음이에요.
Internal Users - 키를 만들고, LLM API를 호출하고, LiteLLM에서 사용량을 볼 수 있는 사용자예요. 사용자는 여러 팀에 속할 수 있어요.
Virtual Keys - LiteLLM API 인증에 쓰는 키예요. 각 키는 선택적으로 user_id, team_id, 또는 둘 다와 연결될 수 있어요:
- 사용자 전용 키: user_id는 있고 team_id는 없음. 개별 추적, 사용자가 삭제될 때 삭제.
- 팀 키 (서비스 계정): team_id는 있고 user_id는 없음. 팀이 공유, 사용자가 제거돼도 삭제되지 않음.
- 사용자 + 팀 키: user_id와 team_id 둘 다 있음. 팀 컨텍스트 내 특정 사용자에 속함.

각 키 유형을 언제 사용할까

키 유형	사용 사례	스펜드 추적	수명 주기
사용자 전용	개별 개발자의 개인 API 키	사용자에게 추적	사용자 삭제 시 삭제
팀 (서비스 계정)	프로덕션 앱, CI/CD 파이프라인, 공유 서비스	팀에게만 추적	팀 멤버가 떠나도 유지
사용자 + 팀	팀 컨텍스트에서 일하는 사용자	사용자와 팀 모두에게 추적	사용자 삭제 시 삭제

예시 시나리오:

로컬 테스트하는 개발자에게는 사용자 전용 키 사용
직원이 떠나도 깨지지 않아야 하는 프로덕션 앱에는 팀 서비스 계정 키 사용
팀 예산 내에서 개별 책임성을 원할 때는 사용자 + 팀 키 사용

사용자 역할

LiteLLM에는 두 가지 유형의 역할이 있어요:

글로벌 Proxy 역할 - 모든 조직·팀에 걸쳐 적용되는 플랫폼 차원 역할
조직/팀 전용 역할 - 특정 조직·팀에 한정된 역할 (Premium 기능)

글로벌 Proxy 역할

역할 이름	권한
`proxy_admin`	전체 플랫폼의 관리자. 모든 조직·팀·사용자에 대한 완전한 제어
`proxy_admin_viewer`	로그인, 모든 키 보기, 플랫폼 전반 스펜드 보기. 키 생성/삭제, 새 사용자 추가 불가
`internal_user`	로그인, 자신의 키 보기/생성(팀 전용 권한이 허용할 때)/삭제, 자신의 스펜드 보기. 새 사용자 추가 불가
`internal_user_viewer`	⚠️ 사용 중단 - 팀/조직 전용 역할 사용. 로그인, 자신의 키 보기, 자신의 스펜드 보기. 키 생성/삭제, 새 사용자 추가 불가

조직/팀 전용 역할

역할 이름	권한
`org_admin`	특정 조직의 관리자. 자신의 조직 안에서 팀과 사용자를 만들 수 있음 ✨ Premium 기능
`team_admin`	특정 팀의 관리자. 팀 멤버 관리, 팀 멤버 권한 업데이트, 팀 키 생성 가능 ✨ Premium 기능

사용량 대시보드 가시성

Usage 페이지는 선택한 보기와 로그인 사용자 역할에 따라 다른 데이터를 보여줘요:

보기	무엇을 보여주나
Personal usage	로그인 사용자의 총 사용량. 여러 팀에 속하면 팀별로 개인 사용량을 나누지 않음
Team usage	선택한 팀의 전체 사용량 (로그인 사용자가 그 팀에 기여한 부분만이 아님)
Organization usage	사용자 조직 역할이 접근을 허용할 때 조직의 총 사용량
Global usage	proxy 관리자·뷰어를 위한 플랫폼 전반 사용량

LiteLLM Admin UI는 사용자 정의 대시보드를 호스팅하지 않아요. 팀 내 사용자별 사용량 같은 사용자 정의 보기가 필요하면 관리 API로 스펜드 데이터를 쿼리하거나 원격 측정을 외부 시스템으로 내보내요.

각 역할이 할 수 있는 것

Proxy Admin - 전체 접근

모든 것을 제어해요. 할 수 있는 일: 모든 조직 생성·관리, 모든 팀 생성·관리, 모든 사용자 생성·관리, 플랫폼 전반 스펜드·사용량 보기, 누구의 키든 생성·삭제, 팀 예산·레이트 리밋·모델 업데이트, 팀 멤버 관리·역할 부여. proxy 관리자는 LiteLLM 인스턴스를 실행하는 사람들만 해야 해요.

Proxy Admin Viewer - 플랫폼 전반 읽기 접근

플랫폼 전반을 볼 수 있지만 변경할 수 없어요. 모든 조직·팀·사용자, 스펜드·사용량, 모든 API 키 보기, 관리 대시보드 로그인 가능. 키 생성/삭제, 사용자 추가/제거, 예산·레이트 리밋·설정 수정 불가. 재무팀, 감사자, 수정 권한 없이 플랫폼 전반 가시성이 필요한 이해관계자가 대상이에요.

Internal User

(팀 전용 권한이 허용할 때) API 키를 만들고 호출할 수 있어요. 자신의 것만 봐요. 팀 관리자나 조직 관리자 역할이 부여되면 그렇게 될 수 있어요. 할 수 있는 일: 자신의 API 키 생성, 자신의 키 삭제, 자신의 스펜드·사용량 보기, 키로 API 호출. 팀/조직 전용 운영을 위해 UI 접근이 필요하거나 여러 키를 줄 개발자가 대상이에요.

Internal User Viewer - 읽기 전용 접근

사용 중단 - 팀/조직 전용 역할 사용. 자신의 정보를 볼 수 있지만 키를 만들거나 삭제하지는 못해요.

조직/팀 전용 역할

Enterprise 기능: 이 기능은 LiteLLM Enterprise 라이선스가 필요해요. 무료 30일 체험판이나 데모 예약이 가능해요.

이 역할은 특정 조직·팀에 한정돼요. 할당된 조직·팀 내 리소스만 관리할 수 있어요.

Org Admin - 조직 수준 접근

하나 이상의 조직을 관리해요. 자신의 조직 안에서 팀을 만들 수 있지만 다른 조직은 건드릴 수 없어요. 할 수 있는 일: 자신의 조직에서 팀 생성, 자신의 조직 팀에 사용자 추가, 자신의 조직 스펜드 보기, 자신의 조직 사용자 키 생성. 할 수 없는 일: 다른 조직 생성·관리, 조직 예산·레이트 리밋 수정, 조직 허용 모델 수정. 부서장·매니저가 대상이에요.

Team Admin - 팀 수준 접근

특정 팀을 관리해요. 팀 리드처럼 사람을 추가하고 설정을 업데이트할 수 있지만 그들의 팀에서만요. 할 수 있는 일: 팀 멤버 추가·제거, 팀 내 멤버 예산·레이트 리밋 업데이트, 팀 레이트 리밋(TPM/RPM)·허용 모델 변경, 팀의 max_budget 유지·하향, 팀 멤버 키 생성·삭제, 팀 BYOK 모델 등록, 팀 멤버 권한 구성. 할 수 없는 일: 새 팀 생성, 팀 max_budget 상향·예산 상한 제거(max_budget: null) — proxy 관리자만 가능, 팀에 글로벌 proxy 모델 추가/제거.

팀 예산 상향: /team/update에서 팀 관리자는 max_budget을 유지하거나 내릴 수만 있어요. 상향(또는 상한 제거)은 proxy 관리자 전용이라 팀 관리자가 스스로 스펜드 권한을 키울 수 없어요. 조직 범위 팀도 조직 예산 안에 있어야 해요.

팀 관리자 만들기: 팀 관리자를 지정하려면 LiteLLM Enterprise 사용자여야 해요.

curl -X POST 'http://0.0.0.0:4000/team/member_add' \
    -H "Authorization: Bearer ***" \
    -H 'Content-Type: application/json' \
    -d '{"team_id": "team-123", "member": {"role": "admin", "user_id": "[email protected]"}}'

팀 멤버 권한

✨ Premium 기능

팀 멤버 권한으로 일반 팀 멤버(role=user)가 자기 팀에서 API 키로 할 수 있는 것을 제어할 수 있어요. 기본적으로 팀 멤버는 키 정보만 볼 수 있지만, 키 생성·수정·삭제 권한을 추가로 부여할 수 있어요.

동작 방식

적용 대상: role=user인 팀 멤버 (팀 관리자나 조직 관리자가 아님)
범위: 자신의 팀에 속한 키에만 적용
구성: team_member_permissions로 팀 수준에서 설정
오버라이드: 팀 관리자와 조직 관리자는 이 설정과 무관하게 항상 전체 권한 보유

사용 가능한 권한

권한	메서드	설명
`/key/info`	GET	팀의 가상 키 정보 보기
`/key/health`	GET	팀의 가상 키 상태 확인
`/key/list`	GET	팀에 속한 모든 가상 키 목록
`/key/generate`	POST	팀의 새 가상 키 생성
`/key/service-account/generate`	POST	팀의 서비스 계정 키(특정 사용자 미연결) 생성
`/key/update`	POST	팀의 기존 가상 키 수정
`/key/delete`	POST	팀에 속한 가상 키 삭제
`/key/regenerate`	POST	팀의 가상 키 재생성
`/key/block`	POST	팀의 가상 키 차단
`/key/unblock`	POST	팀의 가상 키 차단 해제

기본 권한

기본적으로 팀 멤버는 다음만 할 수 있어요: /key/info (키 정보 보기), /key/health (키 상태 확인)

권한 구성

curl --location 'http://0.0.0.0:4000/team/update' \
    --header "Authorization: Bearer ***" \
    --header 'Content-Type: application/json' \
    --data '{
        "team_id": "team-123",
        "team_member_permissions": ["/key/info", "/key/health", "/key/generate", "/key/update"]
    }'

이렇게 하면 팀 멤버가 키 정보 보기, 키 생성, 기존 키 업데이트는 가능하지만 키 삭제는 못 해요. 권한을 구성할 수 있는 사람: Proxy Admin(모든 팀), Org Admin(자기 조직의 팀), Team Admin(자기 팀).

빠른 비교

글로벌 Proxy 역할

작업	Proxy Admin	Proxy Admin Viewer	Internal User	Internal User Viewer ⚠️
조직 생성	✅	❌	❌	❌
팀 생성	✅	❌	❌	❌
모든 팀 관리	✅	❌	❌	❌
모든 키 생성/삭제	✅	❌	❌	❌
자신의 키 생성/삭제	✅	❌	✅	❌
플랫폼 전반 스펜드 보기	✅	✅	❌	❌
자신의 스펜드 보기	✅	✅	✅	✅
모든 키 보기	✅	✅	❌	❌
자신의 키 보기	✅	✅	✅	✅
사용자 추가/제거	✅	❌	❌	❌

조직/팀 전용 역할

작업	Org Admin	Team Admin
(자기 조직에서) 팀 생성	✅	❌
조직의 팀 관리	✅	❌
특정 팀 관리	✅	✅
팀 멤버 추가/제거	✅ (자기 조직)	✅ (자기 팀만)
팀 `max_budget` 유지/하향	✅ (자기 조직)	✅ (자기 팀만)
팀 레이트 리밋 업데이트	✅ (자기 조직)	✅ (자기 팀만)
팀 멤버 키 생성	✅ (자기 조직)	✅ (자기 팀만)
조직 스펜드 보기	✅ (자기 조직)	❌
팀 스펜드 보기	✅ (자기 조직)	✅ (자기 팀)
조직 생성	❌	❌
플랫폼 전반 스펜드 보기	❌	❌

조직 온보딩

✨ Premium 기능

1. 새 조직 생성

role=proxy_admin인 사용자는 누구나 새 조직을 만들 수 있어요.

curl --location 'http://0.0.0.0:4000/organization/new' \
    --header "Authorization: Bearer ***" \
    --header 'Content-Type: application/json' \
    --data '{
        "organization_alias": "marketing_department",
        "models": ["gpt-5.6-terra"],
        "max_budget": 20
    }'

예상 응답:

{
  "organization_id": "ad15e8ca-12ae-46f4-8659-d02debef1b23",
  "organization_alias": "marketing_department",
  "budget_id": "98754244-3a9c-4b31-b2e9-c63edc8fd7eb",
  "metadata": {},
  "models": [
    "gpt-5.6-terra"
  ],
  "created_by": "109010464461339474872",
  "updated_by": "109010464461339474872",
  "created_at": "2024-10-08T18:30:24.637000Z",
  "updated_at": "2024-10-08T18:30:24.637000Z"
}

2. 조직에 `org_admin` 추가

/organization/member_add를 호출할 수 있는 역할: proxy_admin, 그리고 자기 조직 안에서만 org_admin.

curl -X POST 'http://0.0.0.0:4000/organization/member_add' \
    -H "Authorization: Bearer ***" \
    -H 'Content-Type: application/json' \
    -d '{"organization_id": "ad15e8ca-12ae-46f4-8659-d02debef1b23", "member": {"role": "org_admin", "user_id": "[email protected]"}}'

이제 marketing_department 조직에 role=org_admin인 사용자가 생겼어요. 그 사용자용 Virtual Key를 만든 뒤 조직 관리자 운영에 쓸 수 있어요.

3. 조직 관리자가 팀 생성

조직 관리자가 2단계에서 만든 키로 조직 안에 Team을 만들어요.

curl --location 'http://0.0.0.0:4000/team/new' \
    --header "Authorization: Bearer ***" \
    --header 'Content-Type: application/json' \
    --data '{
        "team_alias": "engineering_team",
        "organization_id": "ad15e8ca-12ae-46f4-8659-d02debef1b23"
    }'

이렇게 하면 marketing_department 조직 안에 engineering_team 팀이 생성돼요.

4. 조직 관리자가 팀 관리자 추가

조직 관리자가 engineering_team을 관리할 팀 관리자를 추가할 수 있어요. role=admin을 부여하면 이 팀에 대한 팀 관리자가 돼요.

curl -X POST 'http://0.0.0.0:4000/team/member_add' \
    -H "Authorization: Bearer ***" \
    -H 'Content-Type: application/json' \
    -d '{"team_id": "01044ee8-441b-45f4-be7d-c70e002722d8", "member": {"role": "admin", "user_id": "[email protected]"}}'

이제 [email protected]이 팀 관리자예요. engineering_team을 관리(멤버 추가, 레이트 리밋 업데이트, 팀 예산 유지·하향, 키 생성)할 수 있지만 다른 팀은 건드릴 수 없고 팀 예산은 현재 상한 이상으로 올릴 수 없어요.

5. 팀 관리자가 팀 멤버 추가

이제 팀 관리자가 조직 관리자에게 묻지 않고 팀 멤버를 추가할 수 있어요.

curl -X POST 'http://0.0.0.0:4000/team/member_add' \
    -H "Authorization: Bearer ***" \
    -H 'Content-Type: application/json' \
    -d '{"team_id": "01044ee8-441b-45f4-be7d-c70e002722d8", "member": {"role": "user", "user_id": "[email protected]"}}'

팀 관리자는 팀 멤버용 키도 만들 수 있어요.

6. 팀 관리자가 팀 설정 업데이트

팀 관리자는 레이트 리밋을 업데이트하고 팀 예산을 유지·하향할 수 있어요. max_budget을 팀 현재 값 이상으로 올리려면 proxy 관리자가 필요해요.

curl --location 'http://0.0.0.0:4000/team/update' \
    --header "Authorization: Bearer ***" \
    --header 'Content-Type: application/json' \
    --data '{
        "team_id": "01044ee8-441b-45f4-be7d-c70e002722d8",
        "max_budget": 100,
        "rpm_limit": 1000
    }'

이 예시에서 max_budget: 100은 팀의 현재 예산이 이미 100 이상일 때만(유지/하향) 성공해요. 팀 예산을 올리려면 proxy 관리자 키를 사용하세요.

더 알아보기 (Learn more)

Organizations 문서
Teams 문서
Virtual Keys 문서
Access Groups 문서

역할 기반 접근 제어