Utiliser WIF avec Microsoft Entra ID

Les charges de travail Azure s'authentifient auprès de l'API Claude en présentant un « JSON Web Token » (jeton web JSON), ou JWT, émis par Microsoft Entra ID, puis en l'échangeant contre un jeton d'accès Anthropic de courte durée. La configuration suit la même structure sur chaque plateforme Azure :

1. Enregistrer l'audience du jeton : Créez une inscription d'application dans votre locataire Microsoft Entra pour représenter l'audience de l'API Claude. Chaque charge de travail du locataire demande des jetons Entra pour celle-ci.
2. Configurer l'identité pour votre plateforme : Une identité managée sur les VM, les VM Scale Sets, App Service, Functions et Container Apps, ou Entra Workload Identity sur AKS.
3. Configurer Anthropic : Enregistrez l'émetteur Entra de votre locataire, créez un compte de service et rédigez une règle de fédération qui correspond aux revendications du jeton.
4. Échanger au moment de l'exécution : Votre charge de travail échange son jeton émis par Entra via POST /v1/oauth/token contre un jeton d'accès Anthropic sk-ant-oat01-... et l'utilise pour appeler Claude.

Dans les deux cas, le jeton que vous présentez à Anthropic contient l'émetteur Entra spécifique à votre locataire et l'ID d'objet de l'identité managée dans les revendications sub et oid ; seule la manière dont la charge de travail obtient ce jeton diffère. Choisissez la section correspondant à l'emplacement d'exécution de votre charge de travail : Utiliser une identité managée pour les VM, les VM Scale Sets, App Service, Functions ou Container Apps ; Utiliser Entra Workload Identity sur AKS pour AKS.



Prérequis

• Familiarité avec les concepts WIF : comptes de service, émetteurs de fédération et règles de fédération.
• Un abonnement Azure avec l'autorisation d'attribuer des identités managées (ou de configurer Entra Workload Identity sur AKS).
• L'autorisation de créer une inscription d'application et un principal de service dans votre locataire Microsoft Entra (l'audience partagée de l'API Claude). Entra n'émet des jetons que pour une audience qui existe dans le locataire, donc l'étape Enregistrer l'audience du jeton est requise avant que toute demande de jeton puisse aboutir.
• Votre ID de locataire Microsoft Entra. Vous le trouverez dans le portail Azure sous Microsoft Entra ID → Overview → Tenant ID.
• L'autorisation de créer des comptes de service, des émetteurs de fédération et des règles de fédération dans la Claude Console pour votre organisation Anthropic.



Enregistrer l'audience du jeton

Microsoft Entra ID n'émet un jeton que lorsque l'audience demandée existe dans votre locataire sous la forme d'une inscription d'application avec un principal de service. Créez une inscription d'application pour représenter l'audience de l'API Claude ; chaque charge de travail du locataire peut demander des jetons pour celle-ci. Sans cette inscription, les demandes de jeton échouent avec une erreur « resource not found in tenant » (AADSTS50001 depuis les points de terminaison d'identité managée, AADSTS500011 depuis le point de terminaison de jeton Entra).

# Créez l'inscription d'application qui représente l'audience de l'API Claude.
APP_ID=$(az ad app create --display-name claude-api-federation --query appId -o tsv)

# Demandez des jetons d'accès v2.0 et définissez l'URI d'identificateur api://<APP_ID>.
az ad app update --id "$APP_ID" \
  --identifier-uris "api://$APP_ID" \
  --set api.requestedAccessTokenVersion=2

# Créez le principal de service afin que l'audience soit résolue dans votre locataire.
az ad sp create --id "$APP_ID"



Utiliser une identité managée

Utilisez cette approche lorsque votre charge de travail s'exécute sur une VM, un VM Scale Set, App Service, Functions ou Container Apps. La charge de travail demande un JWT émis par Entra pour son identité managée attribuée depuis le point de terminaison de jeton local de la plateforme, puis échange ce JWT auprès d'Anthropic.



Configurer l'identité managée



Configurer Anthropic

Dans la Claude Console, ouvrez Settings → Workload identity, cliquez sur Connect workload et sélectionnez la vignette Microsoft Entra. L'assistant vous guide à travers l'enregistrement de l'émetteur, la création d'un compte de service et la création d'une règle de fédération.

L'assistant crée ces ressources pour vous. Utilisez les valeurs suivantes, que vous les saisissiez dans l'assistant ou que vous les envoyiez à l'Admin API :

Émetteur de fédération : Choisissez v2.0 (login.microsoftonline.com) dans le sélecteur Token issuer de l'assistant. (Le sélecteur est par défaut sur v1 ; cette valeur par défaut existe pour les locataires réutilisant d'anciennes inscriptions qui émettent encore des jetons v1.0.) Entra publie un document de découverte OIDC à l'URL d'émetteur spécifique au locataire, donc utilisez le mode découverte. Chaque locataire Microsoft Entra que vous fédérez nécessite son propre enregistrement d'émetteur.

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

Une durée de vie acceptée plus longue signifie qu'un jeton Entra divulgué reste échangeable plus longtemps. Si un jeton fuite, le levier consiste à désactiver la règle de fédération ; une correspondance oid stricte limite les identités pouvant échanger un jeton en premier lieu, comme décrit dans Délimiter votre règle.

Règle de fédération : Faites correspondre l'ID d'objet de l'identité managée et votre ID de locataire. Pour les jetons v2.0 que ce guide configure, la valeur audience est l'ID client de l'inscription d'application d'audience (le GUID <APP_ID> de Enregistrer l'audience du jeton). Utilisez la valeur aud exacte de votre jeton décodé.

{
  "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 est la durée de vie du jeton d'accès Anthropic que l'échange renvoie, pas celle du jeton Entra ; le SDK le rafraîchit pour vous.



Acquérir et utiliser le jeton

Au moment de l'exécution, votre charge de travail récupère son jeton Entra, l'échange via POST /v1/oauth/token et utilise le jeton porteur renvoyé pour appeler Claude. Chaque SDK Anthropic gère l'échange et la boucle de rafraîchissement lorsque vous fournissez un callable fournisseur de jeton, comme illustré dans les exemples suivants. L'onglet cURL montre le flux brut.

Les exemples récupèrent le jeton d'identité managée depuis le point de terminaison de jeton de la plateforme : IMDS sur les VM et VM Scale Sets, ou le service IDENTITY_ENDPOINT sur App Service, Functions et Container Apps. Remplacez <APP_ID> dans la valeur de ressource api://<APP_ID> par l'ID client de l'inscription d'application d'audience de Enregistrer l'audience du jeton.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

# L'URI d'identificateur de l'inscription d'application d'audience (voir Inscrire l'audience du jeton).
AUDIENCE = "api://<APP_ID>"


def fetch_entra_token() -> str:
    """Fetch a managed identity token from the platform's token endpoint."""
    # Avec plusieurs identités affectées par l'utilisateur, ajoutez client_id=<IDENTITY_CLIENT_ID>
    # aux paramètres de la requête pour en sélectionner une.
    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 groupe de machines virtuelles identiques : 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)



Vérifier la configuration

Depuis votre ressource Azure, exécutez l'échange cURL présenté dans Acquérir et utiliser le jeton et confirmez que POST /v1/oauth/token renvoie un 200 avec un access_token commençant par sk-ant-oat01- et une valeur expires_in en secondes. En cas de 400 invalid_grant, décodez le jeton Entra (consultez Dépanner un échange échoué pour la commande) et vérifiez les causes les plus courantes côté Azure :

• Incompatibilité d'émetteur : L'issuer_url enregistrée doit correspondre exactement à la revendication iss du jeton. Un jeton v2.0 contient https://login.microsoftonline.com/<TENANT_ID>/v2.0 ; si la revendication ver décodée est 1.0, consultez Si vos jetons sont en v1.0.
• Durée de vie du jeton : Les jetons d'identité managée contiennent jusqu'à 24 heures entre iat et exp. Si l'émetteur a toujours la valeur 7500 de l'assistant (ou la valeur par défaut de 1 heure), augmentez max_jwt_lifetime_seconds à 86400 comme décrit dans Configurer Anthropic.
• Incompatibilité d'audience : L'audience de la règle doit être exactement égale à l'aud du jeton : l'ID client de l'inscription d'application d'audience pour les jetons v2.0 que ce guide configure.
• Incompatibilité de nom de revendication : Une règle qui fait correspondre une revendication que le jeton ne contient pas ne passe jamais. Les jetons v1.0 contiennent l'ID client dans appid, pas dans azp ; consultez Si vos jetons sont en v1.0.



Utiliser Entra Workload Identity sur AKS

Utilisez cette approche lorsque votre charge de travail s'exécute dans un pod AKS. Entra Workload Identity fédère un compte de service Kubernetes avec une identité managée attribuée par l'utilisateur : Kubernetes projette un jeton de compte de service (signé par l'émetteur OIDC du cluster AKS) dans le pod au chemin indiqué dans AZURE_FEDERATED_TOKEN_FILE. Ce jeton projeté n'est pas un jeton émis par Entra, donc pour rester sur le chemin médié par Entra décrit sur cette page, la charge de travail effectue un échange en deux étapes : elle échange d'abord le jeton projeté à l'adresse https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token (grant client_credentials fédéré) contre un jeton d'accès émis par Entra, puis transmet ce jeton Entra au SDK Anthropic comme jeton d'identité.



Configurer Entra Workload Identity



Configurer Anthropic

Dans la Claude Console, ouvrez Settings → Workload identity, cliquez sur Connect workload et sélectionnez la vignette Microsoft Entra. L'assistant vous guide à travers l'enregistrement de l'émetteur, la création d'un compte de service et la création d'une règle de fédération.

L'assistant crée ces ressources pour vous. Utilisez les valeurs suivantes, que vous les saisissiez dans l'assistant ou que vous les envoyiez à l'Admin API :

Émetteur de fédération : Choisissez v2.0 (login.microsoftonline.com) dans le sélecteur Token issuer de l'assistant. (Le sélecteur est par défaut sur v1 ; cette valeur par défaut existe pour les locataires réutilisant d'anciennes inscriptions qui émettent encore des jetons v1.0.) Entra publie un document de découverte OIDC à l'URL d'émetteur spécifique au locataire, donc utilisez le mode découverte. Chaque locataire Microsoft Entra que vous fédérez nécessite son propre enregistrement d'émetteur.

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

Une durée de vie acceptée plus longue signifie qu'un jeton Entra divulgué reste échangeable plus longtemps. Si un jeton fuite, le levier consiste à désactiver la règle de fédération ; une correspondance oid stricte limite les identités pouvant échanger un jeton en premier lieu, comme décrit dans Délimiter votre règle.

Règle de fédération : Faites correspondre l'ID d'objet de l'identité managée et votre ID de locataire. Pour les jetons v2.0 que ce guide configure, la valeur audience est l'ID client de l'inscription d'application d'audience (le GUID <APP_ID> de Enregistrer l'audience du jeton). Utilisez la valeur aud exacte de votre jeton décodé.

{
  "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 est la durée de vie du jeton d'accès Anthropic que l'échange renvoie, pas celle du jeton Entra ; le SDK le rafraîchit pour vous.



Acquérir et utiliser le jeton

Au moment de l'exécution, le pod effectue l'échange en deux étapes : il envoie le jeton projeté par Kubernetes (le fichier situé à AZURE_FEDERATED_TOKEN_FILE) au point de terminaison de jeton d'Entra en tant qu'assertion client_credentials fédérée, puis échange le jeton d'accès Entra résultant via POST /v1/oauth/token. Chaque SDK Anthropic gère le second échange et la boucle de rafraîchissement lorsque vous fournissez la récupération Entra comme callable fournisseur de jeton, comme illustré dans les exemples suivants. L'onglet cURL montre le flux brut.

Deux ID client différents apparaissent dans les exemples. <APP_ID> est l'ID client de l'inscription d'application d'audience de Enregistrer l'audience du jeton ; la portée api://<APP_ID>/.default demande à Entra un jeton adressé à cette audience. $AZURE_CLIENT_ID est l'ID client de l'identité managée, injecté par le webhook, et identifie l'appelant. Ne substituez pas l'un à l'autre.

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)



Vérifier la configuration

Depuis l'intérieur d'un pod étiqueté, exécutez l'échange cURL présenté dans Acquérir et utiliser le jeton et confirmez que POST /v1/oauth/token renvoie un 200 avec un access_token commençant par sk-ant-oat01- et une valeur expires_in en secondes. En cas de 400 invalid_grant, décodez le jeton émis par Entra de l'étape 1 (consultez Dépanner un échange échoué pour la commande) et vérifiez les causes les plus courantes côté Azure :

• Incompatibilité d'émetteur : L'issuer_url enregistrée doit correspondre exactement à la revendication iss du jeton. Un jeton v2.0 contient https://login.microsoftonline.com/<TENANT_ID>/v2.0 ; si la revendication ver décodée est 1.0, consultez Si vos jetons sont en v1.0.
• Durée de vie du jeton : Si une politique de durée de vie de jeton du locataire ou CAE prolonge le jeton client_credentials au-delà de 7500 secondes, augmentez le max_jwt_lifetime_seconds de l'émetteur comme décrit dans Configurer Anthropic.
• Incompatibilité d'audience : L'audience de la règle doit être exactement égale à l'aud du jeton : l'ID client de l'inscription d'application d'audience pour les jetons v2.0 que ce guide configure.
• Incompatibilité de nom de revendication : Une règle qui fait correspondre une revendication que le jeton ne contient pas ne passe jamais. Les jetons v1.0 contiennent l'ID client dans appid, pas dans azp ; consultez Si vos jetons sont en v1.0.



Si vos jetons sont en v1.0

Ce guide configure l'inscription d'application d'audience avec api.requestedAccessTokenVersion: 2, donc chaque jeton qu'il présente est en v2.0. Si vous réutilisez une inscription existante qui laisse requestedAccessTokenVersion non défini, Entra émet des jetons v1.0 à la place. Décodez un exemple de jeton et vérifiez sa revendication ver ; si elle est 1.0, quatre éléments changent :

• Émetteur : La revendication iss est https://sts.windows.net/<TENANT_ID>/ au lieu de https://login.microsoftonline.com/<TENANT_ID>/v2.0. Enregistrez l'URL de l'émetteur exactement telle que la revendication iss de votre jeton la contient. Les deux URL partagent le même JWKS, donc le mode découverte fonctionne pour l'une ou l'autre.
• Sélecteur de l'assistant : Choisissez v1 (sts.windows.net) dans le sélecteur Token issuer de l'assistant Connect workload au lieu de v2.0 (login.microsoftonline.com).
• Audience : La revendication aud est l'URI d'identificateur que vous avez passé comme resource (par exemple, api://<APP_ID>), pas l'ID client de l'inscription. Définissez l'audience de la règle de fédération sur la valeur aud exacte de votre jeton décodé.
• Revendication d'ID client : L'ID client de l'identité appelante apparaît dans appid, pas dans azp. Les deux revendications n'apparaissent jamais dans le même jeton, donc une règle qui fait correspondre azp ne passe jamais avec un jeton v1.0.

Les revendications oid, sub et tid contiennent les mêmes valeurs dans les deux versions, donc le reste de ce guide s'applique sans modification.



Délimiter votre règle

Une règle de fédération peut faire correspondre le sujet du jeton avec subject_prefix en plus de (ou à la place de) la map claims ; consultez Sémantique de correspondance des règles pour comprendre comment les champs se combinent. Les valeurs sub d'Entra pour ces identités sont des GUID canoniques de longueur fixe, donc un subject_prefix contenant l'ID d'objet complet de 36 caractères ne correspond qu'à ce sujet ; c'est une propriété du format de sujet d'Entra, pas de subject_prefix en général.

Verrouillez le bloc match de la règle à la portée la plus étroite qui convient à votre cas d'usage :

• Faire correspondre oid comme valeur exacte : Définissez claims.oid sur l'ID d'objet complet de l'identité managée. Un subject_prefix défini sur cet ID d'objet complet est équivalent (l'assistant de la Console définit les deux) ; n'utilisez jamais un subject_prefix avec caractère générique ou GUID partiel, qui correspond à plus d'identités que prévu.
• Épingler tid comme défense en profondeur : L'URL de l'émetteur épingle déjà votre locataire, mais ajouter claims.tid protège contre une dérive de configuration si l'enregistrement de l'émetteur est modifié ultérieurement.
• Épingler l'audience : Définissez audience sur la valeur aud exacte de votre jeton décodé afin que les jetons émis pour d'autres applications soient rejetés.
• Utiliser une règle distincte pour chaque identité managée : Créez une règle pour chaque identité plutôt qu'une règle qui en autorise plusieurs, afin de pouvoir révoquer l'accès d'une seule charge de travail sans affecter les autres.



Étapes suivantes

• Consultez le modèle de configuration complet dans Workload Identity Federation.
• Consultez les guides des fournisseurs pour AWS, Google Cloud, GitHub Actions et Kubernetes.
• Pour les variables d'environnement, les fichiers de profil et la priorité des identifiants, consultez la référence WIF.