Microsoft Entra ID와 함께 WIF 사용하기

Azure 워크로드는 Microsoft Entra ID에서 발급한 "JSON Web Token"(JSON 웹 토큰), 즉 JWT를 제시한 다음 이를 단기 Anthropic 액세스 토큰으로 교환하여 Claude API에 인증합니다. 설정은 모든 Azure 플랫폼에서 동일한 형태를 따릅니다.

1. 토큰 대상 등록: Microsoft Entra 테넌트에 Claude API 대상을 나타내는 앱 등록을 하나 생성합니다. 테넌트의 모든 워크로드가 이에 대한 Entra 토큰을 요청합니다.
2. 플랫폼에 맞는 ID 설정: VM, VM Scale Sets, App Service, Functions 및 Container Apps에서는 관리 ID를, AKS에서는 Entra Workload Identity를 사용합니다.
3. Anthropic 구성: 테넌트의 Entra 발급자를 등록하고, 서비스 계정을 생성하고, 토큰의 클레임과 일치하는 페더레이션 규칙을 작성합니다.
4. 런타임에 교환: 워크로드는 Entra에서 발급한 토큰을 POST /v1/oauth/token에서 sk-ant-oat01-... Anthropic 액세스 토큰으로 교환하고 이를 사용하여 Claude를 호출합니다.

두 경로 모두에서 Anthropic에 제시하는 토큰은 테넌트별 Entra 발급자와 관리 ID의 객체 ID를 sub 및 oid 클레임에 포함합니다. 워크로드가 해당 토큰을 얻는 방법만 다릅니다. 워크로드가 실행되는 위치에 맞는 섹션을 선택하세요. VM, VM Scale Sets, App Service, Functions 또는 Container Apps의 경우 관리 ID 사용을, AKS의 경우 AKS에서 Entra Workload Identity 사용을 참조하세요.



사전 요구 사항

• WIF 개념에 대한 이해: 서비스 계정, 페더레이션 발급자 및 페더레이션 규칙.
• 관리 ID를 할당할 수 있는 권한(또는 AKS에서 Entra Workload Identity를 구성할 수 있는 권한)이 있는 Azure 구독.
• Microsoft Entra 테넌트에서 앱 등록 및 서비스 주체를 하나 생성할 수 있는 권한(공유 Claude API 대상). Entra는 테넌트에 존재하는 대상에 대해서만 토큰을 발급하므로, 토큰 요청이 성공하려면 토큰 대상 등록 단계가 필요합니다.
• Microsoft Entra 테넌트 ID. Azure 포털의 Microsoft Entra ID → Overview → Tenant ID에서 확인할 수 있습니다.
• Anthropic 조직의 Claude Console에서 서비스 계정, 페더레이션 발급자 및 페더레이션 규칙을 생성할 수 있는 권한.



토큰 대상 등록

Microsoft Entra ID는 요청된 대상이 서비스 주체가 있는 앱 등록으로 테넌트에 존재할 때만 토큰을 발급합니다. Claude API 대상을 나타내는 앱 등록을 하나 생성하세요. 테넌트의 모든 워크로드가 이에 대한 토큰을 요청할 수 있습니다. 이 등록이 없으면 토큰 요청이 "resource not found in tenant" 오류(관리 ID 엔드포인트에서는 AADSTS50001, Entra 토큰 엔드포인트에서는 AADSTS500011)와 함께 실패합니다.

# Claude API 대상(audience)을 나타내는 앱 등록을 생성합니다.
APP_ID=$(az ad app create --display-name claude-api-federation --query appId -o tsv)

# v2.0 액세스 토큰을 요청하고 api://<APP_ID> 식별자 URI를 설정합니다.
az ad app update --id "$APP_ID" \
  --identifier-uris "api://$APP_ID" \
  --set api.requestedAccessTokenVersion=2

# 대상이 테넌트에서 확인되도록 서비스 주체를 생성합니다.
az ad sp create --id "$APP_ID"



관리 ID 사용

워크로드가 VM, VM Scale Set, App Service, Functions 또는 Container Apps에서 실행되는 경우 이 경로를 사용하세요. 워크로드는 플랫폼의 로컬 토큰 엔드포인트에서 할당된 관리 ID에 대한 Entra 발급 JWT를 요청한 다음 해당 JWT를 Anthropic과 교환합니다.



관리 ID 구성



Anthropic 구성

Claude Console에서 Settings → Workload identity를 열고 Connect workload를 클릭한 다음 Microsoft Entra 타일을 선택하세요. 마법사가 발급자 등록, 서비스 계정 생성 및 페더레이션 규칙 생성 과정을 안내합니다.

마법사가 이러한 리소스를 생성합니다. 마법사에 입력하든 Admin API로 전송하든 다음 값을 사용하세요:

페더레이션 발급자: 마법사의 Token issuer 선택기에서 **v2.0 (login.microsoftonline.com)**을 선택하세요. (선택기의 기본값은 v1입니다. 이 기본값은 여전히 v1.0 토큰을 발급하는 이전 등록을 재사용하는 테넌트를 위한 것입니다.) Entra는 테넌트별 발급자 URL에서 OIDC 디스커버리 문서를 게시하므로 디스커버리 모드를 사용하세요. 페더레이션하는 각 Microsoft Entra 테넌트마다 자체 발급자 레코드가 필요합니다.

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

허용되는 수명이 길수록 유출된 Entra 토큰이 더 오래 교환 가능한 상태로 유지됩니다. 토큰이 유출되면 페더레이션 규칙을 비활성화하는 것이 대응 수단입니다. 규칙 범위 지정에 설명된 대로 엄격한 oid 일치는 애초에 토큰을 교환할 수 있는 ID를 제한합니다.

페더레이션 규칙: 관리 ID의 객체 ID와 테넌트 ID를 기준으로 일치시키세요. 이 가이드에서 구성하는 v2.0 토큰의 경우 audience 값은 대상 앱 등록의 클라이언트 ID(토큰 대상 등록의 <APP_ID> GUID)입니다. 디코딩된 토큰의 정확한 aud 값을 사용하세요.

{
  "name": "azure-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "audience": "<APP_ID>",
    "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
}

token_lifetime_seconds는 교환이 반환하는 Anthropic 액세스 토큰의 수명이며 Entra 토큰의 수명이 아닙니다. SDK가 자동으로 새로 고침합니다.



토큰 획득 및 사용

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

샘플은 플랫폼의 토큰 엔드포인트에서 관리 ID 토큰을 가져옵니다. VM 및 VM Scale Sets에서는 IMDS, App Service, Functions 및 Container Apps에서는 IDENTITY_ENDPOINT 서비스입니다. api://<APP_ID> 리소스 값의 <APP_ID>를 토큰 대상 등록의 대상 앱 등록 클라이언트 ID로 바꾸세요.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

# 대상 앱 등록의 식별자 URI (토큰 대상 등록 참조).
AUDIENCE = "api://<APP_ID>"


def fetch_entra_token() -> str:
    """Fetch a managed identity token from the platform's token endpoint."""
    # 사용자 할당 ID가 여러 개인 경우 요청 매개변수에 client_id=<IDENTITY_CLIENT_ID>를
    # 추가하여 하나를 선택하세요.
    if endpoint := os.environ.get("IDENTITY_ENDPOINT"):
        # App Service, Functions, Container Apps
        response = requests.get(
            endpoint,
            headers={"X-IDENTITY-HEADER": os.environ["IDENTITY_HEADER"]},
            params={"api-version": "2019-08-01", "resource": AUDIENCE},
            timeout=5,
        )
    else:
        # VM 또는 VM Scale Set: Azure Instance Metadata Service (IMDS)
        response = requests.get(
            "http://169.254.169.254/metadata/identity/oauth2/token",
            headers={"Metadata": "true"},
            params={"api-version": "2018-02-01", "resource": AUDIENCE},
            timeout=5,
        )
    response.raise_for_status()
    return response.json()["access_token"]


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_entra_token,
        federation_rule_id=os.environ["ANTHROPIC_FEDERATION_RULE_ID"],
        organization_id=os.environ["ANTHROPIC_ORGANIZATION_ID"],
        service_account_id=os.environ["ANTHROPIC_SERVICE_ACCOUNT_ID"],
        workspace_id=os.environ.get("ANTHROPIC_WORKSPACE_ID"),
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Azure"}],
)
print(message.content[0].text)



설정 확인

Azure 리소스에서 토큰 획득 및 사용에 표시된 cURL 교환을 실행하고 POST /v1/oauth/token이 sk-ant-oat01-로 시작하는 access_token과 초 단위의 expires_in 값을 포함한 200을 반환하는지 확인하세요. 400 invalid_grant가 발생하면 Entra 토큰을 디코딩하고(명령은 실패한 교환 문제 해결 참조) 가장 일반적인 Azure 측 원인을 확인하세요.

• 발급자 불일치: 등록된 issuer_url은 토큰의 iss 클레임과 정확히 일치해야 합니다. v2.0 토큰은 https://login.microsoftonline.com/<TENANT_ID>/v2.0을 포함합니다. 디코딩된 ver 클레임이 1.0인 경우 토큰이 v1.0인 경우를 참조하세요.
• 토큰 수명: 관리 ID 토큰은 iat와 exp 사이에 최대 24시간의 간격을 가집니다. 발급자가 여전히 마법사의 7500(또는 1시간 기본값)을 가지고 있는 경우 Anthropic 구성에 설명된 대로 max_jwt_lifetime_seconds를 86400으로 높이세요.
• 대상 불일치: 규칙의 audience는 토큰의 aud와 정확히 일치해야 합니다. 이 가이드에서 구성하는 v2.0 토큰의 경우 대상 앱 등록의 클라이언트 ID입니다.
• 클레임 이름 불일치: 토큰에 없는 클레임을 기준으로 일치시키는 규칙은 절대 통과하지 못합니다. v1.0 토큰은 클라이언트 ID를 azp가 아닌 appid에 포함합니다. 토큰이 v1.0인 경우를 참조하세요.



AKS에서 Entra Workload Identity 사용

워크로드가 AKS 파드에서 실행되는 경우 이 경로를 사용하세요. Entra Workload Identity는 Kubernetes 서비스 계정을 사용자 할당 관리 ID와 페더레이션합니다. Kubernetes는 서비스 계정 토큰(AKS 클러스터의 OIDC 발급자가 서명)을 AZURE_FEDERATED_TOKEN_FILE의 경로에 있는 파드에 프로젝션합니다. 프로젝션된 토큰은 Entra에서 발급한 토큰이 아니므로, 이 페이지에서 설명하는 Entra 중개 경로를 유지하려면 워크로드가 2단계 교환을 수행합니다. 먼저 프로젝션된 토큰을 https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token(페더레이션된 client_credentials 그랜트)에서 Entra 발급 액세스 토큰으로 교환한 다음, 해당 Entra 토큰을 ID 토큰으로 Anthropic SDK에 전달합니다.



Entra Workload Identity 구성



Anthropic 구성

Claude Console에서 Settings → Workload identity를 열고 Connect workload를 클릭한 다음 Microsoft Entra 타일을 선택하세요. 마법사가 발급자 등록, 서비스 계정 생성 및 페더레이션 규칙 생성 과정을 안내합니다.

마법사가 이러한 리소스를 생성합니다. 마법사에 입력하든 Admin API로 전송하든 다음 값을 사용하세요:

페더레이션 발급자: 마법사의 Token issuer 선택기에서 **v2.0 (login.microsoftonline.com)**을 선택하세요. (선택기의 기본값은 v1입니다. 이 기본값은 여전히 v1.0 토큰을 발급하는 이전 등록을 재사용하는 테넌트를 위한 것입니다.) Entra는 테넌트별 발급자 URL에서 OIDC 디스커버리 문서를 게시하므로 디스커버리 모드를 사용하세요. 페더레이션하는 각 Microsoft Entra 테넌트마다 자체 발급자 레코드가 필요합니다.

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

허용되는 수명이 길수록 유출된 Entra 토큰이 더 오래 교환 가능한 상태로 유지됩니다. 토큰이 유출되면 페더레이션 규칙을 비활성화하는 것이 대응 수단입니다. 규칙 범위 지정에 설명된 대로 엄격한 oid 일치는 애초에 토큰을 교환할 수 있는 ID를 제한합니다.

페더레이션 규칙: 관리 ID의 객체 ID와 테넌트 ID를 기준으로 일치시키세요. 이 가이드에서 구성하는 v2.0 토큰의 경우 audience 값은 대상 앱 등록의 클라이언트 ID(토큰 대상 등록의 <APP_ID> GUID)입니다. 디코딩된 토큰의 정확한 aud 값을 사용하세요.

{
  "name": "azure-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "audience": "<APP_ID>",
    "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
}

token_lifetime_seconds는 교환이 반환하는 Anthropic 액세스 토큰의 수명이며 Entra 토큰의 수명이 아닙니다. SDK가 자동으로 새로 고침합니다.



토큰 획득 및 사용

런타임에 파드는 2단계 교환을 수행합니다. Kubernetes 프로젝션 토큰(AZURE_FEDERATED_TOKEN_FILE의 파일)을 페더레이션된 client_credentials 어설션으로 Entra의 토큰 엔드포인트에 보낸 다음, 결과로 얻은 Entra 액세스 토큰을 POST /v1/oauth/token에서 교환합니다. 다음 예제에 표시된 대로 Entra 가져오기를 토큰 제공자 콜러블로 제공하면 각 Anthropic SDK가 두 번째 교환과 새로 고침 루프를 처리합니다. cURL 탭은 원시 흐름을 보여줍니다.

샘플에는 두 개의 서로 다른 클라이언트 ID가 나타납니다. <APP_ID>는 토큰 대상 등록의 대상 앱 등록 클라이언트 ID이며, api://<APP_ID>/.default 범위는 Entra에 해당 대상으로 지정된 토큰을 요청합니다. $AZURE_CLIENT_ID는 웹훅이 주입한 관리 ID의 클라이언트 ID이며 호출자를 식별합니다. 하나를 다른 것으로 대체하지 마세요.

import os
from pathlib import Path

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials


def fetch_entra_token_via_federation() -> str:
    federated_token = Path(os.environ["AZURE_FEDERATED_TOKEN_FILE"]).read_text()
    response = requests.post(
        f"https://login.microsoftonline.com/{os.environ['AZURE_TENANT_ID']}/oauth2/v2.0/token",
        data={
            "client_id": os.environ["AZURE_CLIENT_ID"],
            "grant_type": "client_credentials",
            "scope": "api://<APP_ID>/.default",
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            "client_assertion": federated_token,
        },
        timeout=5,
    )
    response.raise_for_status()
    return response.json()["access_token"]


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_entra_token_via_federation,
        federation_rule_id=os.environ["ANTHROPIC_FEDERATION_RULE_ID"],
        organization_id=os.environ["ANTHROPIC_ORGANIZATION_ID"],
        service_account_id=os.environ["ANTHROPIC_SERVICE_ACCOUNT_ID"],
        workspace_id=os.environ.get("ANTHROPIC_WORKSPACE_ID"),
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Azure"}],
)
print(message.content[0].text)



설정 확인

레이블이 지정된 파드 내부에서 토큰 획득 및 사용에 표시된 cURL 교환을 실행하고 POST /v1/oauth/token이 sk-ant-oat01-로 시작하는 access_token과 초 단위의 expires_in 값을 포함한 200을 반환하는지 확인하세요. 400 invalid_grant가 발생하면 1단계의 Entra 발급 토큰을 디코딩하고(명령은 실패한 교환 문제 해결 참조) 가장 일반적인 Azure 측 원인을 확인하세요.

• 발급자 불일치: 등록된 issuer_url은 토큰의 iss 클레임과 정확히 일치해야 합니다. v2.0 토큰은 https://login.microsoftonline.com/<TENANT_ID>/v2.0을 포함합니다. 디코딩된 ver 클레임이 1.0인 경우 토큰이 v1.0인 경우를 참조하세요.
• 토큰 수명: 테넌트 토큰 수명 정책 또는 CAE가 client_credentials 토큰을 7500초 이상으로 연장하는 경우 Anthropic 구성에 설명된 대로 발급자의 max_jwt_lifetime_seconds를 높이세요.
• 대상 불일치: 규칙의 audience는 토큰의 aud와 정확히 일치해야 합니다. 이 가이드에서 구성하는 v2.0 토큰의 경우 대상 앱 등록의 클라이언트 ID입니다.
• 클레임 이름 불일치: 토큰에 없는 클레임을 기준으로 일치시키는 규칙은 절대 통과하지 못합니다. v1.0 토큰은 클라이언트 ID를 azp가 아닌 appid에 포함합니다. 토큰이 v1.0인 경우를 참조하세요.



토큰이 v1.0인 경우

이 가이드는 대상 앱 등록을 api.requestedAccessTokenVersion: 2로 구성하므로 표시되는 모든 토큰은 v2.0입니다. requestedAccessTokenVersion을 설정하지 않은 기존 등록을 재사용하는 경우 Entra는 대신 v1.0 토큰을 발급합니다. 샘플 토큰을 디코딩하고 ver 클레임을 확인하세요. 1.0인 경우 네 가지가 변경됩니다.

• 발급자: iss 클레임은 https://login.microsoftonline.com/<TENANT_ID>/v2.0 대신 https://sts.windows.net/<TENANT_ID>/입니다. 토큰의 iss 클레임에 있는 그대로 발급자 URL을 등록하세요. 두 URL은 동일한 JWKS를 공유하므로 디스커버리 모드가 둘 다에 대해 작동합니다.
• 마법사 선택기: Connect workload 마법사의 Token issuer 선택기에서 v2.0 (login.microsoftonline.com) 대신 **v1 (sts.windows.net)**을 선택하세요.
• 대상: aud 클레임은 등록의 클라이언트 ID가 아니라 resource로 전달한 식별자 URI(예: api://<APP_ID>)입니다. 페더레이션 규칙의 audience를 디코딩된 토큰의 정확한 aud 값으로 설정하세요.
• 클라이언트 ID 클레임: 호출 ID의 클라이언트 ID는 azp가 아닌 appid에 나타납니다. 두 클레임은 동일한 토큰에 함께 나타나지 않으므로 azp를 기준으로 일치시키는 규칙은 v1.0 토큰에 대해 절대 통과하지 못합니다.

oid, sub 및 tid 클레임은 두 버전에서 동일한 값을 가지므로 이 가이드의 나머지 부분은 변경 없이 적용됩니다.



규칙 범위 지정

페더레이션 규칙은 claims 맵에 추가로(또는 대신) subject_prefix로 토큰의 주체를 일치시킬 수 있습니다. 필드가 결합되는 방식은 규칙 일치 의미론을 참조하세요. 이러한 ID에 대한 Entra sub 값은 고정 길이의 정규 GUID이므로 전체 36자 객체 ID를 포함하는 subject_prefix는 해당 주체만 일치시킵니다. 이는 일반적인 subject_prefix의 속성이 아니라 Entra의 주체 형식의 속성입니다.

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

• oid를 정확한 값으로 일치: claims.oid를 관리 ID의 전체 객체 ID로 설정하세요. 해당 전체 객체 ID로 설정된 subject_prefix는 동일합니다(Console 마법사는 둘 다 설정함). 의도한 것보다 더 많은 ID와 일치하는 와일드카드 또는 부분 GUID subject_prefix는 절대 사용하지 마세요.
• 심층 방어로 tid 고정: 발급자 URL이 이미 테넌트를 고정하지만, claims.tid를 추가하면 나중에 발급자 레코드가 편집될 경우 구성 드리프트를 방지합니다.
• 대상 고정: 다른 애플리케이션용으로 발급된 토큰이 거부되도록 audience를 디코딩된 토큰의 정확한 aud 값으로 설정하세요.
• 각 관리 ID에 대해 별도의 규칙 사용: 여러 ID를 승인하는 하나의 규칙 대신 각 ID에 대해 하나의 규칙을 생성하여 다른 워크로드에 영향을 주지 않고 단일 워크로드의 액세스를 취소할 수 있도록 하세요.



다음 단계

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