Claude Platform Docs
AmministrazioneProvider di identità

Usare WIF con Microsoft Entra ID

Federa le identità gestite di Azure e Entra Workload Identity con la Claude API in modo che i tuoi carichi di lavoro Azure possano chiamare Claude senza chiavi API statiche.

I carichi di lavoro Azure si autenticano alla Claude API presentando un JSON Web Token (JWT) emesso da Microsoft Entra ID, quindi scambiandolo 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 app registration 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: Una "managed identity" (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 service account e scrivi una regola di federazione che corrisponda ai claim del token.
  4. Scambia a runtime: Il tuo carico di lavoro scambia il proprio token emesso da Entra presso POST /v1/oauth/token con un token di accesso Anthropic sk-ant-oat01-... e chiama Claude con esso.

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; cambia solo il modo in cui il carico di lavoro ottiene quel token. Scegli la sezione relativa a dove viene eseguito il tuo carico di lavoro: Usare un'identità gestita per VM, VM Scale Set, App Service, Functions o Container Apps; Usare Entra Workload Identity su AKS per AKS.

Prerequisiti

  • Familiarità con i concetti di WIF: service account, issuer di federazione e regole di federazione.
  • Una sottoscrizione Azure con il permesso di assegnare identità gestite (o di configurare Entra Workload Identity su AKS).
  • Il permesso di creare una app registration 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 Registrare l'audience del token è obbligatorio prima che qualsiasi richiesta di token abbia successo.
  • L'ID del tuo tenant Microsoft Entra. Lo trovi nel portale Azure in Microsoft Entra ID → Overview → Tenant ID.
  • Il permesso di creare service account, issuer di federazione e regole di federazione nella Claude Console per la tua organizzazione Anthropic.

Registrare l'audience del token

Microsoft Entra ID emette un token solo quando l'audience richiesta esiste nel tuo tenant come app registration con un service principal. Crea una app registration 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 token di Entra).

# Crea la registrazione dell'app che rappresenta l'audience della Claude API.
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 affinché l'audience venga risolta nel tuo tenant.
az ad sp create --id "$APP_ID"

Usare 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 propria identità gestita assegnata dall'endpoint token locale della piattaforma, quindi scambia quel JWT con Anthropic.

Configurare l'identità gestita

  1. Collega un'identità gestita

    Abilita un'identità gestita assegnata dal sistema o assegnata dall'utente sulla tua risorsa Azure. Nel portale Azure, apri la risorsa, vai su Identity e attiva System assigned (oppure collega un'identità assegnata dall'utente).

    Dopo che l'identità è stata creata, annota il suo Object (principal) ID. Questo GUID appare sia come claim sub sia come claim oid nel token emesso, e la tua regola di federazione Anthropic effettuerà la corrispondenza su di esso. Puoi trovarlo nella pagina Identity della risorsa; per un'identità assegnata dall'utente, è l'Object (principal) ID nella pagina Overview della risorsa identità gestita. (Un'identità gestita ha solo un service principal in Microsoft Entra ID, non una app registration.)

  2. Trova l'endpoint token della piattaforma

    La piattaforma espone un endpoint token locale una volta che l'identità è collegata:

    • VM e VM Scale Set: IMDS all'indirizzo http://169.254.169.254/metadata/identity/oauth2/token con l'header Metadata: true e api-version=2018-02-01.
    • App Service, Functions e Container Apps: L'URL nella variabile d'ambiente IDENTITY_ENDPOINT con l'header X-IDENTITY-HEADER impostato al valore di IDENTITY_HEADER, e api-version=2019-08-01. IMDS non è raggiungibile su queste piattaforme.

    Se la risorsa ha più di un'identità gestita assegnata dall'utente, aggiungi client_id=<IDENTITY_CLIENT_ID> alla richiesta di token per selezionarne una. Azure raccomanda di specificarlo sempre. Senza di esso, il risultato dipende dal fatto che la risorsa abbia anche un'identità assegnata dal sistema abilitata: se la ha, la richiesta ricade silenziosamente su quell'identità e poi fallisce la corrispondenza oid della tua regola di federazione; se non la ha, la richiesta fallisce direttamente non appena viene collegata una seconda identità assegnata dall'utente.

  3. Decodifica un token di esempio

    Richiedi un token dall'endpoint e decodifica il suo payload per confermare i claim su cui la tua regola di federazione deve effettuare la corrispondenza. (Per il comando di decodifica, consulta Risolvere i problemi di uno scambio fallito.) Un token v2.0 per un'identità gestita contiene questi claim:

    {
  "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
}
    ClaimValoreEffettua la corrispondenza quando
    oidL'object ID dell'identità gestita, identico a subVuoi autorizzare una specifica identità gestita. Questo è il comportamento predefinito; la regola in Configurare Anthropic effettua la corrispondenza su di esso.
    azpIl client ID dell'identità chiamanteVuoi autorizzare ogni carico di lavoro che condivide una app registration. Per un'identità gestita, azp è univoco per quell'identità, quindi è equivalente a oid.
    audIl client ID della app registration dell'audience (il GUID <APP_ID> da Registrare l'audience del token)Sempre. Il campo audience della regola deve essere esattamente uguale al valore aud del token.
    tidL'ID del tuo tenantVuoi una difesa in profondità. L'URL dell'issuer vincola già il tenant.

    Se il claim ver del token decodificato è 1.0, i nomi e i valori dei claim differiscono. Consulta Se i tuoi token sono v1.0 prima di continuare.

Configurare 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 service account 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 valore 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 per tenant, quindi usa la modalità discovery. Ogni tenant Microsoft Entra che federi necessita del proprio record 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 per più tempo. Se un token trapela, la leva è disabilitare la regola di federazione; una corrispondenza oid stretta limita in primo luogo quali identità possono scambiare un token, come descritto in Delimitare la regola.

Regola di federazione: Effettua la corrispondenza 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 app registration dell'audience (il GUID <APP_ID> da Registrare 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 rinnova per te.

Acquisire e usare il token

A runtime il tuo carico di lavoro recupera il proprio token Entra, lo scambia presso POST /v1/oauth/token e usa il bearer token restituito per chiamare Claude. Ogni SDK Anthropic gestisce lo scambio e il ciclo di rinnovo 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 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 resource api://<APP_ID> con il client ID della app registration dell'audience da Registrare l'audience del token.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

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

Verificare la configurazione

Dalla tua risorsa Azure, esegui lo scambio cURL mostrato in Acquisire e usare 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. Se lo scambio fallisce con la risposta opaca 401 authentication_error (messaggio Authentication failed), controlla la pagina della cronologia di autenticazione per il motivo del rifiuto, quindi decodifica il token Entra (consulta Risolvere i problemi di uno scambio fallito per il comando) e verifica le cause più comuni lato Azure:

  • Issuer non corrispondente: 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 contengono fino a 24 ore tra iat ed exp. Se l'issuer ha ancora il 7500 della procedura guidata (o il valore predefinito di 1 ora), aumenta max_jwt_lifetime_seconds a 86400 come descritto in Configurare Anthropic.
  • Audience non corrispondente: L'audience della regola deve essere esattamente uguale all'aud del token: il client ID della app registration dell'audience per i token v2.0 che questa guida configura.
  • Nome del claim non corrispondente: Una regola che effettua la corrispondenza 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.

Usare 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 service account Kubernetes con un'identità gestita assegnata dall'utente: Kubernetes proietta un token del service account (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 in due passaggi: prima riscatta il token proiettato presso 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 identity token.

Configurare Entra Workload Identity

  1. Abilita l'issuer OIDC e workload identity sul tuo cluster

    L'abilitazione di workload identity installa per te il mutating webhook azure-workload-identity; distribuiscilo manualmente solo su cluster non AKS. Acquisisci l'URL dell'issuer OIDC del cluster per la credenziale federata che crei in un passaggio successivo.

    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. Crea un'identità gestita assegnata dall'utente

    Acquisisci due valori dall'identità: il Client ID va nell'annotazione del service account (e viene iniettato nel pod come AZURE_CLIENT_ID), e l'Object (principal) ID appare come claim oid su cui la tua regola di federazione Anthropic effettua la corrispondenza.

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

# Va nell'annotazione del service account; iniettato nel pod come AZURE_CLIENT_ID.
IDENTITY_CLIENT_ID=$(az identity show \
  --resource-group <RESOURCE_GROUP> \
  --name claude-inference-identity \
  --query clientId -o tsv)

# Appare come claim oid a cui corrisponde la tua regola di federazione.
IDENTITY_OBJECT_ID=$(az identity show \
  --resource-group <RESOURCE_GROUP> \
  --name claude-inference-identity \
  --query principalId -o tsv)

  3. Crea il service account Kubernetes annotato

    Il webhook azure-workload-identity legge l'annotazione azure.workload.identity/client-id per iniettare AZURE_CLIENT_ID nel pod, che gli esempi in Acquisire e usare il token leggono dall'ambiente.

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

  4. Crea la credenziale federata sull'identità gestita

    La credenziale federata considera attendibile l'issuer OIDC del tuo cluster per quello specifico service account. Il valore --audience api://AzureADTokenExchange è l'audience fissa di Entra per i token del service account Kubernetes in ingresso; non ha relazione con l'audience della Claude API che hai registrato in precedenza.

    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. Etichetta il pod e imposta il suo service account

    Il pod deve avere l'etichetta azure.workload.identity/use: "true" ed essere eseguito come il service account annotato. Il webhook inietta quindi AZURE_FEDERATED_TOKEN_FILE, AZURE_CLIENT_ID e AZURE_TENANT_ID nel pod. Il file in AZURE_FEDERATED_TOKEN_FILE contiene il token del service account proiettato da Kubernetes, firmato dall'issuer OIDC del 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. Decodifica un token di esempio

    Il token che la tua regola di federazione Anthropic vede non è il file proiettato; è il token emesso da Entra restituito dallo scambio client_credentials. Dall'interno di un pod etichettato, esegui il passaggio 1 dell'esempio cURL in Acquisire e usare il token e decodifica il risultato. Contiene la stessa struttura di claim del percorso con identità gestita:

    {
  "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 sono l'object ID dell'identità gestita, aud è il client ID della app registration dell'audience e azp è il client ID dell'identità gestita (il valore di AZURE_CLIENT_ID). La durata differisce dal percorso con identità gestita: i token client_credentials hanno come valore predefinito una finestra casuale da 60 a 90 minuti tra iat ed exp, non 24 ore.

Configurare 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 service account 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 valore 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 per tenant, quindi usa la modalità discovery. Ogni tenant Microsoft Entra che federi necessita del proprio record 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 per più tempo. Se un token trapela, la leva è disabilitare la regola di federazione; una corrispondenza oid stretta limita in primo luogo quali identità possono scambiare un token, come descritto in Delimitare la regola.

Regola di federazione: Effettua la corrispondenza 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 app registration dell'audience (il GUID <APP_ID> da Registrare 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 rinnova per te.

Acquisire e usare il token

A runtime il pod esegue lo scambio in due passaggi: invia il token proiettato da Kubernetes (il file in AZURE_FEDERATED_TOKEN_FILE) all'endpoint token di Entra come asserzione client_credentials federata, quindi scambia il token di accesso Entra risultante presso POST /v1/oauth/token. Ogni SDK Anthropic gestisce il secondo scambio e il ciclo di rinnovo quando fornisci il recupero 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 app registration dell'audience da Registrare 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"))

Verificare la configurazione

Dall'interno di un pod etichettato, esegui lo scambio cURL mostrato in Acquisire e usare 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. Se lo scambio fallisce con la risposta opaca 401 authentication_error (messaggio Authentication failed), controlla la pagina della cronologia di autenticazione per il motivo del rifiuto, quindi decodifica il token emesso da Entra dal passaggio 1 (consulta Risolvere i problemi di uno scambio fallito per il comando) e verifica le cause più comuni lato Azure:

  • Issuer non corrispondente: 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 7500 secondi, aumenta il max_jwt_lifetime_seconds dell'issuer come descritto in Configurare Anthropic.
  • Audience non corrispondente: L'audience della regola deve essere esattamente uguale all'aud del token: il client ID della app registration dell'audience per i token v2.0 che questa guida configura.
  • Nome del claim non corrispondente: Una regola che effettua la corrispondenza 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 app registration dell'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 lo riporta il 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'identifier URI 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 effettua la corrispondenza 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.

Delimitare la regola

Una regola di federazione può effettuare la corrispondenza sul subject del token con subject_prefix in aggiunta (o in alternativa) alla mappa claims; consulta Semantica di corrispondenza 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'intero object ID di 36 caratteri corrisponde solo a quel subject; questa è una proprietà del formato del subject di Entra, non di subject_prefix in generale.

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

  • Effettua la corrispondenza su oid come valore esatto: Imposta claims.oid all'intero object ID dell'identità gestita. Un subject_prefix impostato a quell'intero object ID è equivalente (la procedura guidata della Console imposta entrambi); non usare mai un subject_prefix con wildcard o GUID parziale, che corrisponde a più identità di quelle che intendi.
  • 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 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à anziché una regola che ne autorizzi diverse, in modo da poter revocare l'accesso di un singolo carico di lavoro senza influire sugli altri.

Passaggi successivi

Was this page helpful?