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

Рабочие нагрузки AWS могут аутентифицироваться в Claude API без статических ключей API (API key), обменивая подписанный 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

В Claude Console откройте Settings → Workload identity, нажмите Connect workload и выберите плитку AWS. Мастер проведёт вас через регистрацию издателя, создание сервисного аккаунта и создание правила федерации.

Мастер создаёт эти ресурсы за вас. Используйте следующие значения независимо от того, вводите ли вы их в мастере или отправляете в Admin API:

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

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

Правило федерации: Сопоставьте аудиторию, которую вы передаёте в 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-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"))



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

Изнутри рабочей нагрузки обменяйте токен, выданный 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

В Claude Console откройте Settings → Workload identity, нажмите Connect workload и выберите плитку AWS. Мастер проведёт вас через регистрацию издателя, создание сервисного аккаунта и создание правила федерации.

Мастер создаёт эти ресурсы за вас. Используйте следующие значения независимо от того, вводите ли вы их в мастере или отправляете в Admin API:

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

{
  "name": "prod-eks-uswest2",
  "issuer_url": "https://oidc.eks.us-west-2.amazonaws.com/id/6FA42E7BFDE8549CB...",
  "jwks": { "type": "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-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"))



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

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

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:.
• Используйте отдельное правило для каждой среды: Создавайте отдельные правила для производственных, промежуточных и разрабатываемых рабочих нагрузок вместо расширения одного префикса для охвата их всех.



Следующие шаги

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