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 le même schéma sur chaque plateforme Azure :

1. Enregistrez l'audience du jeton : Créez une « app registration » (inscription d'application) dans votre « tenant » (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. Configurez l'identité pour votre plateforme : Une « managed identity » (identité managée) sur les VM, les VM Scale Sets, App Service, Functions et Container Apps, ou Entra Workload Identity sur AKS.
3. Configurez Anthropic : Enregistrez l'émetteur Entra de votre locataire, créez un compte de service et écrivez une règle de fédération qui correspond aux « claims » (revendications) du jeton.
4. Échangez à l'exécution : Votre charge de travail échange son jeton émis par Entra à POST /v1/oauth/token contre un jeton d'accès Anthropic sk-ant-oat01-... et appelle Claude avec celui-ci.

Sur les deux chemins, le jeton que vous présentez à Anthropic porte 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'endroit où s'exécute 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

• Une connaissance des 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 « service principal » (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 réussir.
• L'ID de votre locataire Microsoft Entra. Trouvez-le 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 en tant qu'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'identifiant 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 ce chemin 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 auprès du point de terminaison de jeton local de la plateforme, puis échange ce JWT avec Anthropic.



Configurer l'identité managée



Configurer Anthropic

Dans la Claude Console, ouvrez Settings → Workload identity, cliquez sur Connect workload et sélectionnez la tuile Microsoft Entra. L'assistant vous guide dans 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 défini par défaut sur v1 ; cette valeur par défaut existe pour les locataires réutilisant des inscriptions plus anciennes qui émettent encore des jetons v1.0.) Entra publie un document de découverte OIDC à l'URL d'émetteur propre à chaque locataire, utilisez donc 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 fuit, le levier consiste à désactiver la règle de fédération ; une correspondance oid stricte limite dès le départ les identités qui peuvent échanger un jeton, comme décrit dans Délimiter votre règle.

Règle de fédération : Effectuez la correspondance sur l'ID d'objet de l'identité managée et l'ID de votre 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 renvoyé par l'échange, pas celle du jeton Entra ; le SDK l'actualise pour vous.



Acquérir et utiliser le jeton

À l'exécution, votre charge de travail récupère son jeton Entra, l'échange à POST /v1/oauth/token et utilise le jeton bearer renvoyé pour appeler Claude. Chaque SDK Anthropic gère l'échange et la boucle d'actualisation lorsque vous fournissez un appelable fournisseur de jetons, comme le montrent 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 les 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'identifiant de l'inscription d'application de l'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 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"))



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 côté Azure les plus courantes :

• Incohérence d'émetteur : L'issuer_url enregistrée doit correspondre exactement à la revendication iss du jeton. Un jeton v2.0 porte 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 portent jusqu'à 24 heures entre iat et exp. Si l'émetteur a toujours la valeur 7500 de l'assistant (ou la valeur par défaut d'une heure), augmentez max_jwt_lifetime_seconds à 86400 comme décrit dans Configurer Anthropic.
• Incohérence 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.
• Incohérence de nom de revendication : Une règle qui effectue la correspondance sur une revendication que le jeton ne porte pas ne passe jamais. Les jetons v1.0 portent l'ID client dans appid, pas dans azp ; consultez Si vos jetons sont en v1.0.



Utiliser Entra Workload Identity sur AKS

Utilisez ce chemin 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 affecté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 sauts : elle échange d'abord le jeton projeté à https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token (octroi 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 tuile Microsoft Entra. L'assistant vous guide dans 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 défini par défaut sur v1 ; cette valeur par défaut existe pour les locataires réutilisant des inscriptions plus anciennes qui émettent encore des jetons v1.0.) Entra publie un document de découverte OIDC à l'URL d'émetteur propre à chaque locataire, utilisez donc 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 fuit, le levier consiste à désactiver la règle de fédération ; une correspondance oid stricte limite dès le départ les identités qui peuvent échanger un jeton, comme décrit dans Délimiter votre règle.

Règle de fédération : Effectuez la correspondance sur l'ID d'objet de l'identité managée et l'ID de votre 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 renvoyé par l'échange, pas celle du jeton Entra ; le SDK l'actualise pour vous.



Acquérir et utiliser le jeton

À l'exécution, le pod effectue l'échange en deux sauts : il envoie le jeton projeté par Kubernetes (le fichier à 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 à POST /v1/oauth/token. Chaque SDK Anthropic gère le second échange et la boucle d'actualisation lorsque vous fournissez la récupération Entra comme appelable fournisseur de jetons, comme le montrent 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-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"))



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 côté Azure les plus courantes :

• Incohérence d'émetteur : L'issuer_url enregistrée doit correspondre exactement à la revendication iss du jeton. Un jeton v2.0 porte 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 stratégie de durée de vie des jetons du locataire ou la 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.
• Incohérence 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.
• Incohérence de nom de revendication : Une règle qui effectue la correspondance sur une revendication que le jeton ne porte pas ne passe jamais. Les jetons v1.0 portent 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 montre 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 jeton d'exemple et vérifiez sa revendication ver ; si elle est 1.0, quatre choses 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 porte. 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 transmis 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 effectue la correspondance sur azp ne passe jamais avec un jeton v1.0.

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



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 carte claims ; consultez Sémantique de correspondance des règles pour savoir 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 sur la portée la plus étroite qui convient à votre cas d'usage :

• Faites 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 générique ou avec un GUID partiel, qui correspond à plus d'identités que vous ne le souhaitez.
• Épinglez tid comme défense en profondeur : L'URL de l'émetteur épingle déjà votre locataire, mais l'ajout de claims.tid protège contre une dérive de configuration si l'enregistrement de l'émetteur est modifié ultérieurement.
• Épinglez 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.
• Utilisez une règle distincte pour chaque identité managée : Créez une règle pour chaque identité plutôt qu'une seule règle qui en autorise plusieurs, afin de pouvoir révoquer l'accès d'une seule charge de travail sans affecter les autres.



Prochaines étapes

• 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 informations d'identification, consultez la référence WIF.