Usa WIF con Microsoft Entra ID

Las cargas de trabajo de Azure se autentican ante la API de Claude presentando un "JSON Web Token" (token web JSON), o JWT, emitido por Microsoft Entra ID, y luego intercambiándolo por un token de acceso de Anthropic de corta duración. La configuración sigue la misma forma en todas las plataformas de Azure:

1. Registra la audiencia del token: Crea un registro de aplicación en tu tenant de Microsoft Entra para representar la audiencia de la API de Claude. Cada carga de trabajo en el tenant solicita tokens de Entra para él.
2. Configura la identidad para tu plataforma: Una identidad administrada en VMs, VM Scale Sets, App Service, Functions y Container Apps, o Entra Workload Identity en AKS.
3. Configura Anthropic: Registra el emisor de Entra de tu tenant, crea una cuenta de servicio y escribe una regla de federación que coincida con los claims del token.
4. Intercambia en tiempo de ejecución: Tu carga de trabajo intercambia su token emitido por Entra en POST /v1/oauth/token por un token de acceso de Anthropic sk-ant-oat01-... y llama a Claude con él.

En ambas rutas, el token que presentas a Anthropic lleva el emisor de Entra específico de tu tenant y el ID de objeto de la identidad administrada en los claims sub y oid; solo difiere la forma en que la carga de trabajo obtiene ese token. Elige la sección según dónde se ejecuta tu carga de trabajo: Usa una identidad administrada para VMs, VM Scale Sets, App Service, Functions o Container Apps; Usa Entra Workload Identity en AKS para AKS.



Requisitos previos

• Familiaridad con los conceptos de WIF: cuentas de servicio, emisores de federación y reglas de federación.
• Una suscripción de Azure con permiso para asignar identidades administradas (o configurar Entra Workload Identity en AKS).
• Permiso para crear un registro de aplicación y un service principal en tu tenant de Microsoft Entra (la audiencia compartida de la API de Claude). Entra solo emite tokens para una audiencia que existe en el tenant, por lo que el paso Registra la audiencia del token es obligatorio antes de que cualquier solicitud de token tenga éxito.
• El ID de tu tenant de Microsoft Entra. Encuéntralo en el portal de Azure en Microsoft Entra ID → Overview → Tenant ID.
• Permiso para crear cuentas de servicio, emisores de federación y reglas de federación en la Claude Console para tu organización de Anthropic.



Registra la audiencia del token

Microsoft Entra ID solo emite un token cuando la audiencia solicitada existe en tu tenant como un registro de aplicación con un service principal. Crea un registro de aplicación para representar la audiencia de la API de Claude; cada carga de trabajo en el tenant puede solicitar tokens para él. Sin este registro, las solicitudes de token fallan con un error "resource not found in tenant" (AADSTS50001 desde los endpoints de identidad administrada, AADSTS500011 desde el endpoint de tokens de Entra).

# Crea el registro de aplicación que representa la audiencia de la API de Claude.
APP_ID=$(az ad app create --display-name claude-api-federation --query appId -o tsv)

# Solicita tokens de acceso v2.0 y configura el URI identificador api://<APP_ID>.
az ad app update --id "$APP_ID" \
  --identifier-uris "api://$APP_ID" \
  --set api.requestedAccessTokenVersion=2

# Crea el service principal para que la audiencia se resuelva en tu tenant.
az ad sp create --id "$APP_ID"



Usa una identidad administrada

Usa esta ruta cuando tu carga de trabajo se ejecuta en una VM, un VM Scale Set, App Service, Functions o Container Apps. La carga de trabajo solicita un JWT emitido por Entra para su identidad administrada asignada desde el endpoint de tokens local de la plataforma, y luego intercambia ese JWT con Anthropic.



Configura la identidad administrada



Configura Anthropic

En la Claude Console, abre Settings → Workload identity, haz clic en Connect workload y selecciona el mosaico Microsoft Entra. El asistente te guía a través del registro del emisor, la creación de una cuenta de servicio y la creación de una regla de federación.

El asistente crea estos recursos por ti. Usa los siguientes valores, ya sea que los ingreses en el asistente o los envíes a la Admin API:

Emisor de federación: Elige v2.0 (login.microsoftonline.com) en el selector Token issuer del asistente. (El selector tiene v1 como valor predeterminado; ese valor predeterminado existe para tenants que reutilizan registros más antiguos que todavía emiten tokens v1.0.) Entra publica un documento de descubrimiento OIDC en la URL del emisor por tenant, así que usa el modo de descubrimiento. Cada tenant de Microsoft Entra que federes necesita su propio registro de emisor.

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

Una vida útil aceptada más larga significa que un token de Entra filtrado permanece intercambiable durante más tiempo. Si un token se filtra, la palanca es deshabilitar la regla de federación; una coincidencia estricta de oid limita qué identidades pueden intercambiar un token en primer lugar, como se describe en Delimita tu regla.

Regla de federación: Haz coincidir el ID de objeto de la identidad administrada y el ID de tu tenant. Para los tokens v2.0 que configura esta guía, el valor de audience es el ID de cliente del registro de aplicación de la audiencia (el GUID <APP_ID> de Registra la audiencia del token). Usa el valor exacto de aud de tu token decodificado.

{
  "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 es la vida útil del token de acceso de Anthropic que devuelve el intercambio, no del token de Entra; el SDK lo actualiza por ti.



Adquiere y usa el token

En tiempo de ejecución, tu carga de trabajo obtiene su token de Entra, lo intercambia en POST /v1/oauth/token y usa el token bearer devuelto para llamar a Claude. Cada SDK de Anthropic maneja el intercambio y el ciclo de actualización cuando proporcionas un callable proveedor de tokens, como se muestra en los siguientes ejemplos. La pestaña cURL muestra el flujo sin procesar.

Los ejemplos obtienen el token de identidad administrada desde el endpoint de tokens de la plataforma: IMDS en VMs y VM Scale Sets, o el servicio IDENTITY_ENDPOINT en App Service, Functions y Container Apps. Reemplaza <APP_ID> en el valor de recurso api://<APP_ID> con el ID de cliente del registro de aplicación de la audiencia de Registra la audiencia del token.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

# El URI identificador del registro de aplicación de la audiencia (consulta Registrar la audiencia del token).
AUDIENCE = "api://<APP_ID>"


def fetch_entra_token() -> str:
    """Fetch a managed identity token from the platform's token endpoint."""
    # Con varias identidades asignadas por el usuario, agrega client_id=<IDENTITY_CLIENT_ID>
    # a los parámetros de la solicitud para seleccionar 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 configuración

Desde tu recurso de Azure, ejecuta el intercambio cURL que se muestra en Adquiere y usa el token y confirma que POST /v1/oauth/token devuelve un 200 con un access_token que comienza con sk-ant-oat01- y un valor expires_in en segundos. Ante un 400 invalid_grant, decodifica el token de Entra (consulta Soluciona problemas de un intercambio fallido para el comando) y verifica las causas más comunes del lado de Azure:

• Discrepancia de emisor: El issuer_url registrado debe coincidir exactamente con el claim iss del token. Un token v2.0 lleva https://login.microsoftonline.com/<TENANT_ID>/v2.0; si el claim ver decodificado es 1.0, consulta Si tus tokens son v1.0.
• Vida útil del token: Los tokens de identidad administrada llevan hasta 24 horas entre iat y exp. Si el emisor todavía tiene el 7500 del asistente (o el valor predeterminado de 1 hora), aumenta max_jwt_lifetime_seconds a 86400 como se describe en Configura Anthropic.
• Discrepancia de audiencia: El audience de la regla debe ser exactamente igual al aud del token: el ID de cliente del registro de aplicación de la audiencia para los tokens v2.0 que configura esta guía.
• Discrepancia de nombre de claim: Una regla que coincide con un claim que el token no lleva nunca pasa. Los tokens v1.0 llevan el ID de cliente en appid, no en azp; consulta Si tus tokens son v1.0.



Usa Entra Workload Identity en AKS

Usa esta ruta cuando tu carga de trabajo se ejecuta en un pod de AKS. Entra Workload Identity federa una cuenta de servicio de Kubernetes con una identidad administrada asignada por el usuario: Kubernetes proyecta un token de cuenta de servicio (firmado por el emisor OIDC del clúster de AKS) en el pod en la ruta indicada en AZURE_FEDERATED_TOKEN_FILE. Ese token proyectado no es un token emitido por Entra, por lo que para permanecer en la ruta mediada por Entra descrita en esta página, la carga de trabajo realiza un intercambio de dos saltos: primero canjea el token proyectado en https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token (concesión client_credentials federada) por un token de acceso emitido por Entra, y luego pasa ese token de Entra al SDK de Anthropic como el token de identidad.



Configura Entra Workload Identity



Configura Anthropic

En la Claude Console, abre Settings → Workload identity, haz clic en Connect workload y selecciona el mosaico Microsoft Entra. El asistente te guía a través del registro del emisor, la creación de una cuenta de servicio y la creación de una regla de federación.

El asistente crea estos recursos por ti. Usa los siguientes valores, ya sea que los ingreses en el asistente o los envíes a la Admin API:

Emisor de federación: Elige v2.0 (login.microsoftonline.com) en el selector Token issuer del asistente. (El selector tiene v1 como valor predeterminado; ese valor predeterminado existe para tenants que reutilizan registros más antiguos que todavía emiten tokens v1.0.) Entra publica un documento de descubrimiento OIDC en la URL del emisor por tenant, así que usa el modo de descubrimiento. Cada tenant de Microsoft Entra que federes necesita su propio registro de emisor.

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

Una vida útil aceptada más larga significa que un token de Entra filtrado permanece intercambiable durante más tiempo. Si un token se filtra, la palanca es deshabilitar la regla de federación; una coincidencia estricta de oid limita qué identidades pueden intercambiar un token en primer lugar, como se describe en Delimita tu regla.

Regla de federación: Haz coincidir el ID de objeto de la identidad administrada y el ID de tu tenant. Para los tokens v2.0 que configura esta guía, el valor de audience es el ID de cliente del registro de aplicación de la audiencia (el GUID <APP_ID> de Registra la audiencia del token). Usa el valor exacto de aud de tu token decodificado.

{
  "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 es la vida útil del token de acceso de Anthropic que devuelve el intercambio, no del token de Entra; el SDK lo actualiza por ti.



Adquiere y usa el token

En tiempo de ejecución, el pod realiza el intercambio de dos saltos: envía el token proyectado por Kubernetes (el archivo en AZURE_FEDERATED_TOKEN_FILE) al endpoint de tokens de Entra como una aserción client_credentials federada, y luego intercambia el token de acceso de Entra resultante en POST /v1/oauth/token. Cada SDK de Anthropic maneja el segundo intercambio y el ciclo de actualización cuando proporcionas la obtención de Entra como un callable proveedor de tokens, como se muestra en los siguientes ejemplos. La pestaña cURL muestra el flujo sin procesar.

Dos IDs de cliente diferentes aparecen en los ejemplos. <APP_ID> es el ID de cliente del registro de aplicación de la audiencia de Registra la audiencia del token; el scope api://<APP_ID>/.default le pide a Entra un token dirigido a esa audiencia. $AZURE_CLIENT_ID es el ID de cliente de la identidad administrada, inyectado por el webhook, e identifica al llamador. No sustituyas uno por el otro.

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 configuración

Desde dentro de un pod etiquetado, ejecuta el intercambio cURL que se muestra en Adquiere y usa el token y confirma que POST /v1/oauth/token devuelve un 200 con un access_token que comienza con sk-ant-oat01- y un valor expires_in en segundos. Ante un 400 invalid_grant, decodifica el token emitido por Entra del paso 1 (consulta Soluciona problemas de un intercambio fallido para el comando) y verifica las causas más comunes del lado de Azure:

• Discrepancia de emisor: El issuer_url registrado debe coincidir exactamente con el claim iss del token. Un token v2.0 lleva https://login.microsoftonline.com/<TENANT_ID>/v2.0; si el claim ver decodificado es 1.0, consulta Si tus tokens son v1.0.
• Vida útil del token: Si una política de vida útil de tokens del tenant o CAE extiende el token client_credentials más allá de 7500 segundos, aumenta el max_jwt_lifetime_seconds del emisor como se describe en Configura Anthropic.
• Discrepancia de audiencia: El audience de la regla debe ser exactamente igual al aud del token: el ID de cliente del registro de aplicación de la audiencia para los tokens v2.0 que configura esta guía.
• Discrepancia de nombre de claim: Una regla que coincide con un claim que el token no lleva nunca pasa. Los tokens v1.0 llevan el ID de cliente en appid, no en azp; consulta Si tus tokens son v1.0.



Si tus tokens son v1.0

Esta guía configura el registro de aplicación de la audiencia con api.requestedAccessTokenVersion: 2, por lo que cada token que muestra es v2.0. Si reutilizas un registro existente que deja requestedAccessTokenVersion sin establecer, Entra emite tokens v1.0 en su lugar. Decodifica un token de muestra y verifica su claim ver; si es 1.0, cambian cuatro cosas:

• Emisor: El claim iss es https://sts.windows.net/<TENANT_ID>/ en lugar de https://login.microsoftonline.com/<TENANT_ID>/v2.0. Registra la URL del emisor exactamente como la lleva el claim iss de tu token. Las dos URLs comparten el mismo JWKS, por lo que el modo de descubrimiento funciona para cualquiera de las dos.
• Selector del asistente: Elige v1 (sts.windows.net) en el selector Token issuer del asistente Connect workload en lugar de v2.0 (login.microsoftonline.com).
• Audiencia: El claim aud es el URI de identificador que pasaste como resource (por ejemplo, api://<APP_ID>), no el ID de cliente del registro. Establece el audience de la regla de federación al valor exacto de aud de tu token decodificado.
• Claim de ID de cliente: El ID de cliente de la identidad que llama aparece en appid, no en azp. Los dos claims nunca aparecen en el mismo token, por lo que una regla que coincide con azp nunca pasa contra un token v1.0.

Los claims oid, sub y tid llevan los mismos valores en ambas versiones, por lo que el resto de esta guía se aplica sin cambios.



Delimita tu regla

Una regla de federación puede coincidir con el sujeto del token usando subject_prefix además de (o en lugar de) el mapa claims; consulta Semántica de coincidencia de reglas para ver cómo se combinan los campos. Los valores sub de Entra para estas identidades son GUIDs canónicos de longitud fija, por lo que un subject_prefix que contenga el ID de objeto completo de 36 caracteres coincide solo con ese sujeto; esta es una propiedad del formato de sujeto de Entra, no de subject_prefix en general.

Bloquea el bloque match de la regla al alcance más estrecho que se ajuste a tu caso de uso:

• Haz coincidir oid como un valor exacto: Establece claims.oid al ID de objeto completo de la identidad administrada. Un subject_prefix establecido a ese ID de objeto completo es equivalente (el asistente de la Console establece ambos); nunca uses un subject_prefix comodín o con un GUID parcial, que coincide con más identidades de las que pretendes.
• Fija tid como defensa en profundidad: La URL del emisor ya fija tu tenant, pero agregar claims.tid protege contra la deriva de configuración si el registro del emisor se edita más adelante.
• Fija la audiencia: Establece audience al valor exacto de aud de tu token decodificado para que los tokens acuñados para otras aplicaciones sean rechazados.
• Usa una regla separada para cada identidad administrada: Crea una regla para cada identidad en lugar de una regla que autorice a varias, para que puedas revocar el acceso de una sola carga de trabajo sin afectar a las demás.



Próximos pasos

• Revisa el modelo de configuración completo en Workload Identity Federation.
• Consulta las guías de proveedores para AWS, Google Cloud, GitHub Actions y Kubernetes.
• Para variables de entorno, archivos de perfil y precedencia de credenciales, consulta la referencia de WIF.