AdministraçãoProvedores de identidade

Usar WIF com AWS

Autentique cargas de trabalho da AWS no Lambda, EC2, ECS ou EKS na Claude API com Workload Identity Federation e tokens de identidade emitidos pelo STS.

Cargas de trabalho da 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 a carga de trabalho tenha credenciais da AWS: Lambda, EC2, ECS e EKS. Cargas de trabalho 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.
Uma carga de trabalho da AWS (pod do EKS, tarefa do ECS, função Lambda ou instância EC2) com uma função do IAM anexada.
A CLI aws ou um SDK da AWS disponível na carga de trabalho.
Permissão para criar contas de serviço, emissores de federação e regras de federação no Claude Console para sua organização 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 da carga de trabalho, a mesma integração cobre Lambda, EC2, ECS e EKS.

Configurar a AWS

1
Habilitar a federação de identidade web de saída para a conta
Esta é uma flag no nível da conta, desativada por padrão. No console da AWS, abra IAM, escolha Account settings e habilite Outbound web identity federation. Para habilitá-la programaticamente:
python3 -c "import boto3; boto3.client('iam').enable_outbound_web_identity_federation()"
Se isso não estiver habilitado, as chamadas a GetWebIdentityToken falham com OutboundWebIdentityFederationDisabledException.

Conceder à função do IAM da carga de trabalho permissão para chamar a API

Anexe esta política à função do IAM com a qual sua função Lambda, instância EC2 ou tarefa do ECS é executada:

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

3
Encontrar a URL do emissor STS da sua conta
Após habilitar a federação de saída, a página IAM > Account settings mostra um campo Get Token Issuer URL com um valor no formato https://<uuid>.tokens.sts.global.api.aws. Essa URL é exclusiva da sua conta da AWS; copie-a para a próxima etapa. Para recuperá-la programaticamente:
python3 -c "import boto3; print(boto3.client('iam').get_outbound_web_identity_federation_info())"

Configurar 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 emissor, na criação de uma conta de serviço e na criação de uma regra de federação.

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

Emissor de federação: Registre a URL do emissor 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" }
}

Regra de federação: Faça a correspondência com a audiência que você passa para GetWebIdentityToken e com o ARN da função do IAM da função chamadora na claim sub. O valor de sub é o ARN da função do IAM da carga de trabalho 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 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 a carga de trabalho 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 do 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 audiência e, em seguida, passe o resultado para as credenciais de federação do SDK. O provedor de token é um callable, portanto o SDK invoca o STS novamente 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"))

Verificar a configuração

De dentro da carga de trabalho, troque diretamente um token emitido pelo STS e inspecione a resposta:

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

Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Se a troca falhar com a resposta opaca 401 authentication_error (mensagem Authentication failed), verifique a página de histórico de autenticação para ver o motivo da negação e 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 por conta deve corresponder exatamente à issuer_url registrada).

Usar tokens de conta de serviço projetados do EKS

Se sua carga de trabalho é executada 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 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 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 kubectl ao cluster.

Configurar seu cluster EKS

1
Encontrar a URL do emissor OIDC do seu cluster
Cada cluster EKS tem um emissor OIDC exclusivo. Recupere-o com a AWS CLI:
CLI
aws eks describe-cluster \ --name <cluster-name> \ --query "cluster.identity.oidc.issuer" \ --output text
A saída se parece com https://oidc.eks.us-west-2.amazonaws.com/id/6FA42E7BFDE8549CB.... Você registrará essa URL como um emissor de federação na próxima seção.

Criar a conta de serviço e projetar um token com audiência da Anthropic

O webhook de identidade de pod do EKS detecta a anotação eks.amazonaws.com/role-arn e projeta automaticamente um token com aud: sts.amazonaws.com, expondo seu caminho como AWS_WEB_IDENTITY_TOKEN_FILE. Esse token é para assumir funções da AWS. Para a troca com a Anthropic, projete um segundo token com audience: https://api.anthropic.com e monte-o em um caminho dedicado.

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
Observar o formato das claims do token
O token projetado é um JSON Web Token (JWT) assinado pelo emissor OIDC do seu cluster. Sua claim sub segue a convenção do 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 }
A projeção serviceAccountToken define aud como https://api.anthropic.com. O token separado injetado pelo IRSA em AWS_WEB_IDENTITY_TOKEN_FILE carrega aud: sts.amazonaws.com e é para chamadas de API da AWS, não para esta troca.

Configurar a Anthropic

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

Emissor de federação: Os emissores do EKS expõem um endpoint JWKS público, portanto 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": { "type": "discovery" }
}

Regra de federação: Faça a correspondência com a claim sub do Kubernetes e com a audiência da Anthropic https://api.anthropic.com. (Projete um token de conta de serviço dedicado com essa audiência; 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 a carga de trabalho permitir. Afrouxe o subject_prefix para system:serviceaccount:inference:* (o * final o torna uma correspondência de prefixo) somente 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-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"))

Verificar a configuração

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

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

Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Se a troca falhar com a resposta opaca 401 authentication_error (mensagem Authentication failed), verifique a página de histórico de autenticação para ver o motivo da negação e 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).

Definir o escopo da sua regra

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

Fixe o ARN completo da função: Use subject_prefix: "arn:aws:iam::<account>:role/<role-name>" sem * 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 usando o mapa claims ou 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 cargas de trabalho de produção, staging e desenvolvimento em vez de ampliar um único prefixo para cobrir todas elas.

Próximos passos

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

Pré-requisitos

Usar tokens de identidade web do STS (recomendado)

Configurar a AWS

Habilitar a federação de identidade web de saída para a conta

Conceder à função do IAM da carga de trabalho permissão para chamar a API

Encontrar a URL do emissor STS da sua conta

Configurar a Anthropic

Obter e usar o token

Verificar a configuração

Usar tokens de conta de serviço projetados do EKS

Configurar seu cluster EKS

Encontrar a URL do emissor OIDC do seu cluster

Criar a conta de serviço e projetar um token com audiência da Anthropic

Observar o formato das claims do token

Configurar a Anthropic

Obter e usar o token

Verificar a configuração

Definir o escopo da sua regra

Próximos passos

Pré-requisitos

Usar tokens de identidade web do STS (recomendado)

Configurar a AWS

Configurar a Anthropic

Obter e usar o token

Verificar a configuração

Usar tokens de conta de serviço projetados do EKS

Configurar seu cluster EKS

Configurar a Anthropic

Obter e usar o token

Verificar a configuração

Definir o escopo da sua regra

Próximos passos