WIF mit AWS verwenden

AWS-Workloads können sich ohne statische API-Keys bei der Claude API authentifizieren, indem sie ein von AWS signiertes OIDC-Identitäts-Token austauschen. Der empfohlene Weg ruft die AWS STS GetWebIdentityToken API auf, die überall dort funktioniert, wo der Workload über AWS-Anmeldeinformationen verfügt: Lambda, EC2, ECS und EKS. EKS-Workloads können alternativ den Kubernetes-Projected-Token-Weg verwenden, der weniger Konfigurationsschritte erfordert, aber nur innerhalb eines Pods funktioniert.

Diese Anleitung zeigt beide Wege. Für die zugrunde liegenden Konzepte (Service-Accounts, Federation-Issuer und Federation-Regeln) siehe Workload Identity Federation.



Voraussetzungen

• Vertrautheit mit WIF-Konzepten: Service-Accounts, Federation-Issuer und Federation-Regeln.
• Ein AWS-Workload (EKS-Pod, ECS-Task, Lambda-Funktion oder EC2-Instanz) mit einer zugeordneten IAM-Rolle.
• Die aws-CLI oder ein AWS-SDK, das im Workload verfügbar ist.
• Berechtigung zum Erstellen von Service-Accounts, Federation-Issuern und Federation-Regeln in der Claude Console für deine Anthropic-Organisation.



STS-Web-Identity-Tokens verwenden (empfohlen)

Die AWS STS GetWebIdentityToken API gibt ein von AWS signiertes OIDC-Token zurück, das die IAM-Identität des Aufrufers bestätigt. Da sie die vorhandenen AWS-Anmeldeinformationen des Workloads verwendet, deckt dieselbe Integration Lambda, EC2, ECS und EKS ab.



AWS konfigurieren



Anthropic konfigurieren

Öffne in der Claude Console Settings → Workload identity, klicke auf Connect workload und wähle die AWS-Kachel aus. Der Assistent führt dich durch die Registrierung des Issuers, das Erstellen eines Service-Accounts und das Erstellen einer Federation-Regel.

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:

Federation-Issuer: Registriere die kontospezifische STS-Issuer-URL, die du im vorherigen Schritt kopiert hast. Sie stellt einen öffentlichen JWKS-Endpunkt bereit, verwende also den Discovery-Modus.

{
  "name": "aws-sts",
  "issuer_url": "https://<uuid>.tokens.sts.global.api.aws",
  "jwks": { "type": "discovery" }
}

Federation-Regel: Matche die Audience, die du an GetWebIdentityToken übergibst, und die IAM-Rollen-ARN der aufrufenden Rolle im sub-Claim. Der sub-Wert ist die IAM-Rollen-ARN des Workloads, der die API aufgerufen hat, in der Form arn:aws:iam::<account>:role/<role-name>. Das Token enthält außerdem einen https://sts.amazonaws.com/-Claim mit aws_account, org_id, principal_id und allen request_tags, die du übergeben hast; du kannst diese mit der claims-Map der Regel oder einer CEL-condition für eine feinere Steuerung matchen.

{
  "name": "prod-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "arn:aws:iam::123456789012:role/inference-worker",
    "audience": "https://api.anthropic.com"
  },
  "target": { "type": "service_account", "service_account_id": "svac_..." },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Sei so spezifisch, wie es der Workload erlaubt. Matche die exakte Rollen-ARN und erweitere subject_prefix nur dann (zum Beispiel auf arn:aws:iam::123456789012:role/*), wenn mehrere IAM-Rollen demselben Anthropic-Service-Account zugeordnet werden sollen.



Token abrufen und verwenden

Rufe GetWebIdentityToken mit https://api.anthropic.com als Audience auf und übergib das Ergebnis dann an die Federation-Credentials des SDK. Der Token-Provider ist ein Callable, sodass das SDK STS bei jedem Refresh erneut aufruft.

import os

import anthropic
import boto3
from anthropic import WorkloadIdentityCredentials


def get_sts_web_identity_token() -> str:
    sts = boto3.client("sts", region_name="us-east-1")
    resp = sts.get_web_identity_token(
        Audience=["https://api.anthropic.com"],
        SigningAlgorithm="RS256",
        DurationSeconds=900,
    )
    return resp["WebIdentityToken"]


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=get_sts_web_identity_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 AWS"}],
)
print(message.content[0].text)



Setup überprüfen

Tausche von innerhalb des Workloads ein von STS ausgestelltes Token direkt aus und prüfe die Antwort:

JWT=$(aws sts get-web-identity-token \
  --region us-east-1 \
  --audience "https://api.anthropic.com" \
  --signing-algorithm RS256 \
  --duration-seconds 900 \
  --query WebIdentityToken --output text)

curl -sS https://api.anthropic.com/v1/oauth/token \
  -H "content-type: application/json" \
  -d "{
    \"grant_type\": \"urn:ietf:params:oauth:grant-type:jwt-bearer\",
    \"assertion\": \"$JWT\",
    \"federation_rule_id\": \"fdrl_...\",
    \"organization_id\": \"00000000-0000-0000-0000-000000000000\",
    \"service_account_id\": \"svac_...\",
    \"workspace_id\": \"wrkspc_...\"
  }" | jq

Ein erfolgreicher Austausch gibt ein access_token zurück, das mit sk-ant-oat01- beginnt, sowie einen expires_in-Wert in Sekunden. Bei 400 invalid_grant siehe Fehlerbehebung bei einem fehlgeschlagenen Austausch; die häufigste Ursache auf AWS-Seite ist eine iss-Nichtübereinstimmung (die kontospezifische STS-Issuer-URL muss exakt mit der registrierten issuer_url übereinstimmen).



EKS-Projected-Service-Account-Tokens verwenden

Wenn dein Workload in einem EKS-Pod läuft, kannst du den STS-Aufruf überspringen und ein von Kubernetes projiziertes Service-Account-Token direkt von der Festplatte lesen. Kubernetes projiziert nativ ein OIDC-kompatibles Token in den Pod, und das SDK kann es aus einem Dateipfad lesen, sodass kein Token-Provider-Callable erforderlich ist. Dieser Weg hat zwei AWS-Konfigurationsschritte weniger als der STS-Weg, funktioniert aber nur innerhalb eines Pods; der zugrunde liegende Mechanismus ist derselbe wie bei der generischen Kubernetes-Integration.

Dieser Weg erfordert zusätzlich einen EKS-Cluster mit einem aktivierten IAM-OIDC-Provider und kubectl-Zugriff auf den Cluster.



Deinen EKS-Cluster konfigurieren



Anthropic konfigurieren

Öffne in der Claude Console Settings → Workload identity, klicke auf Connect workload und wähle die AWS-Kachel aus. Der Assistent führt dich durch die Registrierung des Issuers, das Erstellen eines Service-Accounts und das Erstellen einer Federation-Regel.

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:

Federation-Issuer: EKS-Issuer stellen einen öffentlichen JWKS-Endpunkt bereit, verwende also den Discovery-Modus. Die Issuer-URL muss exakt mit dem iss-Claim des Tokens übereinstimmen. Registriere einen Issuer pro Cluster.

{
  "name": "prod-eks-uswest2",
  "issuer_url": "https://oidc.eks.us-west-2.amazonaws.com/id/6FA42E7BFDE8549CB...",
  "jwks": { "type": "discovery" }
}

Federation-Regel: Matche den Kubernetes-sub-Claim und die Anthropic-Audience https://api.anthropic.com. (Projiziere ein dediziertes Service-Account-Token mit dieser Audience; verwende nicht das IRSA-Standard-Token mit sts.amazonaws.com wieder.)

{
  "name": "prod-inference",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "system:serviceaccount:inference:inference-worker",
    "audience": "https://api.anthropic.com"
  },
  "target": { "type": "service_account", "service_account_id": "svac_..." },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Sei so spezifisch, wie es der Workload erlaubt. Lockere subject_prefix nur dann auf system:serviceaccount:inference:* (das abschließende * macht daraus einen Präfix-Match), wenn jeder Service-Account im Namespace demselben Anthropic-Service-Account zugeordnet werden soll.



Token abrufen und verwenden

Innerhalb des Pods befindet sich das projizierte Token unter /var/run/secrets/anthropic.com/token (in der Pod-Spec als ANTHROPIC_IDENTITY_TOKEN_FILE bereitgestellt). Übergib diese Datei an die Federation-Credentials des SDK, und das SDK übernimmt den Austausch und den Refresh.

import os

import anthropic
from anthropic import IdentityTokenFile, WorkloadIdentityCredentials

client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile(
            os.environ["ANTHROPIC_IDENTITY_TOKEN_FILE"]
        ),
        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 EKS"}],
)
print(message.content[0].text)



Setup überprüfen

Tausche von innerhalb des Pods das projizierte Token direkt aus und prüfe die Antwort:

JWT=$(cat "$ANTHROPIC_IDENTITY_TOKEN_FILE")

curl -sS https://api.anthropic.com/v1/oauth/token \
  -H "content-type: application/json" \
  -d "{
    \"grant_type\": \"urn:ietf:params:oauth:grant-type:jwt-bearer\",
    \"assertion\": \"$JWT\",
    \"federation_rule_id\": \"$ANTHROPIC_FEDERATION_RULE_ID\",
    \"organization_id\": \"$ANTHROPIC_ORGANIZATION_ID\",
    \"service_account_id\": \"$ANTHROPIC_SERVICE_ACCOUNT_ID\",
    \"workspace_id\": \"$ANTHROPIC_WORKSPACE_ID\"
  }" | jq

Ein erfolgreicher Austausch gibt ein access_token zurück, das mit sk-ant-oat01- beginnt, sowie einen expires_in-Wert in Sekunden. Bei 400 invalid_grant siehe Fehlerbehebung bei einem fehlgeschlagenen Austausch; die häufigste Ursache auf EKS-Seite ist, dass das aud des projizierten Tokens nicht mit der Regel übereinstimmt (projiziere ein Token mit audience: https://api.anthropic.com, nicht das IRSA-Standard-Token mit sts.amazonaws.com).



Deine Regel eingrenzen

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

• Die vollständige Rollen-ARN festlegen: Verwende subject_prefix: "arn:aws:iam::<account>:role/<role-name>" ohne abschließendes *, damit andere Rollen im Konto nicht matchen.
• Die Konto-ID festlegen: Matche das Feld aws_account des https://sts.amazonaws.com/-Claims des Tokens mit der claims-Map oder einer CEL-condition als zusätzliche Absicherung (Defense-in-Depth) gegen ein falsch konfiguriertes Präfix.
• Namespace und Service-Account auf EKS festlegen: Verwende den exakten Wert system:serviceaccount:<namespace>:<name> ohne * nach dem Präfix system:serviceaccount:.
• Eine separate Regel pro Umgebung verwenden: Erstelle getrennte Regeln für Produktions-, Staging- und Entwicklungs-Workloads, anstatt ein Präfix zu erweitern, um alle abzudecken.



Nächste Schritte

• Sieh dir die WIF-Referenz für die vollständige Referenz zu Credential-Priorität, Profilkonfiguration und Regel-Matching an.
• Für selbstverwaltete Kubernetes-Cluster, die nicht auf EKS laufen, siehe WIF mit Kubernetes verwenden.