WIF mit Microsoft Entra ID verwenden

Azure-Workloads authentifizieren sich bei der Claude API, indem sie ein von Microsoft Entra ID ausgestelltes JSON Web Token (JWT) vorlegen und es dann gegen ein kurzlebiges Anthropic-Zugriffstoken eintauschen. Die Einrichtung folgt auf jeder Azure-Plattform demselben Muster:

1. Registriere die Token-Audience: Erstelle eine App-Registrierung in deinem Microsoft Entra-Tenant, die die Claude API-Audience repräsentiert. Jeder Workload im Tenant fordert Entra-Tokens dafür an.
2. Richte die Identität für deine Plattform ein: Eine Managed Identity auf VMs, VM Scale Sets, App Service, Functions und Container Apps, oder Entra Workload Identity auf AKS.
3. Konfiguriere Anthropic: Registriere den Entra-Issuer deines Tenants, erstelle ein Service-Konto und schreibe eine Föderationsregel, die mit den Claims des Tokens übereinstimmt.
4. Tausche zur Laufzeit: Dein Workload tauscht sein von Entra ausgestelltes Token unter POST /v1/oauth/token gegen ein sk-ant-oat01-... Anthropic-Zugriffstoken ein und ruft damit Claude auf.

Auf beiden Pfaden trägt das Token, das du Anthropic vorlegst, deinen tenant-spezifischen Entra-Issuer und die Objekt-ID der Managed Identity in den Claims sub und oid; nur wie der Workload dieses Token erhält, unterscheidet sich. Wähle den Abschnitt für den Ort, an dem dein Workload läuft: Eine Managed Identity verwenden für VMs, VM Scale Sets, App Service, Functions oder Container Apps; Entra Workload Identity auf AKS verwenden für AKS.



Voraussetzungen

• Vertrautheit mit WIF-Konzepten: Service-Konten, Föderations-Issuer und Föderationsregeln.
• Ein Azure-Abonnement mit der Berechtigung, Managed Identities zuzuweisen (oder Entra Workload Identity auf AKS zu konfigurieren).
• Die Berechtigung, eine App-Registrierung und einen Service Principal in deinem Microsoft Entra-Tenant zu erstellen (die gemeinsame Claude API-Audience). Entra stellt nur Tokens für eine Audience aus, die im Tenant existiert, daher ist der Schritt Registriere die Token-Audience erforderlich, bevor eine Token-Anfrage erfolgreich sein kann.
• Deine Microsoft Entra-Tenant-ID. Du findest sie im Azure-Portal unter Microsoft Entra ID → Overview → Tenant ID.
• Die Berechtigung, Service-Konten, Föderations-Issuer und Föderationsregeln in der Claude Console für deine Anthropic-Organisation zu erstellen.



Registriere die Token-Audience

Microsoft Entra ID stellt ein Token nur aus, wenn die angeforderte Audience in deinem Tenant als App-Registrierung mit einem Service Principal existiert. Erstelle eine App-Registrierung, die die Claude API-Audience repräsentiert; jeder Workload im Tenant kann Tokens dafür anfordern. Ohne diese Registrierung schlagen Token-Anfragen mit einem „resource not found in tenant"-Fehler fehl (AADSTS50001 von den Managed-Identity-Endpunkten, AADSTS500011 vom Entra-Token-Endpunkt).

# Erstelle die App-Registrierung, die die Claude API-Audience repräsentiert.
APP_ID=$(az ad app create --display-name claude-api-federation --query appId -o tsv)

# Fordere v2.0-Access-Tokens an und setze die Identifier-URI api://<APP_ID>.
az ad app update --id "$APP_ID" \
  --identifier-uris "api://$APP_ID" \
  --set api.requestedAccessTokenVersion=2

# Erstelle den Service Principal, damit die Audience in deinem Tenant aufgelöst wird.
az ad sp create --id "$APP_ID"



Eine Managed Identity verwenden

Verwende diesen Pfad, wenn dein Workload auf einer VM, einem VM Scale Set, App Service, Functions oder Container Apps läuft. Der Workload fordert ein von Entra ausgestelltes JWT für seine zugewiesene Managed Identity vom lokalen Token-Endpunkt der Plattform an und tauscht dieses JWT dann bei Anthropic ein.



Konfiguriere die Managed Identity



Konfiguriere Anthropic

Öffne in der Claude Console Settings → Workload identity, klicke auf Connect workload und wähle die Kachel Microsoft Entra. Der Assistent führt dich durch die Registrierung des Issuers, die Erstellung eines Service-Kontos und die Erstellung einer Föderationsregel.

Der Assistent erstellt diese Ressourcen für dich. Verwende die folgenden Werte, unabhängig davon, ob du sie im Assistenten eingibst oder an die Admin API sendest:

Föderations-Issuer: Wähle v2.0 (login.microsoftonline.com) im Token issuer-Selektor des Assistenten. (Der Selektor steht standardmäßig auf v1; dieser Standard existiert für Tenants, die ältere Registrierungen wiederverwenden, die noch v1.0-Tokens ausgeben.) Entra veröffentlicht ein OIDC-Discovery-Dokument unter der tenant-spezifischen Issuer-URL, verwende also den Discovery-Modus. Jeder Microsoft Entra-Tenant, den du föderierst, benötigt einen eigenen Issuer-Eintrag.

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

Eine längere akzeptierte Lebensdauer bedeutet, dass ein geleaktes Entra-Token länger eintauschbar bleibt. Wenn ein Token leakt, ist der Hebel das Deaktivieren der Föderationsregel; ein enger oid-Match begrenzt von vornherein, welche Identitäten ein Token eintauschen können, wie in Begrenze den Geltungsbereich deiner Regel beschrieben.

Föderationsregel: Matche auf die Objekt-ID der Managed Identity und deine Tenant-ID. Für die v2.0-Tokens, die dieser Leitfaden konfiguriert, ist der audience-Wert die Client-ID der Audience-App-Registrierung (die <APP_ID>-GUID aus Registriere die Token-Audience). Verwende den exakten aud-Wert aus deinem dekodierten Token.

{
  "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 ist die Lebensdauer des Anthropic-Zugriffstokens, das der Austausch zurückgibt, nicht die des Entra-Tokens; das SDK aktualisiert es für dich.



Token beziehen und verwenden

Zur Laufzeit holt dein Workload sein Entra-Token, tauscht es unter POST /v1/oauth/token ein und verwendet das zurückgegebene Bearer-Token, um Claude aufzurufen. Jedes Anthropic SDK übernimmt den Austausch und die Aktualisierungsschleife, wenn du ein Token-Provider-Callable bereitstellst, wie in den folgenden Beispielen gezeigt. Der cURL-Tab zeigt den rohen Ablauf.

Die Beispiele holen das Managed-Identity-Token vom Token-Endpunkt der Plattform: IMDS auf VMs und VM Scale Sets oder der IDENTITY_ENDPOINT-Dienst auf App Service, Functions und Container Apps. Ersetze <APP_ID> im api://<APP_ID>-Ressourcenwert durch die Client-ID der Audience-App-Registrierung aus Registriere die Token-Audience.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

# Der Identifier-URI der Audience-App-Registrierung (siehe "Token-Audience registrieren").
AUDIENCE = "api://<APP_ID>"


def fetch_entra_token() -> str:
    """Fetch a managed identity token from the platform's token endpoint."""
    # Bei mehreren benutzerzugewiesenen Identitäten füge client_id=<IDENTITY_CLIENT_ID>
    # zu den Request-Parametern hinzu, um eine auszuwählen.
    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 oder 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"))



Überprüfe die Einrichtung

Führe von deiner Azure-Ressource aus den in Token beziehen und verwenden gezeigten cURL-Austausch aus und bestätige, dass POST /v1/oauth/token eine 200 mit einem access_token, das mit sk-ant-oat01- beginnt, und einem expires_in-Wert in Sekunden zurückgibt. Bei 400 invalid_grant dekodiere das Entra-Token (siehe Einen fehlgeschlagenen Austausch beheben für den Befehl) und prüfe die häufigsten Azure-seitigen Ursachen:

• Issuer-Abweichung: Die registrierte issuer_url muss exakt mit dem iss-Claim des Tokens übereinstimmen. Ein v2.0-Token trägt https://login.microsoftonline.com/<TENANT_ID>/v2.0; wenn der dekodierte ver-Claim 1.0 ist, siehe Wenn deine Tokens v1.0 sind.
• Token-Lebensdauer: Managed-Identity-Tokens tragen bis zu 24 Stunden zwischen iat und exp. Wenn der Issuer noch die 7500 des Assistenten (oder den 1-Stunden-Standard) hat, erhöhe max_jwt_lifetime_seconds auf 86400, wie in Konfiguriere Anthropic beschrieben.
• Audience-Abweichung: Die audience der Regel muss exakt dem aud des Tokens entsprechen: die Client-ID der Audience-App-Registrierung für die v2.0-Tokens, die dieser Leitfaden konfiguriert.
• Claim-Namen-Abweichung: Eine Regel, die auf einen Claim matcht, den das Token nicht trägt, besteht nie. v1.0-Tokens tragen die Client-ID in appid, nicht in azp; siehe Wenn deine Tokens v1.0 sind.



Entra Workload Identity auf AKS verwenden

Verwende diesen Pfad, wenn dein Workload in einem AKS-Pod läuft. Entra Workload Identity föderiert ein Kubernetes-Service-Konto mit einer benutzerseitig zugewiesenen Managed Identity: Kubernetes projiziert ein Service-Konto-Token (signiert vom OIDC-Issuer des AKS-Clusters) in den Pod unter dem Pfad in AZURE_FEDERATED_TOKEN_FILE. Dieses projizierte Token ist kein von Entra ausgestelltes Token. Um also auf dem auf dieser Seite beschriebenen Entra-vermittelten Pfad zu bleiben, führt der Workload einen zweistufigen Austausch durch: Er löst zuerst das projizierte Token unter https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token (föderierter client_credentials-Grant) gegen ein von Entra ausgestelltes Zugriffstoken ein und übergibt dann dieses Entra-Token als Identity-Token an das Anthropic SDK.



Konfiguriere Entra Workload Identity



Konfiguriere Anthropic

Öffne in der Claude Console Settings → Workload identity, klicke auf Connect workload und wähle die Kachel Microsoft Entra. Der Assistent führt dich durch die Registrierung des Issuers, die Erstellung eines Service-Kontos und die Erstellung einer Föderationsregel.

Der Assistent erstellt diese Ressourcen für dich. Verwende die folgenden Werte, unabhängig davon, ob du sie im Assistenten eingibst oder an die Admin API sendest:

Föderations-Issuer: Wähle v2.0 (login.microsoftonline.com) im Token issuer-Selektor des Assistenten. (Der Selektor steht standardmäßig auf v1; dieser Standard existiert für Tenants, die ältere Registrierungen wiederverwenden, die noch v1.0-Tokens ausgeben.) Entra veröffentlicht ein OIDC-Discovery-Dokument unter der tenant-spezifischen Issuer-URL, verwende also den Discovery-Modus. Jeder Microsoft Entra-Tenant, den du föderierst, benötigt einen eigenen Issuer-Eintrag.

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

Eine längere akzeptierte Lebensdauer bedeutet, dass ein geleaktes Entra-Token länger eintauschbar bleibt. Wenn ein Token leakt, ist der Hebel das Deaktivieren der Föderationsregel; ein enger oid-Match begrenzt von vornherein, welche Identitäten ein Token eintauschen können, wie in Begrenze den Geltungsbereich deiner Regel beschrieben.

Föderationsregel: Matche auf die Objekt-ID der Managed Identity und deine Tenant-ID. Für die v2.0-Tokens, die dieser Leitfaden konfiguriert, ist der audience-Wert die Client-ID der Audience-App-Registrierung (die <APP_ID>-GUID aus Registriere die Token-Audience). Verwende den exakten aud-Wert aus deinem dekodierten Token.

{
  "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 ist die Lebensdauer des Anthropic-Zugriffstokens, das der Austausch zurückgibt, nicht die des Entra-Tokens; das SDK aktualisiert es für dich.



Token beziehen und verwenden

Zur Laufzeit führt der Pod den zweistufigen Austausch durch: Er sendet das von Kubernetes projizierte Token (die Datei unter AZURE_FEDERATED_TOKEN_FILE) als föderierte client_credentials-Assertion an Entras Token-Endpunkt und tauscht dann das resultierende Entra-Zugriffstoken unter POST /v1/oauth/token ein. Jedes Anthropic SDK übernimmt den zweiten Austausch und die Aktualisierungsschleife, wenn du den Entra-Abruf als Token-Provider-Callable bereitstellst, wie in den folgenden Beispielen gezeigt. Der cURL-Tab zeigt den rohen Ablauf.

In den Beispielen erscheinen zwei verschiedene Client-IDs. <APP_ID> ist die Client-ID der Audience-App-Registrierung aus Registriere die Token-Audience; der Scope api://<APP_ID>/.default fordert von Entra ein Token an, das an diese Audience adressiert ist. $AZURE_CLIENT_ID ist die Client-ID der Managed Identity, vom Webhook injiziert, und identifiziert den Aufrufer. Verwechsle die beiden nicht.

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



Überprüfe die Einrichtung

Führe aus einem gelabelten Pod heraus den in Token beziehen und verwenden gezeigten cURL-Austausch aus und bestätige, dass POST /v1/oauth/token eine 200 mit einem access_token, das mit sk-ant-oat01- beginnt, und einem expires_in-Wert in Sekunden zurückgibt. Bei 400 invalid_grant dekodiere das von Entra ausgestellte Token aus Schritt 1 (siehe Einen fehlgeschlagenen Austausch beheben für den Befehl) und prüfe die häufigsten Azure-seitigen Ursachen:

• Issuer-Abweichung: Die registrierte issuer_url muss exakt mit dem iss-Claim des Tokens übereinstimmen. Ein v2.0-Token trägt https://login.microsoftonline.com/<TENANT_ID>/v2.0; wenn der dekodierte ver-Claim 1.0 ist, siehe Wenn deine Tokens v1.0 sind.
• Token-Lebensdauer: Wenn eine Tenant-Token-Lebensdauer-Richtlinie oder CAE das client_credentials-Token über 7500 Sekunden hinaus verlängert, erhöhe max_jwt_lifetime_seconds des Issuers, wie in Konfiguriere Anthropic beschrieben.
• Audience-Abweichung: Die audience der Regel muss exakt dem aud des Tokens entsprechen: die Client-ID der Audience-App-Registrierung für die v2.0-Tokens, die dieser Leitfaden konfiguriert.
• Claim-Namen-Abweichung: Eine Regel, die auf einen Claim matcht, den das Token nicht trägt, besteht nie. v1.0-Tokens tragen die Client-ID in appid, nicht in azp; siehe Wenn deine Tokens v1.0 sind.



Wenn deine Tokens v1.0 sind

Dieser Leitfaden konfiguriert die Audience-App-Registrierung mit api.requestedAccessTokenVersion: 2, sodass jedes gezeigte Token v2.0 ist. Wenn du eine bestehende Registrierung wiederverwendest, bei der requestedAccessTokenVersion nicht gesetzt ist, stellt Entra stattdessen v1.0-Tokens aus. Dekodiere ein Beispiel-Token und prüfe seinen ver-Claim; wenn er 1.0 ist, ändern sich vier Dinge:

• Issuer: Der iss-Claim ist https://sts.windows.net/<TENANT_ID>/ statt https://login.microsoftonline.com/<TENANT_ID>/v2.0. Registriere die Issuer-URL exakt so, wie sie der iss-Claim deines Tokens trägt. Die beiden URLs teilen sich dasselbe JWKS, sodass der Discovery-Modus für beide funktioniert.
• Assistenten-Selektor: Wähle v1 (sts.windows.net) im Token issuer-Selektor des Connect-workload-Assistenten statt v2.0 (login.microsoftonline.com).
• Audience: Der aud-Claim ist die Identifier-URI, die du als resource übergeben hast (zum Beispiel api://<APP_ID>), nicht die Client-ID der Registrierung. Setze die audience der Föderationsregel auf den exakten aud-Wert aus deinem dekodierten Token.
• Client-ID-Claim: Die Client-ID der aufrufenden Identität erscheint in appid, nicht in azp. Die beiden Claims erscheinen nie im selben Token, sodass eine Regel, die auf azp matcht, bei einem v1.0-Token nie besteht.

Die Claims oid, sub und tid tragen in beiden Versionen dieselben Werte, sodass der Rest dieses Leitfadens unverändert gilt.



Begrenze den Geltungsbereich deiner Regel

Eine Föderationsregel kann das Subject des Tokens zusätzlich zur (oder anstelle der) claims-Map mit subject_prefix matchen; siehe Regel-Matching-Semantik dafür, wie die Felder kombiniert werden. Entra-sub-Werte für diese Identitäten sind kanonische GUIDs fester Länge, sodass ein subject_prefix, der die vollständige 36-stellige Objekt-ID enthält, nur dieses Subject matcht; dies ist eine Eigenschaft von Entras Subject-Format, nicht von subject_prefix im Allgemeinen.

Beschränke den match-Block der Regel auf den engsten Geltungsbereich, der zu deinem Anwendungsfall passt:

• Matche oid als exakten Wert: Setze claims.oid auf die vollständige Objekt-ID der Managed Identity. Ein subject_prefix, der auf diese vollständige Objekt-ID gesetzt ist, ist äquivalent (der Console-Assistent setzt beide); verwende niemals einen Wildcard- oder Teil-GUID-subject_prefix, der mehr Identitäten matcht, als du beabsichtigst.
• Fixiere tid als Defense in Depth: Die Issuer-URL legt deinen Tenant bereits fest, aber das Hinzufügen von claims.tid schützt vor Konfigurationsdrift, falls der Issuer-Eintrag später bearbeitet wird.
• Fixiere die Audience: Setze audience auf den exakten aud-Wert aus deinem dekodierten Token, damit Tokens, die für andere Anwendungen ausgestellt wurden, abgelehnt werden.
• Verwende eine separate Regel für jede Managed Identity: Erstelle eine Regel für jede Identität statt einer Regel, die mehrere autorisiert, damit du den Zugriff eines einzelnen Workloads widerrufen kannst, ohne andere zu beeinträchtigen.



Nächste Schritte

• Sieh dir das vollständige Konfigurationsmodell in Workload Identity Federation an.
• Siehe die Provider-Leitfäden für AWS, Google Cloud, GitHub Actions und Kubernetes.
• Für Umgebungsvariablen, Profildateien und Anmeldeinformations-Priorität siehe die WIF-Referenz.