Usar WIF com o 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, em seguida, trocando-o por um token de acesso de curta duração da Anthropic. A configuração segue o mesmo formato em todas as plataformas do Azure:

1. Registrar 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. Todas as cargas de trabalho no tenant solicitam tokens do Entra para ele.
2. Configurar 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. Configurar a Anthropic: Registre o emissor do Entra do seu tenant, crie uma conta de serviço e escreva uma regra de federação que corresponda às claims do token.
4. Trocar 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 sk-ant-oat01-... da Anthropic e chama o Claude com ele.

Em ambos os caminhos, o token que você apresenta à Anthropic carrega o emissor do 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 ao local onde sua carga de trabalho é executada: Usar uma identidade gerenciada para VMs, VM Scale Sets, App Service, Functions ou Container Apps; Usar 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 uma entidade de serviço 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 Registrar a audiência do token é obrigatória antes que qualquer solicitação de token seja bem-sucedida.
• Seu ID de 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 da Anthropic.



Registrar 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 uma entidade de serviço. Crie um registro de aplicativo para representar a audiência da API do Claude; todas as cargas de trabalho no tenant podem 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 a audiência 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 a entidade de serviço para que a audiência seja resolvida no seu tenant.
az ad sp create --id "$APP_ID"



Usar uma identidade gerenciada

Use este caminho quando sua carga de trabalho for 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.



Configurar a identidade gerenciada



Configurar a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco Microsoft Entra. O assistente orienta você pelo registro do emissor, criação de uma conta de serviço e 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ê federa 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 restrita de oid limita quais identidades podem trocar um token em primeiro lugar, conforme descrito em Definir o escopo da sua regra.

Regra de federação: Faça a correspondência com o ID de objeto da identidade gerenciada e seu ID de tenant. Para os tokens v2.0 que este guia configura, o valor de audience é o client ID do registro de aplicativo de audiência (o GUID <APP_ID> de Registrar 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 da Anthropic que a troca retorna, não do token do Entra; o SDK o atualiza para você.



Adquirir e usar 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 o Claude. Cada SDK da Anthropic lida com a troca e o loop de atualização quando você fornece um callable provedor de token, conforme mostrado nos exemplos a seguir. A aba cURL mostra o fluxo bruto.

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

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

# O URI identificador do registro de aplicativo de 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 Conjunto de Dimensionamento de VMs: 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)



Verificar a configuração

A partir do seu recurso do Azure, execute a troca cURL mostrada em Adquirir e usar 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 Configurar 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 de 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.



Usar o Entra Workload Identity no AKS

Use este caminho quando sua carga de trabalho for 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 de dois saltos: primeiro resgata o token projetado em https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token (grant client_credentials federado) por um token de acesso emitido pelo Entra, depois passa esse token do Entra para o SDK da Anthropic como o token de identidade.



Configurar o Entra Workload Identity



Configurar a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco Microsoft Entra. O assistente orienta você pelo registro do emissor, criação de uma conta de serviço e 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ê federa 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 restrita de oid limita quais identidades podem trocar um token em primeiro lugar, conforme descrito em Definir o escopo da sua regra.

Regra de federação: Faça a correspondência com o ID de objeto da identidade gerenciada e seu ID de tenant. Para os tokens v2.0 que este guia configura, o valor de audience é o client ID do registro de aplicativo de audiência (o GUID <APP_ID> de Registrar 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 da Anthropic que a troca retorna, não do token do Entra; o SDK o atualiza para você.



Adquirir e usar o token

Em tempo de execução, o pod realiza a troca de dois saltos: 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 loop de atualização quando você fornece a busca do Entra como um callable provedor de token, conforme 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 de audiência de Registrar a audiência do token; o escopo api://<APP_ID>/.default solicita 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Azure"}],
)
print(message.content[0].text)



Verificar a configuração

De dentro de um pod rotulado, execute a troca cURL mostrada em Adquirir e usar 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 Configurar 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 de 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 de 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 de 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 como 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.



Definir o escopo da sua regra

Uma regra de federação pode corresponder ao subject do token com subject_prefix além de (ou em vez de) o mapa claims; consulte Semântica de correspondência de regras para saber como os campos se combinam. Os valores 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; isso é 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 adapte ao seu caso de uso:

• Corresponder oid como um valor exato: Defina claims.oid como o ID de objeto completo da identidade gerenciada. Um subject_prefix definido como esse ID de objeto completo é equivalente (o assistente do Console define ambos); nunca use um subject_prefix com curinga ou GUID parcial, que corresponde a mais identidades do que você pretende.
• Fixar tid como defesa em profundidade: A URL do emissor já fixa seu tenant, mas adicionar claims.tid protege contra desvio de configuração se o registro do emissor for editado posteriormente.
• Fixar a audiência: Defina audience como o valor exato de aud do seu token decodificado para que tokens emitidos para outros aplicativos sejam rejeitados.
• Usar 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óximas etapas

• 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.