搭配 Microsoft Entra ID 使用 WIF

Azure 工作負載透過出示由 Microsoft Entra ID 簽發的「JSON Web Token」（JSON 網路權杖），即 JWT，然後將其交換為短期有效的 Anthropic 存取權杖，來向 Claude API 進行驗證。無論在哪個 Azure 平台上，設定流程都遵循相同的架構：

1. 註冊權杖受眾： 在您的 Microsoft Entra 租用戶中建立一個應用程式註冊，以代表 Claude API 受眾。租用戶中的每個工作負載都會為其請求 Entra 權杖。
2. 為您的平台設定身分識別： 在 VM、VM 擴展集、App Service、Functions 和 Container Apps 上使用受控識別，或在 AKS 上使用 Entra Workload Identity。
3. 設定 Anthropic： 註冊您租用戶的 Entra 簽發者、建立服務帳戶，並撰寫符合權杖宣告的聯合規則。
4. 執行階段交換： 您的工作負載在 POST /v1/oauth/token 將其 Entra 簽發的權杖交換為 sk-ant-oat01-... Anthropic 存取權杖，並使用該權杖呼叫 Claude。

在這兩種路徑中，您向 Anthropic 出示的權杖都會在 sub 和 oid 宣告中攜帶您租用戶專屬的 Entra 簽發者以及受控識別的物件 ID；唯一的差異在於工作負載取得該權杖的方式。請根據您的工作負載執行位置選擇對應的章節：VM、VM 擴展集、App Service、Functions 或 Container Apps 請參閱使用受控識別；AKS 請參閱在 AKS 上使用 Entra Workload Identity。



先決條件

• 熟悉 WIF 概念：服務帳戶、聯合簽發者和聯合規則。
• 具有指派受控識別（或在 AKS 上設定 Entra Workload Identity）權限的 Azure 訂用帳戶。
• 在您的 Microsoft Entra 租用戶中建立一個應用程式註冊和服務主體（共用的 Claude API 受眾）的權限。Entra 只會為租用戶中存在的受眾簽發權杖，因此在任何權杖請求成功之前，必須先完成註冊權杖受眾步驟。
• 您的 Microsoft Entra 租用戶 ID。可在 Azure 入口網站的 Microsoft Entra ID → 概觀 → 租用戶 ID 下找到。
• 在 Claude Console 中為您的 Anthropic 組織建立服務帳戶、聯合簽發者和聯合規則的權限。



註冊權杖受眾

Microsoft Entra ID 只有在所請求的受眾以具有服務主體的應用程式註冊形式存在於您的租用戶中時，才會簽發權杖。請建立一個應用程式註冊來代表 Claude API 受眾；租用戶中的每個工作負載都可以為其請求權杖。若沒有此註冊，權杖請求會失敗並顯示「在租用戶中找不到資源」錯誤（受控識別端點回傳 AADSTS50001，Entra 權杖端點回傳 AADSTS500011）。

# 建立代表 Claude API 受眾的應用程式註冊。
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"



使用受控識別

當您的工作負載在 VM、VM 擴展集、App Service、Functions 或 Container Apps 上執行時，請使用此路徑。工作負載會從平台的本機權杖端點為其指派的受控識別請求 Entra 簽發的 JWT，然後將該 JWT 與 Anthropic 進行交換。



設定受控識別



設定 Anthropic

在 Claude Console 中，開啟 設定 → 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。對於本指南設定的 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 分頁顯示原始流程。

這些範例會從平台的權杖端點擷取受控識別權杖：VM 和 VM 擴展集上的 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."""
    # 若有多個使用者指派的身分識別，請在請求參數中加入 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 擴展集：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 傳回 200，其中包含以 sk-ant-oat01- 開頭的 access_token 以及以秒為單位的 expires_in 值。若出現 400 invalid_grant，請解碼 Entra 權杖（指令請參閱疑難排解失敗的交換），並檢查最常見的 Azure 端原因：

• 簽發者不符： 註冊的 issuer_url 必須與權杖的 iss 宣告完全相符。v2.0 權杖攜帶 https://login.microsoftonline.com/<TENANT_ID>/v2.0；如果解碼後的 ver 宣告為 1.0，請參閱如果您的權杖是 v1.0。
• 權杖存留期： 受控識別權杖在 iat 和 exp 之間最長可達 24 小時。如果簽發者仍使用精靈的 7500（或 1 小時預設值），請依照設定 Anthropic 所述將 max_jwt_lifetime_seconds 提高到 86400。
• 受眾不符： 規則的 audience 必須與權杖的 aud 完全相符：對於本指南設定的 v2.0 權杖，即為受眾應用程式註冊的用戶端 ID。
• 宣告名稱不符： 比對權杖未攜帶之宣告的規則永遠不會通過。v1.0 權杖在 appid 中攜帶用戶端 ID，而非 azp；請參閱如果您的權杖是 v1.0。



在 AKS 上使用 Entra Workload Identity

當您的工作負載在 AKS Pod 中執行時，請使用此路徑。Entra Workload Identity 會將 Kubernetes 服務帳戶與使用者指派的受控識別聯合：Kubernetes 會將服務帳戶權杖（由 AKS 叢集的 OIDC 簽發者簽署）投影到 Pod 中 AZURE_FEDERATED_TOKEN_FILE 所指的路徑。該投影權杖並非 Entra 簽發的權杖，因此若要維持本頁所述的 Entra 中介路徑，工作負載需執行兩段式交換：首先在 https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token（聯合 client_credentials 授權）兌換投影權杖以取得 Entra 簽發的存取權杖，然後將該 Entra 權杖作為身分識別權杖傳遞給 Anthropic SDK。



設定 Entra Workload Identity



設定 Anthropic

在 Claude Console 中，開啟 設定 → 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。對於本指南設定的 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 會為您重新整理。



取得並使用權杖

在執行階段，Pod 會執行兩段式交換：將 Kubernetes 投影的權杖（AZURE_FEDERATED_TOKEN_FILE 所指的檔案）作為聯合 client_credentials 斷言傳送到 Entra 的權杖端點，然後在 POST /v1/oauth/token 交換所產生的 Entra 存取權杖。當您將 Entra 擷取作為權杖提供者可呼叫物件提供時，每個 Anthropic SDK 都會處理第二次交換和重新整理迴圈，如以下範例所示。cURL 分頁顯示原始流程。

範例中出現兩個不同的用戶端 ID。<APP_ID> 是來自註冊權杖受眾的受眾應用程式註冊用戶端 ID；範圍 api://<APP_ID>/.default 會向 Entra 請求針對該受眾的權杖。$AZURE_CLIENT_ID 是受控識別的用戶端 ID，由 Webhook 注入，用於識別呼叫端。請勿將兩者互相替換。

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)



驗證設定

從已加標籤的 Pod 內部，執行取得並使用權杖中所示的 cURL 交換，並確認 POST /v1/oauth/token 傳回 200，其中包含以 sk-ant-oat01- 開頭的 access_token 以及以秒為單位的 expires_in 值。若出現 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 權杖在 appid 中攜帶用戶端 ID，而非 azp；請參閱如果您的權杖是 v1.0。



如果您的權杖是 v1.0

本指南將受眾應用程式註冊設定為 api.requestedAccessTokenVersion: 2，因此所顯示的每個權杖都是 v2.0。如果您重複使用未設定 requestedAccessTokenVersion 的現有註冊，Entra 會改為簽發 v1.0 權杖。請解碼範例權杖並檢查其 ver 宣告；如果是 1.0，則有四項變更：

• 簽發者： iss 宣告為 https://sts.windows.net/<TENANT_ID>/，而非 https://login.microsoftonline.com/<TENANT_ID>/v2.0。請完全依照您權杖的 iss 宣告所攜帶的內容註冊簽發者 URL。這兩個 URL 共用相同的 JWKS，因此探索模式對兩者都適用。
• 精靈選擇器： 在 Connect workload 精靈的 Token issuer 選擇器中選擇 v1 (sts.windows.net)，而非 v2.0 (login.microsoftonline.com)。
• 受眾： aud 宣告是您作為 resource 傳遞的識別碼 URI（例如 api://<APP_ID>），而非註冊的用戶端 ID。請將聯合規則的 audience 設為您解碼權杖中的確切 aud 值。
• 用戶端 ID 宣告： 呼叫端身分識別的用戶端 ID 出現在 appid 中，而非 azp。這兩個宣告永遠不會出現在同一個權杖中，因此比對 azp 的規則對 v1.0 權杖永遠不會通過。

oid、sub 和 tid 宣告在兩個版本中攜帶相同的值，因此本指南的其餘部分可原樣適用。



限定規則範圍

聯合規則除了（或取代）claims 對應之外，還可以使用 subject_prefix 比對權杖的主體；欄位如何組合請參閱規則比對語意。這些身分識別的 Entra sub 值是固定長度的標準 GUID，因此包含完整 36 字元物件 ID 的 subject_prefix 只會比對該主體；這是 Entra 主體格式的特性，而非 subject_prefix 的一般特性。

請將規則的 match 區塊鎖定在符合您使用案例的最窄範圍：

• 以精確值比對 oid： 將 claims.oid 設為受控識別的完整物件 ID。將 subject_prefix 設為該完整物件 ID 是等效的（Console 精靈會同時設定兩者）；切勿使用萬用字元或部分 GUID 的 subject_prefix，這會比對到超出您預期的身分識別。
• 固定 tid 作為深度防禦： 簽發者 URL 已經固定了您的租用戶，但加入 claims.tid 可在日後簽發者記錄被編輯時防範設定偏移。
• 固定受眾： 將 audience 設為您解碼權杖中的確切 aud 值，以拒絕為其他應用程式鑄造的權杖。
• 為每個受控識別使用獨立的規則： 為每個身分識別建立一個規則，而非建立一個授權多個身分識別的規則，如此您便可撤銷單一工作負載的存取權而不影響其他工作負載。



後續步驟

• 在 Workload Identity Federation 中檢閱完整的設定模型。
• 請參閱適用於 AWS、Google Cloud、GitHub Actions 和 Kubernetes 的供應商指南。
• 有關環境變數、設定檔和認證優先順序，請參閱 WIF 參考。