Usar WIF com AWS

Workloads da AWS podem se autenticar na API do Claude 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 da AWS: Lambda, EC2, ECS e EKS. Workloads do 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 (contas de serviço, emissores de federação e regras de federação), consulte Workload Identity Federation.

Pré-requisitos

• Familiaridade com os conceitos de WIF: contas de serviço, emissores de federação e regras de federação.
• Um workload da AWS (pod do EKS, tarefa do ECS, função Lambda ou instância EC2) com uma função IAM anexada.
• A CLI aws ou um SDK da AWS disponível no workload.
• Permissão para criar contas de serviço, emissores de federação e regras de federação no Claude Console para sua organização da Anthropic.

Usar 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 da AWS do ambiente do workload, a mesma integração cobre Lambda, EC2, ECS e EKS.

Configurar a AWS

Configurar a Anthropic

Siga o passo a passo de configuração para registrar um emissor de federação, criar uma conta de serviço da Anthropic e criar uma regra de federação no Claude Console. Use estes valores específicos do STS.

Emissor de federação: Registre a URL do emissor STS específica da conta que você copiou na etapa anterior. Ela expõe um endpoint JWKS público, então use o modo de descoberta.

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

Regra de federação: Faça a correspondência com o audience que você passa para GetWebIdentityToken e com o ARN da função IAM do chamador na claim sub. O valor de sub é o ARN da função IAM 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ê passou; você pode fazer correspondência com esses valores usando o mapa claims da regra ou uma condition 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 função e só amplie o subject_prefix (por exemplo, para arn:aws:iam::123456789012:role/*) se várias funções IAM devem ser mapeadas para a mesma conta de serviço da Anthropic.

Obter e usar 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, então 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from AWS"}],
)
print(message.content[0].text)

Verificar 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 emissor STS específica da conta deve corresponder exatamente ao issuer_url registrado).

Usar tokens de conta de serviço projetados do EKS

Se seu workload é executado em um pod do EKS, você pode pular a chamada ao STS e ler um token de conta de serviço projetado pelo Kubernetes diretamente do disco. O Kubernetes projeta nativamente um token compatível com OIDC no pod, e o SDK pode lê-lo de um caminho de arquivo, então nenhum callable de provedor de token é necessário. Esse 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 do Kubernetes.

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

Configurar seu cluster EKS

Configurar a Anthropic

Siga o passo a passo de configuração para registrar um emissor de federação, criar uma conta de serviço da Anthropic e criar uma regra de federação no Claude Console. Use estes valores específicos do EKS.

Emissor de federação: Emissores do EKS expõem um endpoint JWKS público, então use o modo de descoberta. A URL do emissor deve corresponder exatamente à claim iss do token. Registre um emissor por cluster.

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

Regra de federação: Faça a correspondência com a claim sub do Kubernetes e com o audience da Anthropic https://api.anthropic.com. (Projete um token de conta de serviço dedicado com esse audience; não reutilize o token padrão do 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
}

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

Obter e usar 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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from EKS"}],
)
print(message.content[0].text)

Verificar 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 do IRSA sts.amazonaws.com).

Definir o escopo da sua regra

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

• Fixe o ARN completo da função: Use subject_prefix: "arn:aws:iam::<account>:role/<role-name>" sem * no final para que outras funções na conta não correspondam.
• Fixe o ID da conta: Faça a correspondência com o campo aws_account da claim https://sts.amazonaws.com/ do token por meio do mapa claims ou de uma condition CEL como uma verificação de defesa em profundidade contra um prefixo mal configurado.
• Fixe o namespace e a conta de serviço 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 Usar WIF com Kubernetes.