Azure Redis Entra ID 인증

Azure Redis Entra ID 인증 (Azure Redis Entra ID Authentication)

LiteLLM의 Redis 캐시를 Azure Cache for Redis 또는 Azure Managed Redis에 Microsoft Entra ID(이전의 Azure AD)로 연결해요. 그러면 프록시가 관리 ID(managed identity)나 서비스 주체(service principal)로 인증하고, 콘피그에 액세스 키가 존재하지 않아요.

출처: 문서

본문

왜 사용하나요 (Why use it)

Entra ID 인증을 사용하면 클라이언트는 비밀번호 대신 수명이 짧은 Entra 액세스 토큰을 제시하고, Azure는 매 연결마다 캐시의 액세스 정책 할당에 대해 토큰을 검증해요. 액세스는 키를 교체하고 모든 복제본을 재배포하는 대신 정책 할당을 제거하는 방식으로 해지되며, 모든 연결이 테넌트 안의 특정 ID에 귀속돼요.

LiteLLM은 Entra 자격 증명을 한 번만 만들어 프록시 수명 동안 유지하므로, Azure SDK의 내부 토큰 캐시와 자동 갱신이 적용돼요. 각 새 Redis 연결은 새 토큰으로 인증해서, 초기 토큰이 약 1시간 후 만료되면 풀링된 연결이 실패하기 시작하는 실패 모드를 피해요.

요구사항 (Requirements)

azure-identity가 설치되어 있어야 해요. 이 패키지는 litellm[proxy]와 Docker 이미지에 포함돼요. 캐시에서 Entra ID 인증이 활성화되어야 하고, 프록시가 실행되는 ID에 데이터 액세스 정책이 있어야 해요. 응답 캐시에는 Data Contributor면 충분해요. Azure는 이 캐시들을 TLS로만 제공하므로 ssl: true를 설정하고 Azure Cache for Redis는 포트 6380, Azure Managed Redis는 포트 10000을 사용하세요.

구성 (Configuration)

azure_redis_ad_token: "true"를 설정하고 비밀번호를 제거하세요.

config.yaml에 설정하기

litellm_settings:
  cache: true
  cache_params:
    type: redis
    host: my-cache.redis.cache.windows.net
    port: 6380
    ssl: true
    azure_redis_ad_token: "true"

.env에 설정하기

REDIS_HOST="my-cache.redis.cache.windows.net"
REDIS_PORT="6380"
REDIS_SSL="True"
REDIS_AZURE_AD_TOKEN="True"
REDIS_USERNAME="<object id of the proxy's identity>"

Azure Redis 인스턴스는 보통 AUTH 중에 ID의 object(principal) ID를 Redis 사용자 이름으로 기대해요. REDIS_USERNAME 환경 변수를 그 object ID로 설정하세요. 설정하지 않으면 LiteLLM은 토큰만 보내는데, ACL로 구성된 인스턴스는 이를 거부할 수 있어요.

자격 증명이 해석되는 방식 (How credentials resolve)

• azure_client_id, azure_tenant_id, azure_client_secret이 모두 설정된 경우(cache_params 또는 표준 AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET 환경 변수), LiteLLM은 그 서비스 주체로 인증해요.
• azure_client_id만 설정된 경우, 그 사용자 할당 관리 ID로 인증해요.
• 그 외에는 DefaultAzureCredential로 폴백하는데, 이는 시스템 할당 관리 ID, Azure CLI, 그리고 기타 표준 azure-identity 메커니즘을 포함해요.

설정 (Settings)

REDIS_USERNAME은 환경 전용이며, 캐시가 AUTH에 사용자 이름을 요구할 때 ID의 object ID를 담아야 해요.

검증 (Verify)

프록시를 통해 캐시를 ping 해보세요. 정상 응답은 토큰이 발급되었고, Azure가 이를 수락했으며, 쓰기 왕복이 성공했음을 의미해요.

curl -s -X GET 'http://localhost:4000/cache/ping' \
  -H "Authorization: Bearer ***"

{
  "status": "healthy",
  "cache_type": "redis",
  "ping_response": true,
  "set_cache_response": "success"
}

참고 사항 (Notes)

• 동기 Redis 클라이언트는 사용자 정의 connect 함수 안에서 인증해요. 비동기 클라이언트는 동일한 라이브 자격 증명을 redis-py 자격 증명 제공자로 감싸서 새 연결마다 참조해요. 두 경로 모두 하나의 자격 증명 객체를 공유하므로, 토큰 갱신은 재시작 없이 Azure SDK 안에서 일어나요.
• Entra ID와 함께 GCP IAM(gcp_service_account)을 구성하면 GCP 경로가 우선하고 LiteLLM은 경고를 기록해요. Entra ID와 함께 AWS ElastiCache IAM(aws_iam_auth)을 구성하면 Entra 경로가 우선하고 역시 경고를 기록해요. 정확히 하나만 구성하세요. 직접 credential_provider를 제공하면 이 모두를 덮어써요.

문제 해결 (Troubleshooting)

• azure-identity is required for Azure AD Redis authentication — 사용자 지정 설치에서 패키지가 빠졌다는 뜻. 이미 litellm[proxy]의 일부예요.
• Azure AD authentication failed for Redis 또는 WRONGPASS invalid username-password pair — 토큰은 발급됐지만 캐시가 거부했어요. 일반적인 원인은 캐시에서 Entra ID 인증이 활성화되지 않았거나, ID에 데이터 액세스 정책 할당이 없거나, REDIS_USERNAME이 ID의 object ID와 일치하지 않는 경우예요.
• DefaultAzureCredential failed to retrieve a token 같은 azure-identity 자체의 오류 — 자격 증명 소스를 찾을 수 없다는 뜻. 프록시가 실제로 할당한 관리 ID로 실행되는지, 또는 AZURE_* 변수가 설정됐는지 확인하세요.

함께 보기 (See also)

• Redis 캐시의 나머지 모든 것(클러스터 토폴로지, 네임스페이스, TLS 포함)은 Redis and Valkey에 있어요.
• AWS는 AWS ElastiCache IAM Authentication을, GCP는 GCP Memorystore IAM Authentication을 보세요.