Claude Platform Docs
AdministraçãoProvedores de identidade

Usar WIF com o Microsoft Entra ID

Federe identidades gerenciadas do Azure e o Entra Workload Identity com a Claude API para que suas cargas de trabalho do Azure possam chamar o Claude sem chaves de API estáticas.

As cargas de trabalho do Azure se autenticam na Claude API 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 da Anthropic de curta duração. A configuração segue o mesmo formato em todas as plataformas do Azure:

  1. Registrar o audience do token: Crie um "app registration" (registro de aplicativo) no seu "tenant" (locatário) do Microsoft Entra para representar o "audience" (público-alvo) da Claude API. Toda carga de trabalho no locatário solicita tokens do Entra para ele.
  2. Configurar a identidade para sua plataforma: Uma "managed identity" (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 locatário, crie uma "service account" (conta de serviço) e escreva uma "federation rule" (regra de federação) que corresponda às "claims" (declarações) 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 da Anthropic sk-ant-oat01-... 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 locatário 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 "service principal" (entidade de serviço) no seu locatário do Microsoft Entra (o audience compartilhado da Claude API). O Entra só emite tokens para um audience que exista no locatário, portanto a etapa Registrar o audience do token é obrigatória antes que qualquer solicitação de token seja bem-sucedida.
  • O ID do seu locatário 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 o audience do token

O Microsoft Entra ID só emite um token quando o audience solicitado existe no seu locatário como um registro de aplicativo com uma entidade de serviço. Crie um registro de aplicativo para representar o audience da Claude API; toda carga de trabalho no locatário pode solicitar tokens para ele. Sem esse registro, as solicitações de token falham com um erro "resource not found in tenant" (AADSTS50001 nos endpoints de identidade gerenciada, AADSTS500011 no endpoint de token do Entra).

# Crie o registro de aplicativo que representa a audiência da Claude API.
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 locatário.
az ad sp create --id "$APP_ID"

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

Configurar a identidade gerenciada

  1. Anexar uma identidade gerenciada

    Habilite uma identidade gerenciada atribuída pelo sistema ou atribuída pelo usuário no seu recurso do Azure. No portal do Azure, abra o recurso, vá para Identity e ative System assigned (ou anexe uma identidade atribuída pelo usuário).

    Depois que a identidade for criada, anote seu Object (principal) ID. Esse GUID aparece tanto na claim sub quanto na claim oid do token emitido, e sua regra de federação da Anthropic fará a correspondência com ele. Você pode encontrá-lo na página Identity do recurso; para uma identidade atribuída pelo usuário, é o Object (principal) ID na página Overview do recurso de identidade gerenciada. (Uma identidade gerenciada tem apenas uma entidade de serviço no Microsoft Entra ID, não um registro de aplicativo.)

  2. Encontrar o endpoint de token da plataforma

    A plataforma expõe um endpoint de token local assim que a identidade é anexada:

    • VMs e VM Scale Sets: IMDS em http://169.254.169.254/metadata/identity/oauth2/token com o cabeçalho Metadata: true e api-version=2018-02-01.
    • App Service, Functions e Container Apps: A URL na variável de ambiente IDENTITY_ENDPOINT com o cabeçalho X-IDENTITY-HEADER definido com o valor de IDENTITY_HEADER, e api-version=2019-08-01. O IMDS não é acessível nessas plataformas.

    Se o recurso tiver mais de uma identidade gerenciada atribuída pelo usuário, adicione client_id=<IDENTITY_CLIENT_ID> à solicitação de token para selecionar uma. O Azure recomenda sempre especificá-lo. Sem ele, o resultado depende de o recurso também ter uma identidade atribuída pelo sistema habilitada: se tiver, a solicitação recai silenciosamente nessa identidade e então falha na correspondência de oid da sua regra de federação; se não tiver, a solicitação falha imediatamente assim que uma segunda identidade atribuída pelo usuário é anexada.

  3. Decodificar um token de exemplo

    Solicite um token ao endpoint e decodifique seu payload para confirmar as claims com as quais sua regra de federação precisa corresponder. (Para o comando de decodificação, consulte Solucionar problemas de uma troca com falha.) Um token v2.0 para uma identidade gerenciada carrega estas claims:

    {
  "iss": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
  "sub": "9f8e7d6c-1a2b-3c4d-5e6f-...",
  "aud": "<APP_ID>",
  "oid": "9f8e7d6c-1a2b-3c4d-5e6f-...",
  "tid": "<TENANT_ID>",
  "azp": "<IDENTITY_CLIENT_ID>",
  "ver": "2.0",
  "exp": 1775527120
}
    ClaimValorFaça a correspondência quando
    oidO ID de objeto da identidade gerenciada, idêntico a subVocê quer autorizar uma identidade gerenciada específica. Este é o padrão; a regra em Configurar a Anthropic corresponde a ele.
    azpO ID do cliente da identidade chamadoraVocê quer autorizar toda carga de trabalho que compartilha um registro de aplicativo. Para uma identidade gerenciada, azp é exclusivo dessa identidade, portanto é equivalente a oid.
    audO ID do cliente do registro de aplicativo do audience (o GUID <APP_ID> de Registrar o audience do token)Sempre. O campo audience da regra deve ser exatamente igual ao valor aud do token.
    tidO ID do seu locatárioVocê quer defesa em profundidade. A URL do emissor já fixa o locatário.

    Se a claim ver do token decodificado for 1.0, os nomes e valores das claims diferem. Consulte Se seus tokens são v1.0 antes de continuar.

Configurar 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 locatários que reutilizam registros mais antigos que ainda emitem tokens v1.0.) O Entra publica um documento de descoberta OIDC na URL do emissor por locatário, portanto use o modo de descoberta. Cada locatário 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 restrita de oid limita quais identidades podem trocar um token em primeiro lugar, conforme descrito em Delimitar 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 locatário. Para os tokens v2.0 que este guia configura, o valor de audience é o ID do cliente do registro de aplicativo do audience (o GUID <APP_ID> de Registrar o audience do token). Use o valor aud exato 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, 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 ID do cliente do registro de aplicativo do audience de Registrar o audience do token.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

# O URI identificador do registro do 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 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"))

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. Se a troca falhar com a resposta opaca 401 authentication_error (mensagem Authentication failed), verifique a página de histórico de autenticação para ver o motivo da negação, depois 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: A issuer_url registrada 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 são 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 audience: O audience da regra deve ser exatamente igual ao aud do token: o ID do cliente do registro de aplicativo do audience 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 é aprovada. Tokens v1.0 carregam o ID do cliente em appid, não em azp; consulte Se seus tokens são v1.0.

Usar 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 e, em seguida, passa esse token do Entra ao SDK da Anthropic como o token de identidade.

Configurar o Entra Workload Identity

  1. Habilitar o emissor OIDC e o workload identity no seu cluster

    Habilitar o workload identity instala o webhook de mutação azure-workload-identity para você; implante-o manualmente apenas em clusters que não sejam AKS. Capture a URL do emissor OIDC do cluster para a credencial federada que você criará em uma etapa posterior.

    az aks update \
  --resource-group <RESOURCE_GROUP> \
  --name <CLUSTER_NAME> \
  --enable-oidc-issuer \
  --enable-workload-identity

AKS_OIDC_ISSUER=$(az aks show \
  --resource-group <RESOURCE_GROUP> \
  --name <CLUSTER_NAME> \
  --query oidcIssuerProfile.issuerUrl -o tsv)

  2. Criar uma identidade gerenciada atribuída pelo usuário

    Capture dois valores da identidade: o Client ID vai na anotação da conta de serviço (e é injetado no pod como AZURE_CLIENT_ID), e o Object (principal) ID aparece como a claim oid com a qual sua regra de federação da Anthropic faz correspondência.

    az identity create \
  --resource-group <RESOURCE_GROUP> \
  --name claude-inference-identity \
  --location <LOCATION>

# Vai na anotação da service account; injetado no pod como AZURE_CLIENT_ID.
IDENTITY_CLIENT_ID=$(az identity show \
  --resource-group <RESOURCE_GROUP> \
  --name claude-inference-identity \
  --query clientId -o tsv)

# Aparece como a claim oid que sua regra de federação corresponde.
IDENTITY_OBJECT_ID=$(az identity show \
  --resource-group <RESOURCE_GROUP> \
  --name claude-inference-identity \
  --query principalId -o tsv)

  3. Criar a conta de serviço do Kubernetes anotada

    O webhook azure-workload-identity lê a anotação azure.workload.identity/client-id para injetar AZURE_CLIENT_ID no pod, que os exemplos em Adquirir e usar o token leem do ambiente.

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: claude-inference
  namespace: inference
  annotations:
    azure.workload.identity/client-id: <IDENTITY_CLIENT_ID>

  4. Criar a credencial federada na identidade gerenciada

    A credencial federada confia no emissor OIDC do seu cluster para essa conta de serviço específica. O valor --audience api://AzureADTokenExchange é o audience fixo do Entra para tokens de conta de serviço do Kubernetes recebidos; ele não tem relação com o audience da Claude API que você registrou anteriormente.

    az identity federated-credential create \
  --resource-group <RESOURCE_GROUP> \
  --identity-name claude-inference-identity \
  --name claude-inference-aks \
  --issuer "$AKS_OIDC_ISSUER" \
  --subject system:serviceaccount:inference:claude-inference \
  --audience api://AzureADTokenExchange

  5. Rotular o pod e definir sua conta de serviço

    O pod deve carregar o rótulo azure.workload.identity/use: "true" e ser executado como a conta de serviço anotada. O webhook então injeta AZURE_FEDERATED_TOKEN_FILE, AZURE_CLIENT_ID e AZURE_TENANT_ID no pod. O arquivo em AZURE_FEDERATED_TOKEN_FILE contém o token de conta de serviço projetado pelo Kubernetes, assinado pelo emissor OIDC do cluster AKS.

    apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
  labels:
    azure.workload.identity/use: "true"
spec:
  serviceAccountName: claude-inference
  containers:
    - name: app
      image: your-registry/inference-worker:latest

  6. Decodificar um token de exemplo

    O token que sua regra de federação da Anthropic vê não é o arquivo projetado; é o token emitido pelo Entra retornado pela troca client_credentials. De dentro de um pod rotulado, execute a etapa 1 do exemplo cURL em Adquirir e usar o token e decodifique o resultado. Ele carrega o mesmo formato de claims do caminho de identidade gerenciada:

    {
  "iss": "https://login.microsoftonline.com/<TENANT_ID>/v2.0",
  "sub": "9f8e7d6c-1a2b-3c4d-5e6f-...",
  "aud": "<APP_ID>",
  "oid": "9f8e7d6c-1a2b-3c4d-5e6f-...",
  "tid": "<TENANT_ID>",
  "azp": "<IDENTITY_CLIENT_ID>",
  "ver": "2.0",
  "exp": 1775527120
}

    sub e oid são o ID de objeto da identidade gerenciada, aud é o ID do cliente do registro de aplicativo do audience, e azp é o ID do cliente da identidade gerenciada (o valor de AZURE_CLIENT_ID). O tempo de vida difere do caminho de identidade gerenciada: tokens client_credentials têm como padrão uma janela aleatória de 60 a 90 minutos entre iat e exp, não 24 horas.

Configurar 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 locatários que reutilizam registros mais antigos que ainda emitem tokens v1.0.) O Entra publica um documento de descoberta OIDC na URL do emissor por locatário, portanto use o modo de descoberta. Cada locatário 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 restrita de oid limita quais identidades podem trocar um token em primeiro lugar, conforme descrito em Delimitar 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 locatário. Para os tokens v2.0 que este guia configura, o valor de audience é o ID do cliente do registro de aplicativo do audience (o GUID <APP_ID> de Registrar o audience do token). Use o valor aud exato 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 em dois saltos: ele envia o token projetado pelo Kubernetes (o arquivo em AZURE_FEDERATED_TOKEN_FILE) ao endpoint de token do Entra como uma asserção client_credentials federada e, em seguida, 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, como mostrado nos exemplos a seguir. A aba cURL mostra o fluxo bruto.

Dois IDs de cliente diferentes aparecem nos exemplos. <APP_ID> é o ID do cliente do registro de aplicativo do audience de Registrar o audience do token; o escopo api://<APP_ID>/.default pede ao Entra um token endereçado a esse audience. $AZURE_CLIENT_ID é o ID do cliente 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"))

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. Se a troca falhar com a resposta opaca 401 authentication_error (mensagem Authentication failed), verifique a página de histórico de autenticação para ver o motivo da negação, depois 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: A issuer_url registrada 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 são v1.0.
  • Tempo de vida do token: Se uma política de tempo de vida de token do locatário ou a CAE estender o token client_credentials para além de 7500 segundos, aumente o max_jwt_lifetime_seconds do emissor conforme descrito em Configurar a Anthropic.
  • Incompatibilidade de audience: O audience da regra deve ser exatamente igual ao aud do token: o ID do cliente do registro de aplicativo do audience 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 é aprovada. Tokens v1.0 carregam o ID do cliente em appid, não em azp; consulte Se seus tokens são v1.0.

Se seus tokens são v1.0

Este guia configura o registro de aplicativo do audience com api.requestedAccessTokenVersion: 2, portanto todo token que ele mostra é v2.0. Se você reutilizar um registro existente que deixa requestedAccessTokenVersion sem definição, 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 delas.
  • Seletor do assistente: Escolha v1 (sts.windows.net) no seletor Token issuer do assistente Connect workload em vez de v2.0 (login.microsoftonline.com).
  • Audience: A claim aud é a URI de identificador que você passou como resource (por exemplo, api://<APP_ID>), não o ID do cliente do registro. Defina o audience da regra de federação com o valor aud exato do seu token decodificado.
  • Claim de ID do cliente: O ID do cliente 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 é aprovada 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.

Delimitar o escopo da sua regra

Uma regra de federação pode fazer correspondência com o subject do token usando 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 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 atenda ao seu caso de uso:

  • Corresponder 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 de GUID parcial, que corresponde a mais identidades do que você pretende.
  • Fixar tid como defesa em profundidade: A URL do emissor já fixa seu locatário, mas adicionar claims.tid protege contra desvios de configuração caso o registro do emissor seja editado posteriormente.
  • Fixar o audience: Defina audience com o valor aud exato 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 autorize várias, para que você possa revogar o acesso de uma única carga de trabalho sem afetar as outras.

Próximos passos

Was this page helpful?