Microsoft Azure에서 WIF 사용하기

Azure 워크로드는 Microsoft Entra ID에서 발급한 "JSON Web Token"(JSON 웹 토큰), 즉 JWT를 제시한 다음 이를 단기 Anthropic 액세스 토큰으로 교환하여 Claude API에 인증합니다. Entra에서 발급한 토큰을 얻는 일반적인 방법은 두 가지입니다.

• 관리 ID(VM, App Service, Functions, Container Apps): 워크로드가 http://169.254.169.254/metadata/identity/oauth2/token에서 Azure Instance Metadata Service(IMDS)를 호출하고 할당된 ID에 대한 JWT를 받습니다.
• Entra Workload Identity(AKS 파드): Kubernetes가 서비스 계정 토큰(AKS 클러스터의 OIDC 발급자가 서명)을 AZURE_FEDERATED_TOKEN_FILE에 지정된 경로의 파드에 프로젝션합니다. 워크로드는 해당 토큰을 Entra에서 교환하여 Entra에서 발급한 액세스 토큰을 받습니다.

두 경우 모두 Anthropic에 제시하는 Entra 발급 토큰은 테넌트별 Entra 발급자(아래 Anthropic 구성 단계에서 등록할 정확한 URL을 보여줍니다)와 sub 및 oid 클레임에 관리 ID의 객체 ID를 포함합니다. 해당 발급자를 Anthropic에 한 번 등록하고, 예상되는 클레임과 일치하는 페더레이션 규칙을 작성하면, 워크로드가 런타임에 Entra 토큰을 sk-ant-oat01-... 액세스 토큰으로 교환합니다.

사전 요구 사항

• WIF 개념에 대한 이해: 서비스 계정, 페더레이션 발급자, 페더레이션 규칙.
• 관리 ID를 할당할 권한(또는 AKS에서 Entra Workload Identity를 구성할 권한)이 있는 Azure 구독.
• Microsoft Entra 테넌트 ID. Azure 포털의 Microsoft Entra ID → Overview → Tenant ID에서 확인할 수 있습니다.
• Anthropic 조직의 Claude Console에서 서비스 계정, 페더레이션 발급자, 페더레이션 규칙을 생성할 권한.

Azure 구성

Azure가 토큰을 발급할 ID를 설정합니다. 워크로드가 실행되는 위치에 맞는 경로를 선택하세요.

토큰 클레임

관리 ID에 대한 Entra 발급 토큰은 다음 클레임을 포함합니다.

{
  "iss": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
  "sub": "9f8e7d6c-1a2b-3c4d-5e6f-...",
  "aud": "https://api.anthropic.com",
  "oid": "9f8e7d6c-1a2b-3c4d-5e6f-...",
  "tid": "<TENANT_ID>",
  "azp": "<CLIENT_ID>",
  "exp": 1775527120
}

sub와 oid는 동일합니다(관리 ID의 객체 ID). azp는 애플리케이션 또는 클라이언트 ID입니다. 특정 ID 하나를 승인하려면 oid로 매칭하고, 애플리케이션 등록과 연결된 모든 ID를 승인하려면 azp로 매칭하세요. tid 클레임은 테넌트 ID를 반복합니다. 발급자 URL이 이미 테넌트를 고정하므로 이를 매칭하는 것은 심층 방어입니다.

Anthropic 구성

설정 안내를 따라 Claude Console에서 페더레이션 발급자를 등록하고, Anthropic 서비스 계정을 생성하고, 페더레이션 규칙을 생성하세요. Console에서 OIDC 공급자 옵션을 선택하고 다음에 나오는 Entra 관련 값을 입력하세요.

페더레이션 발급자: Entra는 테넌트별 발급자 URL에서 OIDC 디스커버리 문서를 게시하므로 디스커버리 모드를 사용하세요. 페더레이션하는 각 Azure 테넌트마다 자체 발급자 레코드가 필요합니다.

{
  "name": "azure-prod-tenant",
  "issuer_url": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
  "jwks_source": "discovery"
}

페더레이션 규칙: 관리 ID의 객체 ID와 테넌트 ID로 매칭합니다.

{
  "name": "azure-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "audience": "https://api.anthropic.com",
    "claims": {
      "oid": "9f8e7d6c-1a2b-3c4d-5e6f-...",
      "tid": "<TENANT_ID>"
    }
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

토큰 획득 및 사용

런타임에 워크로드는 Entra 토큰을 가져와 POST /v1/oauth/token에서 교환하고, 반환된 베어러 토큰을 사용하여 Claude를 호출합니다. 다음 예제에서 보듯이 토큰 공급자 콜러블을 제공하면 각 Anthropic SDK가 교환 및 갱신 루프를 처리합니다. cURL 탭은 원시 흐름을 보여줍니다.

Entra Workload Identity를 사용하는 AKS에서

AKS에서 AZURE_FEDERATED_TOKEN_FILE에 있는 파일은 Entra에서 발급한 토큰이 아니라 클러스터의 OIDC 발급자가 서명한 Kubernetes 프로젝션 서비스 계정 토큰입니다. 이 페이지에서 설명하는 Entra 중개 경로를 유지하려면 먼저 해당 토큰을 https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token(페더레이션 client_credentials 그랜트)에서 교환한 다음, 결과로 받은 Entra 액세스 토큰을 ID 토큰으로 Anthropic SDK에 전달하세요.

또는 AKS 클러스터의 OIDC 발급자를 Anthropic에 직접 등록하고 Entra 단계를 건너뛸 수 있습니다. 해당 패턴은 Kubernetes를 참조하세요.

설정 확인

Azure 리소스에서 앞서 보여준 cURL 교환을 실행하고 POST /v1/oauth/token이 sk-ant-oat01-로 시작하는 access_token과 초 단위의 expires_in 값을 포함한 200을 반환하는지 확인하세요. 400 invalid_grant가 발생하면 실패한 교환 문제 해결을 참조하세요. Azure 측에서 가장 흔한 원인은 등록한 issuer_url과 디코딩된 토큰의 iss 클레임 간의 불일치입니다. 이 둘은 정확히 일치해야 합니다. 관리 ID 토큰의 경우 iss 값은 https://login.microsoftonline.com/<TENANT_ID>/v2.0 또는 https://sts.windows.net/<TENANT_ID>/입니다.

규칙 범위 지정

규칙의 match 블록을 사용 사례에 맞는 가장 좁은 범위로 제한하세요.

• oid를 정확한 값으로 매칭: claims.oid를 관리 ID의 전체 객체 ID로 설정하고 Azure 토큰에는 절대 subject_prefix를 사용하지 마세요.
• 심층 방어로 tid 고정: 발급자 URL이 이미 테넌트를 고정하지만, claims.tid를 추가하면 나중에 발급자 레코드가 편집될 경우 구성 드리프트를 방지할 수 있습니다.
• 대상(audience) 고정: audience를 https://api.anthropic.com으로 설정하여 다른 리소스용으로 발급된 토큰이 거부되도록 하세요.
• 관리 ID별로 별도의 규칙 사용: 여러 ID를 승인하는 하나의 규칙 대신 ID당 하나의 규칙을 생성하여, 다른 워크로드에 영향을 주지 않고 단일 워크로드의 액세스를 취소할 수 있도록 하세요.

다음 단계

• Workload Identity Federation에서 전체 구성 모델을 검토하세요.
• AWS, Google Cloud, GitHub Actions, Kubernetes에 대한 공급자 가이드를 참조하세요.
• 환경 변수, 프로필 파일, 자격 증명 우선순위에 대해서는 WIF 참조를 참조하세요.