Microsoft Azure AI Foundry 통합

Microsoft Azure AI Foundry를 통해 Claude Code를 배포하면 Azure 네이티브 인프라에서 RBAC 정책, Azure Monitor, Azure Cost Management를 활용한 비용 추적을 사용할 수 있습니다. 이 가이드는 Microsoft Foundry 통합의 전체 설정 과정을 안내합니다.

사전 요구사항

Microsoft Foundry로 Claude Code를 구성하기 전에 다음을 준비해야 합니다.

Microsoft Foundry에 대한 접근 권한이 있는 Azure 구독
Microsoft Foundry 리소스 및 배포를 생성할 RBAC 권한
Azure CLI 설치 및 구성 (선택사항 - 다른 자격증명 획득 방법이 없는 경우에만 필요)

여러 사용자에게 Claude Code를 배포하는 경우, Anthropic이 새 모델을 출시할 때 장애를 방지하기 위해 반드시 모델 버전을 고정해야 합니다.

설정 단계

1단계: Microsoft Foundry 리소스 프로비저닝

먼저 Azure에서 Claude 리소스를 생성합니다.

Microsoft Foundry 포털로 이동합니다.
새 리소스를 생성하고 리소스 이름을 기록해 둡니다.
다음 Claude 모델에 대한 배포를 생성합니다.
- Claude Opus
- Claude Sonnet
- Claude Haiku

배포를 생성할 때 "auto-update to latest" 대신 특정 모델 버전을 선택하세요. 이렇게 하면 예기치 않은 모델 버전 변경으로 인한 장애를 방지할 수 있습니다.

2단계: Azure 자격증명 구성

Microsoft Foundry에 대해 Claude Code는 두 가지 인증 방법을 지원합니다. 보안 요구사항에 가장 적합한 방법을 선택하세요.

옵션 A: API 키 인증

Microsoft Foundry 포털에서 리소스로 이동합니다.
Endpoints and keys 섹션으로 이동합니다.
API Key를 복사합니다.
환경 변수를 설정합니다.

export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

옵션 B: Microsoft Entra ID 인증 (권장)

ANTHROPIC_FOUNDRY_API_KEY가 설정되지 않은 경우, Claude Code는 자동으로 Azure SDK 기본 자격증명 체인을 사용합니다. 이 방식은 로컬 및 원격 워크로드 인증을 위한 다양한 방법을 지원합니다.

로컬 환경에서는 일반적으로 Azure CLI를 사용합니다.

az login

기본 자격증명 체인 순서:

Entra ID 인증 시 Azure SDK는 다음 순서로 자격증명을 시도합니다.

AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET 환경 변수
AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_CERTIFICATE_PATH (인증서 기반)
Azure CLI 자격증명 (az login)
Azure PowerShell 자격증명
Visual Studio Code 자격증명
Managed Identity (Azure 호스팅 환경)

Microsoft Foundry를 사용할 때 인증은 Azure 자격증명을 통해 처리되므로 /login 및 /logout 명령은 비활성화됩니다.

3단계: Claude Code 구성

Microsoft Foundry를 활성화하려면 다음 환경 변수를 설정합니다.

# Microsoft Foundry 통합 활성화
export CLAUDE_CODE_USE_FOUNDRY=1

# Azure 리소스 이름 설정 ({resource}를 실제 리소스 이름으로 교체)
export ANTHROPIC_FOUNDRY_RESOURCE={resource}

# 또는 전체 베이스 URL 직접 제공
# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic

두 방식 중 하나를 선택하여 사용합니다. ANTHROPIC_FOUNDRY_RESOURCE를 설정하면 Claude Code가 자동으로 표준 Azure AI Foundry URL을 구성합니다.

4단계: 모델 버전 고정

모든 배포에 특정 모델 버전을 고정해야 합니다. 버전을 고정하지 않고 모델 별칭(sonnet, opus, haiku)을 사용하면, Anthropic이 업데이트를 출시할 때 Foundry 계정에서 사용 불가능한 새 모델 버전을 사용하려 시도하여 기존 사용자에게 장애가 발생할 수 있습니다.

모델 변수를 1단계에서 생성한 배포 이름과 일치하도록 설정합니다.

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

현재 및 이전 모델 ID에 대한 자세한 내용은 Models overview를 참조합니다.

Azure RBAC 구성

Azure AI User 및 Cognitive Services User 기본 역할에는 Claude 모델을 호출하는 데 필요한 모든 권한이 포함되어 있습니다.

더 제한적인 권한을 위해 다음과 같이 커스텀 역할을 생성할 수 있습니다.

{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/providers/*"
      ]
    }
  ]
}

자세한 내용은 Microsoft Foundry RBAC 문서를 참조합니다.

LLM 게이트웨이를 통한 Foundry 라우팅

조직의 중앙화된 인증 관리나 사용량 추적이 필요한 경우 LLM 게이트웨이를 통해 Foundry 트래픽을 라우팅할 수 있습니다.

# Microsoft Foundry 활성화
export CLAUDE_CODE_USE_FOUNDRY=1

# LLM 게이트웨이 구성
export ANTHROPIC_FOUNDRY_BASE_URL='https://your-llm-gateway.com'
export CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1  # 게이트웨이가 Azure 인증을 처리하는 경우

기업용 프록시를 통해 Foundry 트래픽을 라우팅하는 방법은 다음과 같습니다.

# Microsoft Foundry 활성화
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource
export ANTHROPIC_FOUNDRY_API_KEY=your-api-key  # Entra ID 인증 시 생략 가능

# 기업용 프록시 구성
export HTTPS_PROXY='https://proxy.example.com:8080'

트러블슈팅

"Failed to get token from azureADTokenProvider" 오류

다음 오류가 발생하는 경우:

Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed

해결 방법:

환경에서 Entra ID를 구성하거나 ANTHROPIC_FOUNDRY_API_KEY를 설정합니다.
az login으로 Azure CLI 인증이 완료되었는지 확인합니다.
Managed Identity를 사용하는 경우, 해당 Azure 리소스에 적절한 역할이 할당되었는지 확인합니다.

배포를 찾을 수 없는 오류

Microsoft Foundry 포털에서 배포 이름이 ANTHROPIC_DEFAULT_*_MODEL 변수와 정확히 일치하는지 확인합니다.
배포가 활성 상태인지 확인합니다.
리소스 이름(ANTHROPIC_FOUNDRY_RESOURCE)이 올바른지 확인합니다.

인증 권한 오류

Azure 구독에서 사용자 또는 서비스 주체에 Azure AI User 또는 Cognitive Services User 역할이 할당되었는지 확인합니다.
커스텀 역할을 사용하는 경우, Microsoft.CognitiveServices/accounts/providers/* dataAction이 포함되었는지 확인합니다.

추가 리소스

다음 단계

Microsoft Azure AI Foundry 통합을 완료한 후:

팀 배포: 팀원들에게 Azure 자격증명 설정 및 환경 변수 구성 방법을 안내합니다. Entra ID 인증을 사용하는 경우 각 사용자가 az login을 실행하거나 Managed Identity가 올바르게 구성되어 있는지 확인합니다.
모델 버전 관리: Microsoft Foundry 포털에서 배포된 모델 버전을 정기적으로 검토하고, 테스트 후 계획적으로 버전을 업데이트합니다.
비용 모니터링: Azure Cost Management를 사용하여 팀별 Foundry 사용량을 추적하고 예산 알림을 설정합니다.
보안 감사: Azure Monitor를 활용하여 Claude Code 사용 패턴을 모니터링하고 RBAC 정책을 시행합니다.
엔터프라이즈 배포 전략: 서드파티 통합 및 엔터프라이즈 배포 가이드에서 조직 전체 배포 모범 사례를 참조합니다.