Utilizzare WIF con Microsoft Azure

I workload Azure si autenticano all'API di Claude presentando un "JSON Web Token" (token web JSON), o JWT, emesso da Microsoft Entra ID, per poi scambiarlo con un token di accesso Anthropic di breve durata. Esistono due modi comuni per ottenere il token emesso da Entra:

• Identità gestita (VM, App Service, Functions, Container Apps): Il workload chiama l'Azure Instance Metadata Service (IMDS) all'indirizzo http://169.254.169.254/metadata/identity/oauth2/token e riceve un JWT per l'identità assegnata.
• Entra Workload Identity (pod AKS): Kubernetes proietta un token del service account (firmato dall'issuer OIDC del cluster AKS) nel pod al percorso indicato in AZURE_FEDERATED_TOKEN_FILE. Il workload scambia quel token presso Entra per ottenere un token di accesso emesso da Entra.

In entrambi i casi, il token emesso da Entra che presenti ad Anthropic contiene un issuer Entra specifico del tenant (il passaggio Configurare Anthropic di seguito mostra l'URL esatto da registrare) e l'object ID dell'identità gestita nei claim sub e oid. Registri quell'issuer con Anthropic una sola volta, scrivi una regola di federazione che corrisponda ai claim previsti, e il tuo workload scambia il suo token Entra con un token di accesso sk-ant-oat01-... in fase di runtime.

Prerequisiti

• Familiarità con i concetti di WIF: service account, federation issuer e regole di federazione.
• Una sottoscrizione Azure con il permesso di assegnare identità gestite (o configurare Entra Workload Identity su AKS).
• Il tuo tenant ID di Microsoft Entra. Lo trovi nel portale Azure in Microsoft Entra ID → Overview → Tenant ID.
• Il permesso di creare service account, federation issuer e regole di federazione nella Claude Console per la tua organizzazione Anthropic.

Configurare Azure

Configura l'identità per cui Azure emetterà i token. Scegli il percorso che corrisponde a dove viene eseguito il tuo workload.

Claim del token

Un token emesso da Entra per un'identità gestita contiene questi claim:

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

sub e oid sono identici (l'object ID dell'identità gestita). azp è l'ID dell'applicazione o del client. Effettua la corrispondenza su oid per autorizzare una specifica identità, oppure su azp per autorizzare qualsiasi identità associata a una registrazione dell'applicazione. Il claim tid ripete il tuo tenant ID; effettuare la corrispondenza su di esso è una difesa in profondità, perché l'URL dell'issuer vincola già il tenant.

Configurare Anthropic

Segui la procedura di configurazione per registrare un federation issuer, creare un service account Anthropic e creare una regola di federazione nella Claude Console. Nella Console, scegli l'opzione del provider OIDC e fornisci i valori specifici di Entra che seguono.

Federation issuer: Entra pubblica un documento di discovery OIDC all'URL dell'issuer specifico del tenant, quindi usa la modalità discovery. Ogni tenant Azure che federi necessita del proprio record di issuer.

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

Regola di federazione: Effettua la corrispondenza sull'object ID dell'identità gestita e sul tuo tenant ID.

{
  "name": "azure-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "audience": "https://api.anthropic.com",
    "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
}

Acquisire e utilizzare il token

In fase di runtime il tuo workload recupera il suo token Entra, lo scambia tramite POST /v1/oauth/token e utilizza il bearer token restituito per chiamare Claude. Ogni SDK Anthropic gestisce lo scambio e il ciclo di refresh quando fornisci un callable token-provider, come mostrato negli esempi seguenti. La scheda cURL mostra il flusso grezzo.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

IMDS_URL = "http://169.254.169.254/metadata/identity/oauth2/token"


def fetch_entra_token() -> str:
    """Fetch a managed identity token from Azure IMDS."""
    response = requests.get(
        IMDS_URL,
        headers={"Metadata": "true"},
        params={"api-version": "2018-02-01", "resource": "https://api.anthropic.com"},
        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)

Su AKS con Entra Workload Identity

Su AKS, il file in AZURE_FEDERATED_TOKEN_FILE è un token del service account proiettato da Kubernetes firmato dall'issuer OIDC del tuo cluster, non un token emesso da Entra. Per rimanere sul percorso mediato da Entra descritto in questa pagina, scambia prima quel token presso https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token (grant client_credentials federato), quindi passa il token di accesso Entra risultante all'SDK Anthropic come identity token.

import os
from pathlib import Path
import httpx
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_entra_token_via_federation() -> str:
    federated_token = Path(os.environ["AZURE_FEDERATED_TOKEN_FILE"]).read_text()
    response = httpx.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": "https://api.anthropic.com/.default",
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            "client_assertion": federated_token,
        },
    )
    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)

In alternativa, registra direttamente l'issuer OIDC del tuo cluster AKS con Anthropic e salta il passaggio tramite Entra. Consulta Kubernetes per quel pattern.

Verificare la configurazione

Dalla tua risorsa Azure, esegui lo scambio cURL mostrato in precedenza 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, consulta Risolvere i problemi di uno scambio fallito; la causa più comune lato Azure è una discrepanza tra l'issuer_url che hai registrato e il claim iss nel tuo token decodificato. Devono corrispondere esattamente. Per i token delle identità gestite il valore iss è https://login.microsoftonline.com/<TENANT_ID>/v2.0 oppure https://sts.windows.net/<TENANT_ID>/.

Definire l'ambito della regola

Limita il blocco match della regola all'ambito più ristretto che si adatta al tuo caso d'uso:

• Corrispondenza su oid come valore esatto: Imposta claims.oid sull'object ID completo dell'identità gestita e non usare mai subject_prefix per i token Azure.
• Vincola tid come difesa in profondità: L'URL dell'issuer vincola già il tuo tenant, ma aggiungere claims.tid protegge da derive di configurazione nel caso in cui il record dell'issuer venga modificato in seguito.
• Vincola l'audience: Imposta audience su https://api.anthropic.com in modo che i token emessi per altre risorse vengano rifiutati.
• Usa una regola separata per ogni identità gestita: Crea una regola per identità anziché una regola che ne autorizza diverse, così puoi revocare l'accesso di un singolo workload senza influire sugli altri.

Passaggi successivi

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