Use WIF com AWS

Workloads AWS podem se autenticar na Claude API sem chaves de API estáticas trocando um token de identidade OIDC assinado pela AWS. O caminho recomendado chama a API GetWebIdentityToken do AWS STS, que funciona em qualquer lugar onde o workload tenha credenciais AWS: Lambda, EC2, ECS e EKS. Workloads EKS podem, alternativamente, usar o caminho de token projetado do Kubernetes, que tem menos etapas de configuração, mas só funciona dentro de um pod.

Este guia mostra ambos os caminhos. Para os conceitos subjacentes (service accounts, federation issuers e federation rules), consulte Workload Identity Federation.



Pré-requisitos

• Familiaridade com os conceitos de WIF: service accounts, federation issuers e federation rules.
• Um workload AWS (pod EKS, task ECS, função Lambda ou instância EC2) com uma IAM role anexada.
• A CLI aws ou um SDK da AWS disponível no workload.
• Permissão para criar service accounts, federation issuers e federation rules no Claude Console para sua organização Anthropic.



Use tokens de identidade web do STS (recomendado)

A API GetWebIdentityToken do AWS STS retorna um token OIDC assinado pela AWS que atesta a identidade IAM do chamador. Como ela usa as credenciais AWS do ambiente do workload, a mesma integração cobre Lambda, EC2, ECS e EKS.



Configure a AWS



Configure a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco AWS. O assistente orienta você no registro do issuer, na criação de uma service account e na criação de uma federation rule.

O assistente cria esses recursos para você. Use os seguintes valores, seja inserindo-os no assistente ou enviando-os para a Admin API:

Federation issuer: Registre a URL do issuer do STS por conta que você copiou na etapa anterior. Ela expõe um endpoint JWKS público, portanto use o modo de descoberta.

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

Federation rule: Faça a correspondência da audience que você passa para GetWebIdentityToken e do ARN da IAM role do chamador na claim sub. O valor de sub é o ARN da IAM role do workload que chamou a API, no formato arn:aws:iam::<account>:role/<role-name>. O token também carrega uma claim https://sts.amazonaws.com/ com aws_account, org_id, principal_id e quaisquer request_tags que você tenha passado; você pode fazer correspondência com esses valores usando o mapa claims da regra ou uma condition em CEL para um controle mais refinado.

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

Seja tão específico quanto o workload permitir. Faça a correspondência com o ARN exato da role e só amplie o subject_prefix (por exemplo, para arn:aws:iam::123456789012:role/*) se várias IAM roles devem ser mapeadas para a mesma service account da Anthropic.



Adquira e use o token

Chame GetWebIdentityToken com https://api.anthropic.com como audience e, em seguida, passe o resultado para as credenciais de federação do SDK. O provedor de token é um callable, portanto o SDK reinvoca o STS a cada atualização.

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



Verifique a configuração

De dentro do workload, troque um token emitido pelo STS diretamente e inspecione a resposta:

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

Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Em caso de 400 invalid_grant, consulte Solucionar problemas de uma troca com falha; a causa mais comum do lado da AWS é uma incompatibilidade de iss (a URL do issuer do STS por conta deve corresponder exatamente ao issuer_url registrado).



Use tokens de service account projetados do EKS

Se o seu workload é executado em um pod EKS, você pode pular a chamada ao STS e ler um token de service account projetado pelo Kubernetes diretamente do disco. O Kubernetes projeta nativamente um token compatível com OIDC no pod, e o SDK pode lê-lo a partir de um caminho de arquivo, portanto nenhum callable de provedor de token é necessário. Este caminho tem duas etapas de configuração da AWS a menos do que o caminho do STS, mas só funciona dentro de um pod; o mecanismo subjacente é o mesmo da integração genérica com Kubernetes.

Este caminho requer adicionalmente um cluster EKS com um provedor OIDC do IAM habilitado e acesso via kubectl ao cluster.



Configure seu cluster EKS



Configure a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco AWS. O assistente orienta você no registro do issuer, na criação de uma service account e na criação de uma federation rule.

O assistente cria esses recursos para você. Use os seguintes valores, seja inserindo-os no assistente ou enviando-os para a Admin API:

Federation issuer: Issuers do EKS expõem um endpoint JWKS público, portanto use o modo de descoberta. A URL do issuer deve corresponder exatamente à claim iss do token. Registre um issuer por cluster.

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

Federation rule: Faça a correspondência da claim sub do Kubernetes e da audience da Anthropic https://api.anthropic.com. (Projete um token de service account dedicado com essa audience; não reutilize o token padrão sts.amazonaws.com do IRSA.)

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

Seja tão específico quanto o workload permitir. Afrouxe o subject_prefix para system:serviceaccount:inference:* (o * no final o torna uma correspondência de prefixo) somente se todas as service accounts no namespace devem ser mapeadas para a mesma service account da Anthropic.



Adquira e use o token

Dentro do pod, o token projetado está em /var/run/secrets/anthropic.com/token (exposto como ANTHROPIC_IDENTITY_TOKEN_FILE na especificação do Pod). Passe esse arquivo para as credenciais de federação do SDK e o SDK cuida da troca e da atualização.

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



Verifique a configuração

De dentro do pod, troque o token projetado diretamente e inspecione a resposta:

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

Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Em caso de 400 invalid_grant, consulte Solucionar problemas de uma troca com falha; a causa mais comum do lado do EKS é o aud do token projetado não corresponder à regra (projete um token com audience: https://api.anthropic.com, não o padrão sts.amazonaws.com do IRSA).



Defina o escopo da sua regra

Restrinja o bloco match da regra ao escopo mais estreito que se adeque ao seu caso de uso:

• Fixe o ARN completo da role: Use subject_prefix: "arn:aws:iam::<account>:role/<role-name>" sem * no final para que outras roles na conta não correspondam.
• Fixe o ID da conta: Faça a correspondência do campo aws_account da claim https://sts.amazonaws.com/ do token com o mapa claims ou uma condition em CEL como uma verificação de defesa em profundidade contra um prefixo mal configurado.
• Fixe o namespace e a service account no EKS: Use o valor exato system:serviceaccount:<namespace>:<name> sem * após o prefixo system:serviceaccount:.
• Use uma regra separada por ambiente: Crie regras distintas para workloads de produção, staging e desenvolvimento em vez de ampliar um único prefixo para cobrir todos eles.



Próximos passos

• Revise a referência de WIF para a referência completa de precedência de credenciais, configuração de perfil e correspondência de regras.
• Para clusters Kubernetes autogerenciados que não estão no EKS, consulte Use WIF com Kubernetes.