Claude Platform Docs
AdminIdentitätsanbieter

WIF mit Microsoft Entra ID verwenden

Föderiere verwaltete Azure-Identitäten und Entra Workload Identity mit der Claude API, damit deine Azure-Workloads Claude ohne statische API-Keys aufrufen können.

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

  1. Token-Audience registrieren: Erstelle eine „app registration“ (App-Registrierung) in deinem Microsoft-Entra-„tenant“ (Mandanten), die die „audience“ (Zielgruppe) der Claude API repräsentiert. Jeder Workload im Mandanten fordert Entra-Token für sie an.
  2. Identität für deine Plattform einrichten: Eine „managed identity“ (verwaltete Identität) auf VMs, VM Scale Sets, App Service, Functions und Container Apps oder Entra Workload Identity auf AKS.
  3. Anthropic konfigurieren: Registriere den Entra-„issuer“ (Aussteller) deines Mandanten, erstelle einen „service account“ (Dienstkonto) und schreibe eine „federation rule“ (Föderationsregel), die zu den „claims“ (Ansprüchen) des Tokens passt.
  4. Zur Laufzeit austauschen: Dein Workload tauscht sein von Entra ausgestelltes Token bei POST /v1/oauth/token gegen ein sk-ant-oat01-...-Anthropic-Zugriffstoken ein und ruft Claude damit auf.

Auf beiden Wegen trägt das Token, das du Anthropic vorlegst, deinen mandantenspezifischen Entra-Issuer sowie die Objekt-ID der verwalteten Identität in den Claims sub und oid; nur die Art, wie der Workload dieses Token erhält, unterscheidet sich. Wähle den Abschnitt, der dem Ausführungsort deines Workloads entspricht: Eine verwaltete Identität 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 den WIF-Konzepten: Dienstkonten, Föderations-Issuer und Föderationsregeln.
  • Ein Azure-Abonnement mit der Berechtigung, verwaltete Identitäten zuzuweisen (oder Entra Workload Identity auf AKS zu konfigurieren).
  • Die Berechtigung, eine App-Registrierung und einen „service principal“ (Dienstprinzipal) in deinem Microsoft-Entra-Mandanten zu erstellen (die gemeinsame Claude-API-Audience). Entra stellt Token nur für eine Audience aus, die im Mandanten existiert, daher ist der Schritt Token-Audience registrieren erforderlich, bevor irgendeine Token-Anforderung erfolgreich ist.
  • Deine Microsoft-Entra-Mandanten-ID. Du findest sie im Azure-Portal unter Microsoft Entra ID → Overview → Tenant ID.
  • Die Berechtigung, in der Claude Console Dienstkonten, Föderations-Issuer und Föderationsregeln für deine Anthropic-Organisation zu erstellen.

Token-Audience registrieren

Microsoft Entra ID stellt ein Token nur aus, wenn die angeforderte Audience in deinem Mandanten als App-Registrierung mit einem Dienstprinzipal existiert. Erstelle eine App-Registrierung, die die Claude-API-Audience repräsentiert; jeder Workload im Mandanten kann Token für sie anfordern. Ohne diese Registrierung schlagen Token-Anforderungen mit einem Fehler „resource not found in tenant“ fehl (AADSTS50001 von den Endpunkten der verwalteten Identität, 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-Zugriffstoken an und setze die Bezeichner-URI api://<APP_ID>.
az ad app update --id "$APP_ID" \
  --identifier-uris "api://$APP_ID" \
  --set api.requestedAccessTokenVersion=2

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

Eine verwaltete Identität verwenden

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

Die verwaltete Identität konfigurieren

  1. Eine verwaltete Identität anhängen

    Aktiviere eine systemseitig oder benutzerseitig zugewiesene verwaltete Identität auf deiner Azure-Ressource. Öffne im Azure-Portal die Ressource, gehe zu Identity und schalte System assigned ein (oder hänge eine benutzerseitig zugewiesene Identität an).

    Notiere nach dem Erstellen der Identität ihre Object (principal) ID. Diese GUID erscheint im ausgestellten Token sowohl als sub- als auch als oid-Claim, und deine Anthropic-Föderationsregel wird darauf abgleichen. Du findest sie auf der Seite Identity der Ressource; bei einer benutzerseitig zugewiesenen Identität ist es die Object (principal) ID auf der Seite Overview der Ressource der verwalteten Identität. (Eine verwaltete Identität hat in Microsoft Entra ID nur einen Dienstprinzipal, keine App-Registrierung.)

  2. Den Token-Endpunkt der Plattform finden

    Die Plattform stellt einen lokalen Token-Endpunkt bereit, sobald die Identität angehängt ist:

    • VMs und VM Scale Sets: IMDS unter http://169.254.169.254/metadata/identity/oauth2/token mit dem Header Metadata: true und api-version=2018-02-01.
    • App Service, Functions und Container Apps: Die URL in der Umgebungsvariablen IDENTITY_ENDPOINT mit dem Header X-IDENTITY-HEADER, gesetzt auf den Wert von IDENTITY_HEADER, und api-version=2019-08-01. IMDS ist auf diesen Plattformen nicht erreichbar.

    Wenn die Ressource mehr als eine benutzerseitig zugewiesene verwaltete Identität hat, füge der Token-Anforderung client_id=<IDENTITY_CLIENT_ID> hinzu, um eine auszuwählen. Azure empfiehlt, sie immer anzugeben. Ohne sie hängt das Ergebnis davon ab, ob auf der Ressource zusätzlich eine systemseitig zugewiesene Identität aktiviert ist: Falls ja, fällt die Anforderung stillschweigend auf diese Identität zurück und scheitert dann am oid-Abgleich deiner Föderationsregel; falls nein, schlägt die Anforderung sofort fehl, sobald eine zweite benutzerseitig zugewiesene Identität angehängt wird.

  3. Ein Beispiel-Token dekodieren

    Fordere ein Token vom Endpunkt an und dekodiere seine Payload, um die Claims zu bestätigen, auf die deine Föderationsregel abgleichen muss. (Den Dekodierbefehl findest du unter Fehlerbehebung bei einem fehlgeschlagenen Austausch.) Ein v2.0-Token für eine verwaltete Identität trägt diese Claims:

    {
  "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
}
    ClaimWertGleiche darauf ab, wenn
    oidDie Objekt-ID der verwalteten Identität, identisch mit subDu eine bestimmte verwaltete Identität autorisieren möchtest. Dies ist der Standard; die Regel in Anthropic konfigurieren gleicht darauf ab.
    azpDie Client-ID der aufrufenden IdentitätDu jeden Workload autorisieren möchtest, der sich eine App-Registrierung teilt. Bei einer verwalteten Identität ist azp für diese Identität eindeutig und damit äquivalent zu oid.
    audDie Client-ID der Audience-App-Registrierung (die <APP_ID>-GUID aus Token-Audience registrieren)Immer. Das Feld audience der Regel muss exakt dem aud-Wert des Tokens entsprechen.
    tidDeine Mandanten-IDDu „defense in depth“ (mehrschichtige Absicherung) möchtest. Die Issuer-URL legt den Mandanten bereits fest.

    Wenn der ver-Claim des dekodierten Tokens 1.0 ist, unterscheiden sich die Claim-Namen und -Werte. Siehe Wenn deine Token v1.0 sind, bevor du fortfährst.

Anthropic konfigurieren

Ö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 das Registrieren des Issuers, das Erstellen eines Dienstkontos und das Erstellen 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) in der Auswahl Token issuer des Assistenten. (Die Auswahl steht standardmäßig auf v1; dieser Standard existiert für Mandanten, die ältere Registrierungen wiederverwenden, die noch v1.0-Token ausgeben.) Entra veröffentlicht ein OIDC-Discovery-Dokument unter der mandantenspezifischen Issuer-URL, verwende also den Discovery-Modus. Jeder Microsoft-Entra-Mandant, 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-Abgleich begrenzt von vornherein, welche Identitäten ein Token eintauschen können, wie in Deine Regel eingrenzen beschrieben.

Föderationsregel: Gleiche auf die Objekt-ID der verwalteten Identität und deine Mandanten-ID ab. Für die v2.0-Token, die dieser Leitfaden konfiguriert, ist der audience-Wert die Client-ID der Audience-App-Registrierung (die <APP_ID>-GUID aus Token-Audience registrieren). 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.

Das Token beziehen und verwenden

Zur Laufzeit ruft dein Workload sein Entra-Token ab, tauscht es bei 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 rufen das Token der verwalteten Identität vom Token-Endpunkt der Plattform ab: IMDS auf VMs und VM Scale Sets oder der IDENTITY_ENDPOINT-Dienst auf App Service, Functions und Container Apps. Ersetze <APP_ID> im Ressourcenwert api://<APP_ID> durch die Client-ID der Audience-App-Registrierung aus Token-Audience registrieren.

import os

import anthropic
import requests
from anthropic import WorkloadIdentityCredentials

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

Die Einrichtung überprüfen

Führe von deiner Azure-Ressource aus den in Das Token beziehen und verwenden gezeigten cURL-Austausch aus und bestätige, dass POST /v1/oauth/token ein 200 mit einem access_token, das mit sk-ant-oat01- beginnt, und einem expires_in-Wert in Sekunden zurückgibt. Wenn der Austausch mit der undurchsichtigen 401-authentication_error-Antwort (Meldung Authentication failed) fehlschlägt, prüfe die Seite mit dem Authentifizierungsverlauf auf den Ablehnungsgrund, dekodiere dann das Entra-Token (den Befehl findest du unter Fehlerbehebung bei einem fehlgeschlagenen Austausch) 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 Token v1.0 sind.
  • Token-Lebensdauer: Token für verwaltete Identitäten tragen bis zu 24 Stunden zwischen iat und exp. Wenn der Issuer noch den Wert 7500 des Assistenten (oder den 1-Stunden-Standard) hat, erhöhe max_jwt_lifetime_seconds auf 86400, wie in Anthropic konfigurieren beschrieben.
  • Audience-Abweichung: Die audience der Regel muss exakt dem aud des Tokens entsprechen: der Client-ID der Audience-App-Registrierung für die v2.0-Token, die dieser Leitfaden konfiguriert.
  • Claim-Namen-Abweichung: Eine Regel, die auf einen Claim abgleicht, den das Token nicht trägt, besteht nie. v1.0-Token tragen die Client-ID in appid, nicht in azp; siehe Wenn deine Token v1.0 sind.

Entra Workload Identity auf AKS verwenden

Verwende diesen Weg, wenn dein Workload in einem AKS-Pod läuft. Entra Workload Identity föderiert ein Kubernetes-Dienstkonto mit einer benutzerseitig zugewiesenen verwalteten Identität: Kubernetes projiziert ein Dienstkonto-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 auf dem auf dieser Seite beschriebenen, über Entra vermittelten Weg zu bleiben, führt der Workload daher einen zweistufigen Austausch durch: Er löst zuerst das projizierte Token bei 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.

Entra Workload Identity konfigurieren

  1. Den OIDC-Issuer und Workload Identity auf deinem Cluster aktivieren

    Das Aktivieren von Workload Identity installiert den Mutating Webhook azure-workload-identity für dich; stelle ihn nur auf Nicht-AKS-Clustern manuell bereit. Erfasse die OIDC-Issuer-URL des Clusters für die föderierten Anmeldeinformationen, die du in einem späteren Schritt erstellst.

    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. Eine benutzerseitig zugewiesene verwaltete Identität erstellen

    Erfasse zwei Werte der Identität: Die Client ID kommt in die Annotation des Dienstkontos (und wird als AZURE_CLIENT_ID in den Pod injiziert), und die Object (principal) ID erscheint als oid-Claim, auf den deine Anthropic-Föderationsregel abgleicht.

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

# Gehört in die Service-Account-Annotation; wird als AZURE_CLIENT_ID in den Pod injiziert.
IDENTITY_CLIENT_ID=$(az identity show \
  --resource-group <RESOURCE_GROUP> \
  --name claude-inference-identity \
  --query clientId -o tsv)

# Erscheint als oid-Claim, auf den deine Föderationsregel matcht.
IDENTITY_OBJECT_ID=$(az identity show \
  --resource-group <RESOURCE_GROUP> \
  --name claude-inference-identity \
  --query principalId -o tsv)

  3. Das annotierte Kubernetes-Dienstkonto erstellen

    Der Webhook azure-workload-identity liest die Annotation azure.workload.identity/client-id, um AZURE_CLIENT_ID in den Pod zu injizieren, was die Beispiele in Das Token beziehen und verwenden aus der Umgebung lesen.

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

  4. Die föderierten Anmeldeinformationen auf der verwalteten Identität erstellen

    Die „federated credential“ (föderierten Anmeldeinformationen) vertrauen dem OIDC-Issuer deines Clusters für dieses spezifische Dienstkonto. Der Wert --audience api://AzureADTokenExchange ist Entras feste Audience für eingehende Kubernetes-Dienstkonto-Token; er hat nichts mit der Claude-API-Audience zu tun, die du zuvor registriert hast.

    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. Den Pod labeln und sein Dienstkonto setzen

    Der Pod muss das Label azure.workload.identity/use: "true" tragen und als das annotierte Dienstkonto laufen. Der Webhook injiziert dann AZURE_FEDERATED_TOKEN_FILE, AZURE_CLIENT_ID und AZURE_TENANT_ID in den Pod. Die Datei unter AZURE_FEDERATED_TOKEN_FILE enthält das von Kubernetes projizierte Dienstkonto-Token, signiert vom OIDC-Issuer des AKS-Clusters.

    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. Ein Beispiel-Token dekodieren

    Das Token, das deine Anthropic-Föderationsregel sieht, ist nicht die projizierte Datei; es ist das von Entra ausgestellte Token, das der client_credentials-Austausch zurückgibt. Führe aus einem gelabelten Pod heraus Schritt 1 des cURL-Beispiels in Das Token beziehen und verwenden aus und dekodiere das Ergebnis. Es trägt dieselbe Claim-Struktur wie der Weg mit verwalteter Identität:

    {
  "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 und oid sind die Objekt-ID der verwalteten Identität, aud ist die Client-ID der Audience-App-Registrierung und azp ist die Client-ID der verwalteten Identität (der Wert von AZURE_CLIENT_ID). Die Lebensdauer unterscheidet sich vom Weg mit verwalteter Identität: client_credentials-Token haben standardmäßig ein zufälliges Zeitfenster von 60 bis 90 Minuten zwischen iat und exp, nicht 24 Stunden.

Anthropic konfigurieren

Ö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 das Registrieren des Issuers, das Erstellen eines Dienstkontos und das Erstellen 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) in der Auswahl Token issuer des Assistenten. (Die Auswahl steht standardmäßig auf v1; dieser Standard existiert für Mandanten, die ältere Registrierungen wiederverwenden, die noch v1.0-Token ausgeben.) Entra veröffentlicht ein OIDC-Discovery-Dokument unter der mandantenspezifischen Issuer-URL, verwende also den Discovery-Modus. Jeder Microsoft-Entra-Mandant, 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-Abgleich begrenzt von vornherein, welche Identitäten ein Token eintauschen können, wie in Deine Regel eingrenzen beschrieben.

Föderationsregel: Gleiche auf die Objekt-ID der verwalteten Identität und deine Mandanten-ID ab. Für die v2.0-Token, die dieser Leitfaden konfiguriert, ist der audience-Wert die Client-ID der Audience-App-Registrierung (die <APP_ID>-GUID aus Token-Audience registrieren). 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.

Das 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 bei 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 Token-Audience registrieren; 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 verwalteten Identität, vom Webhook injiziert, und identifiziert den Aufrufer. Ersetze nicht die eine durch die andere.

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

Die Einrichtung überprüfen

Führe aus einem gelabelten Pod heraus den in Das Token beziehen und verwenden gezeigten cURL-Austausch aus und bestätige, dass POST /v1/oauth/token ein 200 mit einem access_token, das mit sk-ant-oat01- beginnt, und einem expires_in-Wert in Sekunden zurückgibt. Wenn der Austausch mit der undurchsichtigen 401-authentication_error-Antwort (Meldung Authentication failed) fehlschlägt, prüfe die Seite mit dem Authentifizierungsverlauf auf den Ablehnungsgrund, dekodiere dann das von Entra ausgestellte Token aus Schritt 1 (den Befehl findest du unter Fehlerbehebung bei einem fehlgeschlagenen Austausch) 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 Token v1.0 sind.
  • Token-Lebensdauer: Wenn eine Token-Lebensdauer-Richtlinie des Mandanten oder CAE das client_credentials-Token über 7500 Sekunden hinaus verlängert, erhöhe max_jwt_lifetime_seconds des Issuers, wie in Anthropic konfigurieren beschrieben.
  • Audience-Abweichung: Die audience der Regel muss exakt dem aud des Tokens entsprechen: der Client-ID der Audience-App-Registrierung für die v2.0-Token, die dieser Leitfaden konfiguriert.
  • Claim-Namen-Abweichung: Eine Regel, die auf einen Claim abgleicht, den das Token nicht trägt, besteht nie. v1.0-Token tragen die Client-ID in appid, nicht in azp; siehe Wenn deine Token v1.0 sind.

Wenn deine Token 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, die requestedAccessTokenVersion ungesetzt lässt, stellt Entra stattdessen v1.0-Token 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 der iss-Claim deines Tokens sie trägt. Die beiden URLs teilen sich dasselbe JWKS, sodass der Discovery-Modus für beide funktioniert.
  • Auswahl im Assistenten: Wähle v1 (sts.windows.net) in der Auswahl Token issuer des Assistenten „Connect workload“ statt v2.0 (login.microsoftonline.com).
  • Audience: Der aud-Claim ist die Bezeichner-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 abgleicht, gegen ein 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.

Deine Regel eingrenzen

Eine Föderationsregel kann das Subject des Tokens zusätzlich zur (oder anstelle der) claims-Map mit subject_prefix abgleichen; siehe Semantik des Regelabgleichs dazu, wie die Felder kombiniert werden. Entra-sub-Werte für diese Identitäten sind kanonische GUIDs fester Länge, sodass ein subject_prefix, das die vollständige 36-stellige Objekt-ID enthält, nur auf dieses Subject passt; 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:

  • oid als exakten Wert abgleichen: Setze claims.oid auf die vollständige Objekt-ID der verwalteten Identität. Ein auf diese vollständige Objekt-ID gesetztes subject_prefix ist äquivalent (der Console-Assistent setzt beides); verwende niemals ein Wildcard- oder Teil-GUID-subject_prefix, das auf mehr Identitäten passt, als du beabsichtigst.
  • tid als Defense in Depth festlegen: Die Issuer-URL legt deinen Mandanten bereits fest, aber das Hinzufügen von claims.tid schützt vor Konfigurationsdrift, falls der Issuer-Eintrag später bearbeitet wird.
  • Die Audience festlegen: Setze audience auf den exakten aud-Wert aus deinem dekodierten Token, damit für andere Anwendungen ausgestellte Token abgelehnt werden.
  • Eine separate Regel für jede verwaltete Identität verwenden: 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

Was this page helpful?