Use WIF com Microsoft Entra ID

As cargas de trabalho do Azure se autenticam na API do Claude apresentando um "JSON Web Token" (token web JSON), ou JWT, emitido pelo Microsoft Entra ID, e depois trocando-o por um token de acesso Anthropic de curta duração. A configuração segue o mesmo formato em todas as plataformas Azure:

1. Registre a audiência do token: Crie um registro de aplicativo no seu tenant do Microsoft Entra para representar a audiência da API do Claude. Toda carga de trabalho no tenant solicita tokens do Entra para ele.
2. Configure a identidade para sua plataforma: Uma identidade gerenciada em VMs, VM Scale Sets, App Service, Functions e Container Apps, ou o Entra Workload Identity no AKS.
3. Configure a Anthropic: Registre o emissor Entra do seu tenant, crie uma conta de serviço e escreva uma regra de federação que corresponda às claims do token.
4. Troque em tempo de execução: Sua carga de trabalho troca seu token emitido pelo Entra em POST /v1/oauth/token por um token de acesso Anthropic sk-ant-oat01-... e chama Claude com ele.

Em ambos os caminhos, o token que você apresenta à Anthropic carrega o emissor Entra específico do seu tenant e o ID de objeto da identidade gerenciada nas claims sub e oid; apenas a forma como a carga de trabalho obtém esse token difere. Escolha a seção correspondente a onde sua carga de trabalho é executada: Use uma identidade gerenciada para VMs, VM Scale Sets, App Service, Functions ou Container Apps; Use o Entra Workload Identity no AKS para AKS.



Pré-requisitos

• Familiaridade com os conceitos de WIF: contas de serviço, emissores de federação e regras de federação.
• Uma assinatura do Azure com permissão para atribuir identidades gerenciadas (ou configurar o Entra Workload Identity no AKS).
• Permissão para criar um registro de aplicativo e um service principal no seu tenant do Microsoft Entra (a audiência compartilhada da API do Claude). O Entra só emite tokens para uma audiência que existe no tenant, portanto a etapa Registre a audiência do token é necessária antes que qualquer solicitação de token tenha sucesso.
• O ID do seu tenant do Microsoft Entra. Encontre-o no portal do Azure em Microsoft Entra ID → Overview → Tenant ID.
• Permissão para criar contas de serviço, emissores de federação e regras de federação no Claude Console para sua organização Anthropic.



Registre a audiência do token

O Microsoft Entra ID só emite um token quando a audiência solicitada existe no seu tenant como um registro de aplicativo com um service principal. Crie um registro de aplicativo para representar a audiência da API do Claude; toda carga de trabalho no tenant pode solicitar tokens para ele. Sem esse registro, as solicitações de token falham com um erro "resource not found in tenant" (AADSTS50001 dos endpoints de identidade gerenciada, AADSTS500011 do endpoint de token do Entra).

# Crie o registro de aplicativo que representa o público (audience) da API do Claude.
APP_ID=$(az ad app create --display-name claude-api-federation --query appId -o tsv)

# Solicite tokens de acesso v2.0 e defina o URI identificador api://<APP_ID>.
az ad app update --id "$APP_ID" \
  --identifier-uris "api://$APP_ID" \
  --set api.requestedAccessTokenVersion=2

# Crie o service principal para que o público (audience) seja resolvido no seu tenant.
az ad sp create --id "$APP_ID"



Use uma identidade gerenciada

Use este caminho quando sua carga de trabalho é executada em uma VM, um VM Scale Set, App Service, Functions ou Container Apps. A carga de trabalho solicita um JWT emitido pelo Entra para sua identidade gerenciada atribuída a partir do endpoint de token local da plataforma e, em seguida, troca esse JWT com a Anthropic.



Configure a identidade gerenciada



Configure a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco Microsoft Entra. O assistente orienta você no registro do emissor, na criação de uma conta de serviço e na criação de uma regra de federação.

O assistente cria esses recursos para você. Use os seguintes valores, seja inserindo-os no assistente ou enviando-os para a Admin API:

Emissor de federação: Escolha v2.0 (login.microsoftonline.com) no seletor Token issuer do assistente. (O seletor tem v1 como padrão; esse padrão existe para tenants que reutilizam registros mais antigos que ainda emitem tokens v1.0.) O Entra publica um documento de descoberta OIDC na URL do emissor por tenant, portanto use o modo de descoberta. Cada tenant do Microsoft Entra que você federar precisa de seu próprio registro de emissor.

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

Um tempo de vida aceito mais longo significa que um token do Entra vazado permanece trocável por mais tempo. Se um token vazar, a alavanca é desabilitar a regra de federação; uma correspondência estrita de oid limita quais identidades podem trocar um token em primeiro lugar, conforme descrito em Delimite o escopo da sua regra.

Regra de federação: Faça a correspondência com o ID de objeto da identidade gerenciada e o ID do seu tenant. Para os tokens v2.0 que este guia configura, o valor de audience é o client ID do registro de aplicativo da audiência (o GUID <APP_ID> de Registre a audiência do token). Use o valor exato de aud do seu token decodificado.

{
  "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 é o tempo de vida do token de acesso Anthropic que a troca retorna, não do token do Entra; o SDK o atualiza para você.



Adquira e use o token

Em tempo de execução, sua carga de trabalho busca seu token do Entra, troca-o em POST /v1/oauth/token e usa o token bearer retornado para chamar Claude. Cada SDK da Anthropic lida com a troca e o ciclo de atualização quando você fornece um callable provedor de token, como mostrado nos exemplos a seguir. A aba cURL mostra o fluxo bruto.

Os exemplos buscam o token de identidade gerenciada no endpoint de token da plataforma: IMDS em VMs e VM Scale Sets, ou o serviço IDENTITY_ENDPOINT no App Service, Functions e Container Apps. Substitua <APP_ID> no valor de recurso api://<APP_ID> pelo client ID do registro de aplicativo da audiência de Registre a audiência do token.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

# O URI identificador do registro de aplicativo da audiência (consulte Registrar a audiência do token).
AUDIENCE = "api://<APP_ID>"


def fetch_entra_token() -> str:
    """Fetch a managed identity token from the platform's token endpoint."""
    # Com várias identidades atribuídas pelo usuário, adicione client_id=<IDENTITY_CLIENT_ID>
    # aos parâmetros da requisição para selecionar uma.
    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 ou 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-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"))



Verifique a configuração

A partir do seu recurso do Azure, execute a troca cURL mostrada em Adquira e use o token e confirme que POST /v1/oauth/token retorna um 200 com um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Em caso de 400 invalid_grant, decodifique o token do Entra (consulte Solucionar problemas de uma troca com falha para o comando) e verifique as causas mais comuns do lado do Azure:

• Incompatibilidade de emissor: O issuer_url registrado deve corresponder exatamente à claim iss do token. Um token v2.0 carrega https://login.microsoftonline.com/<TENANT_ID>/v2.0; se a claim ver decodificada for 1.0, consulte Se seus tokens forem v1.0.
• Tempo de vida do token: Tokens de identidade gerenciada carregam até 24 horas entre iat e exp. Se o emissor ainda tiver o 7500 do assistente (ou o padrão de 1 hora), aumente max_jwt_lifetime_seconds para 86400 conforme descrito em Configure a Anthropic.
• Incompatibilidade de audiência: O audience da regra deve ser exatamente igual ao aud do token: o client ID do registro de aplicativo da audiência para os tokens v2.0 que este guia configura.
• Incompatibilidade de nome de claim: Uma regra que faz correspondência com uma claim que o token não carrega nunca passa. Tokens v1.0 carregam o client ID em appid, não em azp; consulte Se seus tokens forem v1.0.



Use o Entra Workload Identity no AKS

Use este caminho quando sua carga de trabalho é executada em um pod do AKS. O Entra Workload Identity federa uma conta de serviço do Kubernetes com uma identidade gerenciada atribuída pelo usuário: o Kubernetes projeta um token de conta de serviço (assinado pelo emissor OIDC do cluster AKS) no pod no caminho em AZURE_FEDERATED_TOKEN_FILE. Esse token projetado não é um token emitido pelo Entra, portanto, para permanecer no caminho mediado pelo Entra descrito nesta página, a carga de trabalho realiza uma troca em dois saltos: primeiro ela resgata o token projetado em https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token (concessão client_credentials federada) por um token de acesso emitido pelo Entra, depois passa esse token do Entra para o SDK da Anthropic como o token de identidade.



Configure o Entra Workload Identity



Configure a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco Microsoft Entra. O assistente orienta você no registro do emissor, na criação de uma conta de serviço e na criação de uma regra de federação.

O assistente cria esses recursos para você. Use os seguintes valores, seja inserindo-os no assistente ou enviando-os para a Admin API:

Emissor de federação: Escolha v2.0 (login.microsoftonline.com) no seletor Token issuer do assistente. (O seletor tem v1 como padrão; esse padrão existe para tenants que reutilizam registros mais antigos que ainda emitem tokens v1.0.) O Entra publica um documento de descoberta OIDC na URL do emissor por tenant, portanto use o modo de descoberta. Cada tenant do Microsoft Entra que você federar precisa de seu próprio registro de emissor.

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

Um tempo de vida aceito mais longo significa que um token do Entra vazado permanece trocável por mais tempo. Se um token vazar, a alavanca é desabilitar a regra de federação; uma correspondência estrita de oid limita quais identidades podem trocar um token em primeiro lugar, conforme descrito em Delimite o escopo da sua regra.

Regra de federação: Faça a correspondência com o ID de objeto da identidade gerenciada e o ID do seu tenant. Para os tokens v2.0 que este guia configura, o valor de audience é o client ID do registro de aplicativo da audiência (o GUID <APP_ID> de Registre a audiência do token). Use o valor exato de aud do seu token decodificado.

{
  "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 é o tempo de vida do token de acesso Anthropic que a troca retorna, não do token do Entra; o SDK o atualiza para você.



Adquira e use o token

Em tempo de execução, o pod realiza a troca em dois saltos: ele envia o token projetado pelo Kubernetes (o arquivo em AZURE_FEDERATED_TOKEN_FILE) para o endpoint de token do Entra como uma asserção client_credentials federada, depois troca o token de acesso do Entra resultante em POST /v1/oauth/token. Cada SDK da Anthropic lida com a segunda troca e o ciclo de atualização quando você fornece a busca do Entra como um callable provedor de token, como mostrado nos exemplos a seguir. A aba cURL mostra o fluxo bruto.

Dois client IDs diferentes aparecem nos exemplos. <APP_ID> é o client ID do registro de aplicativo da audiência de Registre a audiência do token; o escopo api://<APP_ID>/.default pede ao Entra um token endereçado a essa audiência. $AZURE_CLIENT_ID é o client ID da identidade gerenciada, injetado pelo webhook, e identifica o chamador. Não substitua um pelo outro.

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"))



Verifique a configuração

De dentro de um pod rotulado, execute a troca cURL mostrada em Adquira e use o token e confirme que POST /v1/oauth/token retorna um 200 com um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Em caso de 400 invalid_grant, decodifique o token emitido pelo Entra da etapa 1 (consulte Solucionar problemas de uma troca com falha para o comando) e verifique as causas mais comuns do lado do Azure:

• Incompatibilidade de emissor: O issuer_url registrado deve corresponder exatamente à claim iss do token. Um token v2.0 carrega https://login.microsoftonline.com/<TENANT_ID>/v2.0; se a claim ver decodificada for 1.0, consulte Se seus tokens forem v1.0.
• Tempo de vida do token: Se uma política de tempo de vida de token do tenant ou o CAE estender o token client_credentials além de 7500 segundos, aumente o max_jwt_lifetime_seconds do emissor conforme descrito em Configure a Anthropic.
• Incompatibilidade de audiência: O audience da regra deve ser exatamente igual ao aud do token: o client ID do registro de aplicativo da audiência para os tokens v2.0 que este guia configura.
• Incompatibilidade de nome de claim: Uma regra que faz correspondência com uma claim que o token não carrega nunca passa. Tokens v1.0 carregam o client ID em appid, não em azp; consulte Se seus tokens forem v1.0.



Se seus tokens forem v1.0

Este guia configura o registro de aplicativo da audiência com api.requestedAccessTokenVersion: 2, portanto todos os tokens que ele mostra são v2.0. Se você reutilizar um registro existente que deixa requestedAccessTokenVersion não definido, o Entra emite tokens v1.0 em vez disso. Decodifique um token de exemplo e verifique sua claim ver; se for 1.0, quatro coisas mudam:

• Emissor: A claim iss é https://sts.windows.net/<TENANT_ID>/ em vez de https://login.microsoftonline.com/<TENANT_ID>/v2.0. Registre a URL do emissor exatamente como a claim iss do seu token a carrega. As duas URLs compartilham o mesmo JWKS, portanto o modo de descoberta funciona para qualquer uma.
• Seletor do assistente: Escolha v1 (sts.windows.net) no seletor Token issuer do assistente Connect workload em vez de v2.0 (login.microsoftonline.com).
• Audiência: A claim aud é o URI identificador que você passou como resource (por exemplo, api://<APP_ID>), não o client ID do registro. Defina o audience da regra de federação com o valor exato de aud do seu token decodificado.
• Claim de client ID: O client ID da identidade chamadora aparece em appid, não em azp. As duas claims nunca aparecem no mesmo token, portanto uma regra que faz correspondência com azp nunca passa contra um token v1.0.

As claims oid, sub e tid carregam os mesmos valores em ambas as versões, portanto o restante deste guia se aplica sem alterações.



Delimite o escopo da sua regra

Uma regra de federação pode corresponder ao subject do token com subject_prefix além do (ou em vez do) mapa claims; consulte Semântica de correspondência de regras para saber como os campos se combinam. Os valores de sub do Entra para essas identidades são GUIDs canônicos de comprimento fixo, portanto um subject_prefix contendo o ID de objeto completo de 36 caracteres corresponde apenas a esse subject; essa é uma propriedade do formato de subject do Entra, não de subject_prefix em geral.

Restrinja o bloco match da regra ao escopo mais estreito que se adequa ao seu caso de uso:

• Faça a correspondência de oid como um valor exato: Defina claims.oid com o ID de objeto completo da identidade gerenciada. Um subject_prefix definido com esse ID de objeto completo é equivalente (o assistente do Console define ambos); nunca use um subject_prefix curinga ou com GUID parcial, que corresponde a mais identidades do que você pretende.
• Fixe tid como defesa em profundidade: A URL do emissor já fixa seu tenant, mas adicionar claims.tid protege contra desvios de configuração se o registro do emissor for editado posteriormente.
• Fixe a audiência: Defina audience com o valor exato de aud do seu token decodificado para que tokens emitidos para outros aplicativos sejam rejeitados.
• Use uma regra separada para cada identidade gerenciada: Crie uma regra para cada identidade em vez de uma regra que autoriza várias, para que você possa revogar o acesso de uma única carga de trabalho sem afetar as outras.



Próximos passos

• Revise o modelo de configuração completo em Workload Identity Federation.
• Consulte os guias de provedores para AWS, Google Cloud, GitHub Actions e Kubernetes.
• Para variáveis de ambiente, arquivos de perfil e precedência de credenciais, consulte a referência de WIF.