Claude Platform Docs
AmministrazioneProvider di identità

Usare WIF con AWS

Autentica i workload AWS su Lambda, EC2, ECS o EKS alla Claude API con Workload Identity Federation e token di identità emessi da STS.

I workload AWS possono autenticarsi alla Claude API senza chiavi API statiche scambiando un token di identità OIDC firmato da AWS. Il percorso consigliato chiama l'API AWS STS GetWebIdentityToken, che funziona ovunque il workload disponga di credenziali AWS: Lambda, EC2, ECS ed EKS. I workload EKS possono in alternativa usare il percorso con token proiettato di Kubernetes, che richiede meno passaggi di configurazione ma funziona solo all'interno di un pod.

Questa guida mostra entrambi i percorsi. Per i concetti sottostanti (service account, federation issuer e federation rule), consulta Workload Identity Federation.

Prerequisiti

  • Familiarità con i concetti di WIF: service account, federation issuer e federation rule.
  • Un workload AWS (pod EKS, task ECS, funzione Lambda o istanza EC2) con un ruolo IAM associato.
  • La CLI aws o un AWS SDK disponibile nel workload.
  • Permesso di creare service account, federation issuer e federation rule nella Claude Console per la tua organizzazione Anthropic.

L'API AWS STS GetWebIdentityToken restituisce un token OIDC firmato da AWS che attesta l'identità IAM del chiamante. Poiché usa le credenziali AWS ambientali del workload, la stessa integrazione copre Lambda, EC2, ECS ed EKS.

Configurare AWS

  1. Abilita la outbound web identity federation per l'account

    Si tratta di un flag a livello di account, disattivato per impostazione predefinita. Nella console AWS, apri IAM, scegli Account settings e abilita Outbound web identity federation. Per abilitarlo in modo programmatico:

    python3 -c "import boto3; boto3.client('iam').enable_outbound_web_identity_federation()"

    Se non è abilitato, le chiamate a GetWebIdentityToken falliscono con OutboundWebIdentityFederationDisabledException.

  2. Concedi al ruolo IAM del workload il permesso di chiamare l'API

    Associa questa policy al ruolo IAM con cui viene eseguita la tua funzione Lambda, istanza EC2 o task ECS:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["sts:GetWebIdentityToken"],
      "Resource": "*"
    }
  ]
}

  3. Trova l'URL dell'issuer STS del tuo account

    Dopo aver abilitato la outbound federation, la pagina IAM > Account settings mostra un campo Get Token Issuer URL con un valore nella forma https://<uuid>.tokens.sts.global.api.aws. Questo URL è univoco per il tuo account AWS; copialo per il passaggio successivo. Per recuperarlo in modo programmatico:

    python3 -c "import boto3; print(boto3.client('iam').get_outbound_web_identity_federation_info())"

Configurare Anthropic

Nella Claude Console, apri Settings → Workload identity, fai clic su Connect workload e seleziona il riquadro AWS. La procedura guidata ti accompagna nella registrazione dell'issuer, nella creazione di un service account e nella creazione di una federation rule.

La procedura guidata crea queste risorse per te. Usa i seguenti valori sia che tu li inserisca nella procedura guidata sia che li invii all'Admin API:

Federation issuer: Registra l'URL dell'issuer STS per account che hai copiato nel passaggio precedente. Espone un endpoint JWKS pubblico, quindi usa la modalità discovery.

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

Federation rule: Fai corrispondere l'audience che passi a GetWebIdentityToken e l'ARN del ruolo IAM del ruolo chiamante nel claim sub. Il valore di sub è l'ARN del ruolo IAM del workload che ha chiamato l'API, nella forma arn:aws:iam::<account>:role/<role-name>. Il token contiene anche un claim https://sts.amazonaws.com/ con aws_account, org_id, principal_id ed eventuali request_tags che hai passato; puoi effettuare il match su questi con la mappa claims della regola o con una condition CEL per un controllo più granulare.

{
  "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
}

Sii specifico quanto il workload consente. Fai corrispondere l'ARN esatto del ruolo e amplia subject_prefix (ad esempio, a arn:aws:iam::123456789012:role/*) solo se più ruoli IAM devono essere mappati allo stesso service account Anthropic.

Acquisire e usare il token

Chiama GetWebIdentityToken con https://api.anthropic.com come audience, quindi passa il risultato alle credenziali di federazione dell'SDK. Il token provider è un callable, quindi l'SDK richiama STS a ogni refresh.

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

Verificare la configurazione

Dall'interno del workload, scambia direttamente un token emesso da STS e ispeziona la risposta:

cURL
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

Uno scambio riuscito restituisce un access_token che inizia con sk-ant-oat01- e un valore expires_in in secondi. Se lo scambio fallisce con la risposta opaca 401 authentication_error (messaggio Authentication failed), controlla la pagina della cronologia di autenticazione per il motivo del rifiuto e consulta Risolvere i problemi di uno scambio fallito; la causa più comune lato AWS è una mancata corrispondenza di iss (l'URL dell'issuer STS per account deve corrispondere esattamente all'issuer_url registrato).

Usare i token di service account proiettati di EKS

Se il tuo workload viene eseguito in un pod EKS, puoi saltare la chiamata STS e leggere un token di service account proiettato da Kubernetes direttamente dal disco. Kubernetes proietta nativamente nel pod un token compatibile con OIDC e l'SDK può leggerlo da un percorso di file, quindi non è richiesto alcun callable token provider. Questo percorso ha due passaggi di configurazione AWS in meno rispetto al percorso STS ma funziona solo all'interno di un pod; il meccanismo sottostante è lo stesso dell'integrazione Kubernetes generica.

Questo percorso richiede inoltre un cluster EKS con un provider OIDC IAM abilitato e accesso kubectl al cluster.

Configurare il cluster EKS

  1. Trova l'URL dell'issuer OIDC del tuo cluster

    Ogni cluster EKS ha un issuer OIDC univoco. Recuperalo con la AWS CLI:

    CLI
    aws eks describe-cluster \
  --name <cluster-name> \
  --query "cluster.identity.oidc.issuer" \
  --output text

    L'output ha un aspetto simile a https://oidc.eks.us-west-2.amazonaws.com/id/6FA42E7BFDE8549CB.... Registrerai questo URL come federation issuer nella sezione successiva.

  2. Crea il service account e proietta un token con audience Anthropic

    Il webhook di pod identity di EKS rileva l'annotazione eks.amazonaws.com/role-arn e proietta automaticamente un token con aud: sts.amazonaws.com, esponendone il percorso come AWS_WEB_IDENTITY_TOKEN_FILE. Quel token serve per l'assunzione di ruoli AWS. Per lo scambio Anthropic, proietta un secondo token con audience: https://api.anthropic.com e montalo in un percorso dedicato.

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: inference-worker
  namespace: inference
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/inference-worker
    apiVersion: v1
kind: Pod
metadata:
  name: inference-worker
  namespace: inference
spec:
  serviceAccountName: inference-worker
  volumes:
    - name: anthropic-token
      projected:
        sources:
          - serviceAccountToken:
              audience: https://api.anthropic.com
              expirationSeconds: 3600
              path: token
  containers:
    - name: app
      image: your-registry/inference-worker:latest
      env:
        - name: ANTHROPIC_IDENTITY_TOKEN_FILE
          value: /var/run/secrets/anthropic.com/token
        - name: ANTHROPIC_FEDERATION_RULE_ID
          value: fdrl_...
        - name: ANTHROPIC_ORGANIZATION_ID
          value: 00000000-0000-0000-0000-000000000000
        - name: ANTHROPIC_SERVICE_ACCOUNT_ID
          value: svac_...
        - name: ANTHROPIC_WORKSPACE_ID  # required when the rule covers multiple workspaces
          value: wrkspc_...
      volumeMounts:
        - name: anthropic-token
          mountPath: /var/run/secrets/anthropic.com
          readOnly: true

  3. Prendi nota della struttura dei claim del token

    Il token proiettato è un JSON Web Token (JWT) firmato dall'issuer OIDC del tuo cluster. Il suo claim sub segue la convenzione Kubernetes system:serviceaccount:<namespace>:<service-account-name>:

    {
  "iss": "https://oidc.eks.us-west-2.amazonaws.com/id/6FA42E7BFDE8549CB...",
  "sub": "system:serviceaccount:inference:inference-worker",
  "aud": ["https://api.anthropic.com"],
  "kubernetes.io": {
    "namespace": "inference",
    "serviceaccount": { "name": "inference-worker", "uid": "..." }
  },
  "exp": 1775527120,
  "iat": 1775523520
}

    La proiezione serviceAccountToken imposta aud a https://api.anthropic.com. Il token separato iniettato da IRSA in AWS_WEB_IDENTITY_TOKEN_FILE contiene aud: sts.amazonaws.com e serve per le chiamate alle API AWS, non per questo scambio.

Configurare Anthropic

Nella Claude Console, apri Settings → Workload identity, fai clic su Connect workload e seleziona il riquadro AWS. La procedura guidata ti accompagna nella registrazione dell'issuer, nella creazione di un service account e nella creazione di una federation rule.

La procedura guidata crea queste risorse per te. Usa i seguenti valori sia che tu li inserisca nella procedura guidata sia che li invii all'Admin API:

Federation issuer: Gli issuer EKS espongono un endpoint JWKS pubblico, quindi usa la modalità discovery. L'URL dell'issuer deve corrispondere esattamente al claim iss del token. Registra un issuer per cluster.

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

Federation rule: Fai corrispondere il claim sub di Kubernetes e l'audience Anthropic https://api.anthropic.com. (Proietta un token di service account dedicato con quell'audience; non riutilizzare il token predefinito IRSA sts.amazonaws.com.)

{
  "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
}

Sii specifico quanto il workload consente. Allenta subject_prefix a system:serviceaccount:inference:* (il * finale lo rende un match per prefisso) solo se ogni service account nel namespace deve essere mappato allo stesso service account Anthropic.

Acquisire e usare il token

All'interno del pod, il token proiettato si trova in /var/run/secrets/anthropic.com/token (esposto come ANTHROPIC_IDENTITY_TOKEN_FILE nella specifica del Pod). Passa quel file alle credenziali di federazione dell'SDK e l'SDK gestisce lo scambio e il 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-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"))

Verificare la configurazione

Dall'interno del pod, scambia direttamente il token proiettato e ispeziona la risposta:

cURL
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

Uno scambio riuscito restituisce un access_token che inizia con sk-ant-oat01- e un valore expires_in in secondi. Se lo scambio fallisce con la risposta opaca 401 authentication_error (messaggio Authentication failed), controlla la pagina della cronologia di autenticazione per il motivo del rifiuto e consulta Risolvere i problemi di uno scambio fallito; la causa più comune lato EKS è che l'aud del token proiettato non corrisponde alla regola (proietta un token con audience: https://api.anthropic.com, non il valore predefinito IRSA sts.amazonaws.com).

Definire l'ambito della regola

Vincola il blocco match della regola all'ambito più ristretto adatto al tuo caso d'uso:

  • Fissa l'ARN completo del ruolo: Usa subject_prefix: "arn:aws:iam::<account>:role/<role-name>" senza * finale in modo che gli altri ruoli nell'account non corrispondano.
  • Fissa l'ID dell'account: Fai corrispondere il campo aws_account del claim https://sts.amazonaws.com/ del token con la mappa claims o una condition CEL come controllo di difesa in profondità contro un prefisso configurato in modo errato.
  • Fissa namespace e service account su EKS: Usa il valore esatto system:serviceaccount:<namespace>:<name> senza * dopo il prefisso system:serviceaccount:.
  • Usa una regola separata per ambiente: Crea regole distinte per i workload di produzione, staging e sviluppo invece di ampliare un unico prefisso per coprirli tutti.

Passaggi successivi

  • Consulta il riferimento WIF per il riferimento completo sulla precedenza delle credenziali, la configurazione dei profili e il matching delle regole.
  • Per i cluster Kubernetes autogestiti che non sono su EKS, consulta Usare WIF con Kubernetes.

Was this page helpful?