신원 프로비저닝과 키 발급

신원 프로비저닝과 키 발급 (Provisioning identities and issuing keys)

SSO 배포에서 흔히 나오는 질문은 신원 공급자(SCIM으로)를 통해 프로비저닝된 사용자가 자동으로 가상 키와 노트북의 자격증명을 얻어 게이트웨이를 호출할 준비가 되느냐예요. LiteLLM은 이 모든 조각을 갖고 있지만, 하나의 턴키(turnkey) 흐름이 아니라 조합하는 별개의 기능들이에요.

이 페이지는 SCIM으로 프로비저닝된 사용자가 자신의 디바이스에서 인증하고 자기 가상 키를 받는 동작 설정으로 아무것도 없는 상태부터 데려가는 단계별 가이드예요. 각 단계 후 체크포인트가 있어 현재 위치를 알 수 있어요.

단일 기능에 대한 참조만 필요하다면 전용 페이지가 더 깊이 다루어요: SCIM 프로비저닝, OIDC JWT 인증, JWT → 가상 키 매핑, CLI 인증.

출처: 문서

본문

만드려는 것 (What you are building)

네 개의 계층이 결합되어 엔드투엔드 흐름을 이루며, 각각 한 가지 작업을 하는 별개 기능이에요.

계층	기능	만드는 것	Enterprise?
신원 프로비저닝	SCIM	IdP에서 동기화된 `LiteLLM_UserTable` 행과 팀	예
요청 인증	JWT 인증	IdP 토큰에서 요청별 검증된 호출자 신원	예
권한 부여 + 지출	가상 키	모델 접근, 예산, 레이트 리밋, 지출 추적	아니요
디바이스 자격증명 + 에이전트 실행	CLI 로그인·래퍼 (`lite login`, `lite claude`/`lite codex`)	저장된 세션 토큰, 프록시 env 변수가 설정되어 실행되는 코딩 에이전트	아니요

이들은 자동으로 서로 넘겨주지 않아요. SCIM이 사용자를 만들더라도 키는 발급하지 않아요. JWT 인증이 토큰을 검증해도 그 자체로 키를 만들지 않아요. 둘 다 사용자 디바이스에 아무것도 넣지 않아요. 올바른 조합을 켜고 공유 신원 클레임을 일치시킴으로써 엔드투엔드 동작을 얻는데, 아래 단계가 그렇게 해요.

사전 요구사항 (Prerequisites)

데이터베이스로 뒷받침되는 LiteLLM 프록시(SCIM과 auto_register 모두 여기에 기록), 엔터프라이즈 라이선스(SCIM과 JWT 인증 모두 엔터프라이즈 기능), 프록시 master_key, 그리고 JWT용 OIDC와 프로비저닝용 SCIM 2.0을 지원하는 신원 공급자(Okta, Entra ID, OneLogin, Keycloak, Auth0, Google Workspace)가 필요해요.

1단계: JWT 인증 켜기

게이트웨이를 IdP의 서명 키에 연결하고 어떤 클레임이 사용자·이메일·팀을 담는지 알려줘요. JWT_PUBLIC_KEY_URL을 IdP의 JWKS나 OIDC discovery URL로 설정하고, 선택적으로 JWT_AUDIENCE와 JWT_ISSUER로 허용되는 토큰을 제한해요.

export JWT_PUBLIC_KEY_URL="https://your-idp.example.com/.well-known/openid-configuration"
export JWT_AUDIENCE="litellm-proxy"     # optional but recommended
export JWT_ISSUER="https://your-idp.example.com"  # optional but recommended

config.yaml:

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  enable_jwt_auth: True
  litellm_jwtauth:
    user_id_jwt_field: "sub"        # stable per-user id from your IdP
    user_email_jwt_field: "email"
    team_ids_jwt_field: "groups"    # claim carrying the user's group/team ids

체크포인트. 프록시를 재시작하고 유효한 IdP JWT를 bearer 토큰으로 요청을 보내세요. 인증되고 호출자를 팀으로 해석해야 해요. 401이 나오면 서명·audience·issuer 검사가 실패하는 것이며, OIDC JWT 인증 문서에서 문제 해결 방법을 확인하세요.

2단계: SCIM으로 사용자·팀 프로비저닝

IdP가 사용할 SCIM 토큰을 만든 뒤 프로비저닝을 연결해요. Admin UI에서 Settings > Admin Settings > SCIM으로 가서 SCIM 토큰을 만들어요. 이것은 라우트가 /scim/*로 잠긴 일반 가상 키예요. 테넌트 URL(https://<your-proxy>/scim/v2)과 토큰을 복사해요. IdP의 LiteLLM 앱 프로비저닝 구성에 그 URL과 토큰을 붙여넣고, 동기화할 사용자·그룹을 지정해요. 전체 워크스루는 SCIM 페이지에 스크린샷과 함께 있어요.

체크포인트. 지정 후 사용자와 팀이 착륙했는지 확인해요.

curl 'https://<your-proxy>/scim/v2/Users' \
  -H 'Authorization: Bearer ***'

프로비저닝된 사용자가 보이고, 지정된 그룹이 UI에서 팀으로 나타나야 해요. 이 사용자들은 아직 가상 키가 없어요. SCIM은 auto_create_key=False로 신원을 만들고 절대 키를 발급하지 않아요. 그것은 3단계가 다룹니다.

3단계: 가상 키 자동 등록 켜기

litellm_jwtauth에 두 가지 설정을 추가해요: 각 클라이언트를 식별하는 클레임, 그리고 클라이언트에 키가 아직 없을 때의 동작.

config.yaml:

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  enable_jwt_auth: True
  litellm_jwtauth:
    user_id_jwt_field: "sub"
    user_email_jwt_field: "email"
    team_ids_jwt_field: "groups"
    virtual_key_claim_field: "email"                    # per-client key lookup
    unregistered_jwt_client_behavior: "auto_register"   # mint on first request

unregistered_jwt_client_behavior는 fallback_team_mapping(기본값, 팀 인증으로 대체), reject(매핑이 없으면 403), auto_register를 허용해요. auto_register를 쓰면 새 클레임 값이 담긴 첫 요청이 관리자 호출 없이 즉석에서 가상 키와 클레임→키 매핑을 발급해요. 키는 토큰이 전체 정책(서명, RBAC·scope, custom_validate, user_allowed_email_domain)을 통과한 뒤에만 생성되고, JWT에서 해석된 팀·사용자·조직을 상속하며, 프록시 관리자로 해석되는 토큰은 건너뛰고, 데이터베이스를 요구해요. 클라이언트별 예산·수동 매핑은 JWT → 가상 키 매핑 문서를 참고하세요.

체크포인트. 프록시를 재시작해요. 트리거는 이 구성 변경이 아니라 첫 요청이므로 아직 아무것도 생성되지 않아요. 5단계에서 검증합니다.

4단계: 코딩 에이전트를 게이트웨이에 연결

개발자의 도구는 참조로 프록시를, 자격증명으로 bearer 토큰을 필요로 해요. 각 개발자가 수동으로 export하게 하는 대신 lite CLI가 대신 연결해요. 맞는 모델을 골라요.

권장: lite CLI로 에이전트를 실행해요. CLI에는 lite claude, lite codex, lite opencode 래퍼 명령이 있어요. 자격증명이 없으면 SSO로 로그인 시키고, 키를 프록시에 검증하며, 에이전트가 읽는 환경 변수를 설정한 뒤 헨드오프해요. 개발자는 아무것도 export하지 않아요.

export LITELLM_PROXY_URL=https://your-litellm-proxy:4000
lite claude          # or: lite codex / lite opencode

첫 실행에서 lite login(브라우저 SSO)을 트리거하고 짧은 수명의 세션 토큰을 개발자 OS 키체인에 저장한 뒤 에이전트를 시작해요. 래퍼는 에이전트별로 올바른 변수를 설정해요. Claude Code는 ANTHROPIC_BASE_URL(프록시 루트)과 ANTHROPIC_AUTH_TOKEN을 받고, 흩어진 ANTHROPIC_API_KEY를 지워 프록시 토큰이 이기게 해요. Codex와 OpenCode는 OPENAI_BASE_URL(프록시 + /v1)과 OPENAI_API_KEY를 받으며, Codex는 OPENAI_BASE_URL을 무시하므로 커스텀 프로바이더를 추가로 가리켜요. 래퍼를 통해 에이전트 자체 플래그를 전달해요(예: lite claude --model my-proxy-model). 요청하는 모델은 프록시에 존재해야 해요. 이 경로는 lite login의 세션 토큰을 사용하며 SSO(그리고 SCIM 프로비저닝된) 사용자에 묶여 있어 3단계의 auto_register 경로를 거치지 않아요. 로그인 흐름이 자격증명을 발급하고 지출은 여전히 그 사용자에 대해 추적돼요. SSO 세션 토큰 대신 수명이 긴 가상 키를 사용하려면 --api-key를 전달하거나 LITELLM_PROXY_API_KEY를 설정하세요.

IdP JWT를 이미 가진 클라이언트. 서비스나 IdP에 이미 연결된 에이전트는 IdP가 발급한 JWT를 bearer 토큰으로 프록시에 바로 보내요. LiteLLM은 절대 저장하지 않아요. 이것이 3단계의 auto_register를 트리거하는 경로로, 첫 요청에서 사용자별 가상 키를 발급해요. Anthropic 스타일 클라이언트는 프록시 루트를 가리키고 JWT를 인증 토큰으로 전달해요.

export ANTHROPIC_BASE_URL="https://your-litellm-proxy:4000"
export ANTHROPIC_AUTH_TOKEN="<user-sso-jwt-token>"

사람들을 헷갈리게 하는 두 가지 명확화. lite login의 자격증명은 OS 키체인(macOS Keychain, Windows Credential Manager, Linux Secret Service)과 ~/.litellm/token.json에서 비밀 아닌 메타데이터(게이트웨이 URL, 사용자 id·이메일·역할, 인증 헤더 이름, 로그인 시각)만 유지해요. 키체인에 도달하려면 keyring 패키지가 필요하며, 이는 cli extra와 함께 오므로 CLI를 litellm[cli]로 설치해요. 키체인이 없는 곳(예: 헤드리스 Linux)이나 LITELLM_CLI_DISABLE_KEYRING으로 키체인 저장을 끈 곳에서는 자격증명이 같은 0600 파일로 대체되고 lite login이 둘 중 무엇을 사용했는지 말해줘요. 여전히 git 스타일 credential-helper 통합은 없어요. CLI가 저장하는 세션 토큰은 게이트웨이로 범위가 한정된 LiteLLM 발급 토큰이며, 원시 IdP JWT도 Keys UI에 나타나는 영속 가상 키도 아니에요.

5단계: 자동 등록 트리거 및 검증

4단계 두 번째 옵션(Auto_register 경로, 클라이언트가 IdP JWT를 직접 전송)을 검증해요. 개발자가 lite claude/lite codex로 온보딩하면 검사할 매핑이 없으므로, 에이전트가 실행되고 사용자 지출이 대시보드에 나타나면 성공을 확인해요. IdP-JWT 경로에서는 프로비저닝된 사용자로 첫 실제 요청을 보내요.

JWT_TOKEN="eyJhbG..."   # a valid IdP token for the SCIM-provisioned user

curl -X POST 'https://your-litellm-proxy:4000/v1/chat/completions' \
  -H "Authorization: Bearer ***" \
  -H 'Content-Type: application/json' \
  -d '{"model": "claude-sonnet-5", "messages": [{"role": "user", "content": "Hello"}]}'

그 첫 요청이 사용자의 가상 키와 클레임→키 매핑을 발급해요. 둘 다 확인해요.

# The mapping now exists, keyed on the claim value (the user's email here)
curl 'https://your-litellm-proxy:4000/jwt/key/mapping/list?page=1&size=50' \
  -H "Authorization: Bearer ***"

Admin UI에서 자동 등록된 키가 auto_registered: true 메타데이터로 사용자 아래 나타나며, 지출·레이트 리밋·모델 접근이 이제 사용자별로 추적돼요. 이후 그 사용자의 모든 요청은 같은 키를 재사용해요. 이 지점에서 흐름이 자립해요. 특정 사용자의 예산이나 모델 세트를 조정할 때만 다시 들어가며, 기본 키를 업데이트해서 합니다.

키가 올바른 사용자에 묶이게 하기

자동 등록된 키를 올바른 SCIM 프로비저닝 사용자와 연관하려면 SCIM과 JWT 클레임에 걸쳐 일관된 신원 값을 구성해요. LiteLLM은 SCIM userName을 user_id로, emails[0].value를 user_email로 저장해요. externalId 속성은 PUT·PATCH에서는 sso_user_id로 저장되지만 초기 POST에서는 그렇지 않아요. 따라서 사용자가 업데이트될 때까지 sso_user_id가 비어 있을 수 있어요. 속성 매핑 표를 참고하세요.

user_id_jwt_field가 SCIM userName으로 제공된 것과 같은 값을 담는 JWT 클레임을 참조하도록 구성해요. emails[0].value가 user_email_jwt_field로 구성된 JWT 클레임과 일치하면 LiteLLM은 이메일로 기존 사용자와도 일치시킬 수 있어요. virtual_key_claim_field는 이메일 주소나 안정적인 subject 식별자 같은 전역적으로 고유한 값으로 설정해, 여러 사용자가 같은 키 매핑을 공유하지 못하게 해요.

LiteLLM이 하는 것과 하지 않는 것

동작	지원?
SCIM이 IdP에서 사용자·팀 프로비저닝	예
SCIM이 프로비저닝된 사용자용 가상 키 자동 생성	아니요 (`auto_create_key=False`)
SCIM 디프로비저닝이 사용자 키 폐기	예
JWT 인증이 IdP 토큰으로 요청 인증	예
JWT 인증이 클라이언트별 가상 키 자동 등록	예, `virtual_key_claim_field` + `auto_register`
SCIM 프로비저닝 이벤트가 직접 키 생성 트리거	아니요 (첫 요청이 지연 생성)
`lite login`이 디바이스에 게이트웨이 자격증명 저장	예 (OS 키체인, 없으면 `~/.litellm/token.json`(0600))
`lite claude`/`lite codex`/`lite opencode`가 에이전트 env 변수 설정	예 (기본 URL·bearer 토큰을 에이전트별로 연결)
OS 키체인에 자격증명 저장	예 (service `litellm-cli`; git 스타일 credential-helper 통합 없음)
디바이스 저장 자격증명이 원시 IdP JWT	아니요 (LiteLLM 발급 세션 토큰임)

SCIM with LiteLLM: IdP에서 사용자·팀 프로비저닝
OIDC JWT 인증: 기본 JWT 인증 설정
JWT → 가상 키 매핑: 클라이언트별 키, 수동 매핑, auto_register
CLI 인증: lite login 디바이스 흐름
가상 키: 접근 제어와 지출의 단위

신원 프로비저닝과 키 발급