将 WIF 与 Microsoft Entra ID 结合使用

Azure 工作负载通过出示由 Microsoft Entra ID 颁发的 "JSON Web Token"（JSON Web 令牌），即 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 受众（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"



使用托管标识

当您的工作负载运行在 VM、VM 规模集、App Service、Functions 或 Container Apps 上时，请使用此路径。工作负载从平台的本地令牌端点为其分配的托管标识请求 Entra 颁发的 JWT，然后将该 JWT 与 Anthropic 进行交换。



配置托管标识



配置 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。对于本指南配置的 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 Scale Set：Azure 实例元数据服务（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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Azure"}],
)
print(next(block.text for block in message.content if block.type == "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 中，打开 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。对于本指南配置的 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Azure"}],
)
print(next(block.text for block in message.content if block.type == "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。设置为该完整对象 ID 的 subject_prefix 是等效的（Console 向导会同时设置两者）；切勿使用通配符或部分 GUID 的 subject_prefix，它会匹配比您预期更多的标识。
• 固定 tid 作为纵深防御： 颁发者 URL 已经固定了您的租户，但添加 claims.tid 可以防止颁发者记录后续被编辑时出现的配置漂移。
• 固定受众： 将 audience 设置为您解码后的令牌中的确切 aud 值，以便拒绝为其他应用程序铸造的令牌。
• 为每个托管标识使用单独的规则： 为每个标识创建一条规则，而不是用一条规则授权多个标识，这样您就可以撤销单个工作负载的访问权限而不影响其他工作负载。



后续步骤

• 在工作负载身份联合中查看完整的配置模型。
• 请参阅适用于 AWS、Google Cloud、GitHub Actions 和 Kubernetes 的提供商指南。
• 有关环境变量、配置文件和凭据优先级，请参阅 WIF 参考。