Использование WIF с AWS

Рабочие нагрузки AWS могут аутентифицироваться в Claude API без статических ключей API, обменивая подписанный AWS токен идентификации OIDC. Рекомендуемый способ — вызов API AWS STS GetWebIdentityToken, который работает везде, где у рабочей нагрузки есть учётные данные AWS: Lambda, EC2, ECS и EKS. Рабочие нагрузки EKS могут альтернативно использовать способ с проецируемым токеном Kubernetes, который требует меньше шагов настройки, но работает только внутри пода.

В этом руководстве показаны оба способа. Для понимания базовых концепций (сервисные аккаунты, эмитенты федерации и правила федерации) см. Workload Identity Federation.

Предварительные требования

• Знакомство с концепциями WIF: сервисные аккаунты, эмитенты федерации и правила федерации.
• Рабочая нагрузка AWS (под EKS, задача ECS, функция Lambda или инстанс EC2) с прикреплённой ролью IAM.
• CLI aws или AWS SDK, доступные в рабочей нагрузке.
• Разрешение на создание сервисных аккаунтов, эмитентов федерации и правил федерации в Claude Console для вашей организации Anthropic.

Использование веб-токенов идентификации STS (рекомендуется)

API AWS STS GetWebIdentityToken возвращает токен OIDC, подписанный AWS, который подтверждает IAM-идентичность вызывающей стороны. Поскольку он использует окружающие учётные данные AWS рабочей нагрузки, одна и та же интеграция охватывает Lambda, EC2, ECS и EKS.

Настройка AWS

Настройка Anthropic

Следуйте пошаговому руководству по настройке, чтобы зарегистрировать эмитент федерации, создать сервисный аккаунт Anthropic и создать правило федерации в Claude Console. Используйте следующие значения, специфичные для STS.

Эмитент федерации: Зарегистрируйте URL эмитента STS для конкретного аккаунта, который вы скопировали на предыдущем шаге. Он предоставляет публичную конечную точку JWKS, поэтому используйте режим обнаружения (discovery mode).

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

Правило федерации: Сопоставьте аудиторию (audience), которую вы передаёте в GetWebIdentityToken, и ARN роли IAM вызывающей стороны в утверждении sub. Значение sub — это ARN роли IAM рабочей нагрузки, вызвавшей API, в формате arn:aws:iam::<account>:role/<role-name>. Токен также содержит утверждение https://sts.amazonaws.com/ с полями aws_account, org_id, principal_id и любыми переданными вами request_tags; вы можете сопоставлять их с помощью карты claims правила или условия CEL condition для более точного контроля.

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

Будьте настолько конкретны, насколько позволяет рабочая нагрузка. Сопоставляйте точный ARN роли и расширяйте subject_prefix (например, до arn:aws:iam::123456789012:role/*) только в том случае, если несколько ролей IAM должны соответствовать одному и тому же сервисному аккаунту Anthropic.

Получение и использование токена

Вызовите GetWebIdentityToken с https://api.anthropic.com в качестве аудитории, затем передайте результат в учётные данные федерации SDK. Провайдер токена — это вызываемый объект, поэтому SDK повторно вызывает STS при каждом обновлении.

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)

Проверка настройки

Изнутри рабочей нагрузки обменяйте токен, выданный STS, напрямую и изучите ответ:

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

Успешный обмен возвращает access_token, начинающийся с sk-ant-oat01-, и значение expires_in в секундах. При ошибке 400 invalid_grant см. Устранение неполадок при неудачном обмене; наиболее частая причина со стороны AWS — несоответствие iss (URL эмитента STS для конкретного аккаунта должен точно совпадать с зарегистрированным issuer_url).

Использование проецируемых токенов сервисных аккаунтов EKS

Если ваша рабочая нагрузка выполняется в поде EKS, вы можете пропустить вызов STS и читать проецируемый Kubernetes токен сервисного аккаунта непосредственно с диска. Kubernetes нативно проецирует OIDC-совместимый токен в под, и SDK может читать его по пути к файлу, поэтому вызываемый провайдер токена не требуется. Этот способ требует на два шага настройки AWS меньше, чем способ через STS, но работает только внутри пода; базовый механизм такой же, как в общей интеграции с Kubernetes.

Этот способ дополнительно требует кластер EKS с включённым провайдером IAM OIDC и доступ kubectl к кластеру.

Настройка кластера EKS

Настройка Anthropic

Следуйте пошаговому руководству по настройке, чтобы зарегистрировать эмитент федерации, создать сервисный аккаунт Anthropic и создать правило федерации в Claude Console. Используйте следующие значения, специфичные для EKS.

Эмитент федерации: Эмитенты EKS предоставляют публичную конечную точку JWKS, поэтому используйте режим обнаружения. URL эмитента должен точно совпадать с утверждением iss токена. Регистрируйте по одному эмитенту на кластер.

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

Правило федерации: Сопоставьте утверждение Kubernetes sub и аудиторию Anthropic https://api.anthropic.com. (Спроецируйте выделенный токен сервисного аккаунта с этой аудиторией; не используйте повторно токен 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
}

Будьте настолько конкретны, насколько позволяет рабочая нагрузка. Ослабляйте subject_prefix до system:serviceaccount:inference:* (завершающий * делает его префиксным сопоставлением) только в том случае, если каждый сервисный аккаунт в пространстве имён должен соответствовать одному и тому же сервисному аккаунту Anthropic.

Получение и использование токена

Внутри пода проецируемый токен находится по пути /var/run/secrets/anthropic.com/token (предоставляется как ANTHROPIC_IDENTITY_TOKEN_FILE в спецификации Pod). Передайте этот файл в учётные данные федерации SDK, и SDK обработает обмен и обновление.

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)

Проверка настройки

Изнутри пода обменяйте проецируемый токен напрямую и изучите ответ:

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

Успешный обмен возвращает access_token, начинающийся с sk-ant-oat01-, и значение expires_in в секундах. При ошибке 400 invalid_grant см. Устранение неполадок при неудачном обмене; наиболее частая причина со стороны EKS — несоответствие aud проецируемого токена правилу (спроецируйте токен с audience: https://api.anthropic.com, а не с IRSA по умолчанию sts.amazonaws.com).

Ограничение области действия правила

Ограничьте блок match правила до наиболее узкой области, подходящей для вашего сценария использования:

• Закрепите полный ARN роли: Используйте subject_prefix: "arn:aws:iam::<account>:role/<role-name>" без завершающего *, чтобы другие роли в аккаунте не соответствовали.
• Закрепите идентификатор аккаунта: Сопоставьте поле aws_account утверждения токена https://sts.amazonaws.com/ через карту claims или условие CEL condition в качестве дополнительной защиты от неправильно настроенного префикса.
• Закрепите пространство имён и сервисный аккаунт в EKS: Используйте точное значение system:serviceaccount:<namespace>:<name> без * после префикса system:serviceaccount:.
• Используйте отдельное правило для каждой среды: Создавайте отдельные правила для рабочих нагрузок production, staging и development вместо расширения одного префикса для охвата их всех.

Дальнейшие шаги

• Ознакомьтесь со справочником по WIF для получения полной информации о приоритете учётных данных, настройке профилей и сопоставлении правил.
• Для самоуправляемых кластеров Kubernetes, не работающих на EKS, см. Использование WIF с Kubernetes.