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ätstoken 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-Pfad mit projizierten Token verwenden, der weniger Konfigurationsschritte hat, aber nur innerhalb eines Pods funktioniert.

Dieser Leitfaden zeigt beide Wege. Für die zugrunde liegenden Konzepte (Service Accounts, Federation Issuers und Federation Rules) siehe Workload Identity Federation.



Voraussetzungen

• Vertrautheit mit den WIF-Konzepten: Service Accounts, Federation Issuers und Federation Rules.
• 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 Issuers und Federation Rules 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 Kachel AWS. Der Assistent führt dich durch die Registrierung des Issuers, die Erstellung eines Service Accounts und die Erstellung einer Federation Rule.

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 Rule: Gleiche die Audience ab, die du an GetWebIdentityToken übergibst, sowie den IAM-Rollen-ARN der aufrufenden Rolle im sub-Claim. Der sub-Wert ist der 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 Kontrolle abgleichen.

{
  "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 zulässt. Gleiche den exakten Rollen-ARN ab 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 beziehen und verwenden

Rufe GetWebIdentityToken mit https://api.anthropic.com als Audience auf und übergib dann das Ergebnis an die Federation-Anmeldeinformationen des SDK. Der Token-Provider ist ein Callable, sodass das SDK STS bei jeder Aktualisierung 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from AWS"}],
)
print(next(block.text for block in message.content if block.type == "text"))



Einrichtung überprüfen

Tausche aus dem Workload heraus 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-projizierte 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 Kachel AWS. Der Assistent führt dich durch die Registrierung des Issuers, die Erstellung eines Service Accounts und die Erstellung einer Federation Rule.

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 Rule: Gleiche den Kubernetes-sub-Claim und die Anthropic-Audience https://api.anthropic.com ab. (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 zulässt. Lockere subject_prefix nur dann auf system:serviceaccount:inference:* (das abschließende * macht daraus einen Präfix-Abgleich), wenn jeder Service Account im Namespace demselben Anthropic Service Account zugeordnet werden soll.



Token beziehen und verwenden

Innerhalb des Pods befindet sich das projizierte Token unter /var/run/secrets/anthropic.com/token (als ANTHROPIC_IDENTITY_TOKEN_FILE in der Pod-Spezifikation verfügbar gemacht). Übergib diese Datei an die Federation-Anmeldeinformationen des SDK, und das SDK übernimmt den Austausch und die Aktualisierung.

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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from EKS"}],
)
print(next(block.text for block in message.content if block.type == "text"))



Einrichtung überprüfen

Tausche aus dem Pod heraus 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 mit dem IRSA-Standard sts.amazonaws.com).



Deine Regel eingrenzen

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

• Den vollständigen Rollen-ARN festlegen: Verwende subject_prefix: "arn:aws:iam::<account>:role/<role-name>" ohne abschließendes *, damit andere Rollen im Konto nicht übereinstimmen.
• Die Konto-ID festlegen: Gleiche das Feld aws_account des https://sts.amazonaws.com/-Claims des Tokens mit der claims-Map oder einer CEL-condition ab, als Defense-in-Depth-Prüfung 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 unterschiedliche 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 Anmeldeinformations-Priorität, Profilkonfiguration und Regelabgleich an.
• Für selbstverwaltete Kubernetes-Cluster, die nicht auf EKS laufen, siehe WIF mit Kubernetes verwenden.