Usa WIF con Microsoft Entra ID

I carichi di lavoro Azure si autenticano alla Claude API presentando un JSON Web Token (JWT) emesso da Microsoft Entra ID, per poi scambiarlo con un token di accesso Anthropic di breve durata. La configurazione segue la stessa struttura su ogni piattaforma Azure:

1. Registra l'audience del token: Crea una registrazione dell'app nel tuo tenant Microsoft Entra per rappresentare l'audience della Claude API. Ogni carico di lavoro nel tenant richiede token Entra per essa.
2. Configura l'identità per la tua piattaforma: Un'identità gestita su VM, VM Scale Set, App Service, Functions e Container Apps, oppure Entra Workload Identity su AKS.
3. Configura Anthropic: Registra l'issuer Entra del tuo tenant, crea un account di servizio e scrivi una regola di federazione che corrisponda ai claim del token.
4. Scambia a runtime: Il tuo carico di lavoro scambia il token emesso da Entra su POST /v1/oauth/token con un token di accesso Anthropic sk-ant-oat01-... e lo usa per chiamare Claude.

In entrambi i percorsi il token che presenti ad Anthropic contiene l'issuer Entra specifico del tuo tenant e l'object ID dell'identità gestita nei claim sub e oid; differisce solo il modo in cui il carico di lavoro ottiene quel token. Scegli la sezione in base a dove viene eseguito il tuo carico di lavoro: Usa un'identità gestita per VM, VM Scale Set, App Service, Functions o Container Apps; Usa Entra Workload Identity su AKS per AKS.



Prerequisiti

• Familiarità con i concetti di WIF: account di servizio, issuer di federazione e regole di federazione.
• Una sottoscrizione Azure con l'autorizzazione ad assegnare identità gestite (o a configurare Entra Workload Identity su AKS).
• L'autorizzazione a creare una registrazione dell'app e un service principal nel tuo tenant Microsoft Entra (l'audience condivisa della Claude API). Entra emette token solo per un'audience che esiste nel tenant, quindi il passaggio Registra l'audience del token è necessario prima che qualsiasi richiesta di token abbia successo.
• L'ID del tuo tenant Microsoft Entra. Lo trovi nel portale di Azure in Microsoft Entra ID → Overview → Tenant ID.
• L'autorizzazione a creare account di servizio, issuer di federazione e regole di federazione nella Claude Console per la tua organizzazione Anthropic.



Registra l'audience del token

Microsoft Entra ID emette un token solo quando l'audience richiesta esiste nel tuo tenant come registrazione dell'app con un service principal. Crea una registrazione dell'app per rappresentare l'audience della Claude API; ogni carico di lavoro nel tenant può richiedere token per essa. Senza questa registrazione, le richieste di token falliscono con un errore "resource not found in tenant" (AADSTS50001 dagli endpoint dell'identità gestita, AADSTS500011 dall'endpoint dei token di Entra).

# Crea la registrazione dell'app che rappresenta l'audience dell'API Claude.
APP_ID=$(az ad app create --display-name claude-api-federation --query appId -o tsv)

# Richiedi token di accesso v2.0 e imposta l'URI identificatore api://<APP_ID>.
az ad app update --id "$APP_ID" \
  --identifier-uris "api://$APP_ID" \
  --set api.requestedAccessTokenVersion=2

# Crea il service principal in modo che l'audience venga risolta nel tuo tenant.
az ad sp create --id "$APP_ID"



Usa un'identità gestita

Usa questo percorso quando il tuo carico di lavoro viene eseguito su una VM, un VM Scale Set, App Service, Functions o Container Apps. Il carico di lavoro richiede un JWT emesso da Entra per la sua identità gestita assegnata dall'endpoint locale dei token della piattaforma, quindi scambia quel JWT con Anthropic.



Configura l'identità gestita



Configura Anthropic

Nella Claude Console, apri Settings → Workload identity, fai clic su Connect workload e seleziona il riquadro Microsoft Entra. La procedura guidata ti accompagna nella registrazione dell'issuer, nella creazione di un account di servizio e nella creazione di una regola di federazione.

La procedura guidata crea queste risorse per te. Usa i seguenti valori sia che tu li inserisca nella procedura guidata sia che li invii all'Admin API:

Issuer di federazione: Scegli v2.0 (login.microsoftonline.com) nel selettore Token issuer della procedura guidata. (Il selettore ha come predefinito v1; quel valore predefinito esiste per i tenant che riutilizzano registrazioni più vecchie che emettono ancora token v1.0.) Entra pubblica un documento di discovery OIDC all'URL dell'issuer specifico del tenant, quindi usa la modalità discovery. Ogni tenant Microsoft Entra che federi necessita del proprio record di issuer.

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

Una durata accettata più lunga significa che un token Entra trapelato rimane scambiabile più a lungo. Se un token trapela, la leva è disabilitare la regola di federazione; un match oid stretto limita quali identità possono scambiare un token in primo luogo, come descritto in Delimita la tua regola.

Regola di federazione: Fai il match sull'object ID dell'identità gestita e sull'ID del tuo tenant. Per i token v2.0 che questa guida configura, il valore audience è il client ID della registrazione dell'app audience (il GUID <APP_ID> da Registra l'audience del token). Usa il valore aud esatto dal tuo token decodificato.

{
  "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 è la durata del token di accesso Anthropic restituito dallo scambio, non del token Entra; l'SDK lo aggiorna per te.



Acquisisci e usa il token

A runtime il tuo carico di lavoro recupera il suo token Entra, lo scambia su POST /v1/oauth/token e usa il bearer token restituito per chiamare Claude. Ogni SDK Anthropic gestisce lo scambio e il ciclo di aggiornamento quando fornisci un callable token-provider, come mostrato negli esempi seguenti. La scheda cURL mostra il flusso grezzo.

Gli esempi recuperano il token dell'identità gestita dall'endpoint dei token della piattaforma: IMDS su VM e VM Scale Set, oppure il servizio IDENTITY_ENDPOINT su App Service, Functions e Container Apps. Sostituisci <APP_ID> nel valore della risorsa api://<APP_ID> con il client ID della registrazione dell'app audience da Registra l'audience del token.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

# L'URI identificatore della registrazione dell'app audience (vedi Registrare l'audience del token).
AUDIENCE = "api://<APP_ID>"


def fetch_entra_token() -> str:
    """Fetch a managed identity token from the platform's token endpoint."""
    # Con più identità assegnate dall'utente, aggiungi client_id=<IDENTITY_CLIENT_ID>
    # ai parametri della richiesta per selezionarne una.
    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 o 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"))



Verifica la configurazione

Dalla tua risorsa Azure, esegui lo scambio cURL mostrato in Acquisisci e usa il token e conferma che POST /v1/oauth/token restituisca un 200 con un access_token che inizia con sk-ant-oat01- e un valore expires_in in secondi. In caso di 400 invalid_grant, decodifica il token Entra (consulta Risolvere i problemi di uno scambio fallito per il comando) e controlla le cause più comuni lato Azure:

• Mancata corrispondenza dell'issuer: L'issuer_url registrato deve corrispondere esattamente al claim iss del token. Un token v2.0 contiene https://login.microsoftonline.com/<TENANT_ID>/v2.0; se il claim ver decodificato è 1.0, consulta Se i tuoi token sono v1.0.
• Durata del token: I token di identità gestita hanno fino a 24 ore tra iat ed exp. Se l'issuer ha ancora il valore 7500 della procedura guidata (o il valore predefinito di 1 ora), aumenta max_jwt_lifetime_seconds a 86400 come descritto in Configura Anthropic.
• Mancata corrispondenza dell'audience: L'audience della regola deve essere esattamente uguale all'aud del token: il client ID della registrazione dell'app audience per i token v2.0 che questa guida configura.
• Mancata corrispondenza del nome del claim: Una regola che fa il match su un claim che il token non contiene non passa mai. I token v1.0 contengono il client ID in appid, non in azp; consulta Se i tuoi token sono v1.0.



Usa Entra Workload Identity su AKS

Usa questo percorso quando il tuo carico di lavoro viene eseguito in un pod AKS. Entra Workload Identity federa un account di servizio Kubernetes con un'identità gestita assegnata dall'utente: Kubernetes proietta un token dell'account di servizio (firmato dall'issuer OIDC del cluster AKS) nel pod al percorso indicato in AZURE_FEDERATED_TOKEN_FILE. Quel token proiettato non è un token emesso da Entra, quindi per rimanere sul percorso mediato da Entra descritto in questa pagina, il carico di lavoro esegue uno scambio a due passaggi: prima riscatta il token proiettato su https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token (grant client_credentials federato) per un token di accesso emesso da Entra, poi passa quel token Entra all'SDK Anthropic come token di identità.



Configura Entra Workload Identity



Configura Anthropic

Nella Claude Console, apri Settings → Workload identity, fai clic su Connect workload e seleziona il riquadro Microsoft Entra. La procedura guidata ti accompagna nella registrazione dell'issuer, nella creazione di un account di servizio e nella creazione di una regola di federazione.

La procedura guidata crea queste risorse per te. Usa i seguenti valori sia che tu li inserisca nella procedura guidata sia che li invii all'Admin API:

Issuer di federazione: Scegli v2.0 (login.microsoftonline.com) nel selettore Token issuer della procedura guidata. (Il selettore ha come predefinito v1; quel valore predefinito esiste per i tenant che riutilizzano registrazioni più vecchie che emettono ancora token v1.0.) Entra pubblica un documento di discovery OIDC all'URL dell'issuer specifico del tenant, quindi usa la modalità discovery. Ogni tenant Microsoft Entra che federi necessita del proprio record di issuer.

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

Una durata accettata più lunga significa che un token Entra trapelato rimane scambiabile più a lungo. Se un token trapela, la leva è disabilitare la regola di federazione; un match oid stretto limita quali identità possono scambiare un token in primo luogo, come descritto in Delimita la tua regola.

Regola di federazione: Fai il match sull'object ID dell'identità gestita e sull'ID del tuo tenant. Per i token v2.0 che questa guida configura, il valore audience è il client ID della registrazione dell'app audience (il GUID <APP_ID> da Registra l'audience del token). Usa il valore aud esatto dal tuo token decodificato.

{
  "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 è la durata del token di accesso Anthropic restituito dallo scambio, non del token Entra; l'SDK lo aggiorna per te.



Acquisisci e usa il token

A runtime il pod esegue lo scambio a due passaggi: invia il token proiettato da Kubernetes (il file in AZURE_FEDERATED_TOKEN_FILE) all'endpoint dei token di Entra come asserzione client_credentials federata, poi scambia il token di accesso Entra risultante su POST /v1/oauth/token. Ogni SDK Anthropic gestisce il secondo scambio e il ciclo di aggiornamento quando fornisci il recupero da Entra come callable token-provider, come mostrato negli esempi seguenti. La scheda cURL mostra il flusso grezzo.

Negli esempi compaiono due client ID diversi. <APP_ID> è il client ID della registrazione dell'app audience da Registra l'audience del token; lo scope api://<APP_ID>/.default chiede a Entra un token indirizzato a quell'audience. $AZURE_CLIENT_ID è il client ID dell'identità gestita, iniettato dal webhook, e identifica il chiamante. Non sostituire l'uno con l'altro.

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



Verifica la configurazione

Dall'interno di un pod etichettato, esegui lo scambio cURL mostrato in Acquisisci e usa il token e conferma che POST /v1/oauth/token restituisca un 200 con un access_token che inizia con sk-ant-oat01- e un valore expires_in in secondi. In caso di 400 invalid_grant, decodifica il token emesso da Entra dal passaggio 1 (consulta Risolvere i problemi di uno scambio fallito per il comando) e controlla le cause più comuni lato Azure:

• Mancata corrispondenza dell'issuer: L'issuer_url registrato deve corrispondere esattamente al claim iss del token. Un token v2.0 contiene https://login.microsoftonline.com/<TENANT_ID>/v2.0; se il claim ver decodificato è 1.0, consulta Se i tuoi token sono v1.0.
• Durata del token: Se una policy di durata dei token del tenant o la CAE estende il token client_credentials oltre i 7500 secondi, aumenta max_jwt_lifetime_seconds dell'issuer come descritto in Configura Anthropic.
• Mancata corrispondenza dell'audience: L'audience della regola deve essere esattamente uguale all'aud del token: il client ID della registrazione dell'app audience per i token v2.0 che questa guida configura.
• Mancata corrispondenza del nome del claim: Una regola che fa il match su un claim che il token non contiene non passa mai. I token v1.0 contengono il client ID in appid, non in azp; consulta Se i tuoi token sono v1.0.



Se i tuoi token sono v1.0

Questa guida configura la registrazione dell'app audience con api.requestedAccessTokenVersion: 2, quindi ogni token che mostra è v2.0. Se riutilizzi una registrazione esistente che lascia requestedAccessTokenVersion non impostato, Entra emette invece token v1.0. Decodifica un token di esempio e controlla il suo claim ver; se è 1.0, cambiano quattro cose:

• Issuer: Il claim iss è https://sts.windows.net/<TENANT_ID>/ invece di https://login.microsoftonline.com/<TENANT_ID>/v2.0. Registra l'URL dell'issuer esattamente come appare nel claim iss del tuo token. I due URL condividono lo stesso JWKS, quindi la modalità discovery funziona per entrambi.
• Selettore della procedura guidata: Scegli v1 (sts.windows.net) nel selettore Token issuer della procedura guidata Connect workload invece di v2.0 (login.microsoftonline.com).
• Audience: Il claim aud è l'URI identificatore che hai passato come resource (ad esempio, api://<APP_ID>), non il client ID della registrazione. Imposta l'audience della regola di federazione al valore aud esatto dal tuo token decodificato.
• Claim del client ID: Il client ID dell'identità chiamante appare in appid, non in azp. I due claim non appaiono mai nello stesso token, quindi una regola che fa il match su azp non passa mai con un token v1.0.

I claim oid, sub e tid contengono gli stessi valori in entrambe le versioni, quindi il resto di questa guida si applica senza modifiche.



Delimita la tua regola

Una regola di federazione può fare il match sul subject del token con subject_prefix in aggiunta (o in alternativa) alla mappa claims; consulta Semantica del matching delle regole per come i campi si combinano. I valori sub di Entra per queste identità sono GUID canonici a lunghezza fissa, quindi un subject_prefix contenente l'object ID completo di 36 caratteri corrisponde solo a quel subject; questa è una proprietà del formato del subject di Entra, non di subject_prefix in generale.

Blocca il blocco match della regola all'ambito più ristretto adatto al tuo caso d'uso:

• Fai il match su oid come valore esatto: Imposta claims.oid all'object ID completo dell'identità gestita. Un subject_prefix impostato a quell'object ID completo è equivalente (la procedura guidata della Console imposta entrambi); non usare mai un subject_prefix con wildcard o con un GUID parziale, che corrisponde a più identità di quelle previste.
• Vincola tid come difesa in profondità: L'URL dell'issuer vincola già il tuo tenant, ma aggiungere claims.tid protegge dalla deriva della configurazione se il record dell'issuer viene modificato in seguito.
• Vincola l'audience: Imposta audience al valore aud esatto dal tuo token decodificato in modo che i token emessi per altre applicazioni vengano rifiutati.
• Usa una regola separata per ogni identità gestita: Crea una regola per ogni identità invece di una regola che ne autorizza diverse, in modo da poter revocare l'accesso di un singolo carico di lavoro senza influire sugli altri.



Prossimi passi

• Rivedi il modello di configurazione completo in Workload Identity Federation.
• Consulta le guide dei provider per AWS, Google Cloud, GitHub Actions e Kubernetes.
• Per le variabili d'ambiente, i file di profilo e la precedenza delle credenziali, consulta il riferimento WIF.