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

SPIFFE — это стандарт CNCF для выдачи идентичности рабочим нагрузкам. SPIRE — его эталонная реализация с открытым исходным кодом, и несколько коммерческих продуктов также выдают идентичности, соответствующие SPIFFE. Anthropic федерируется с любой реализацией SPIFFE, которая выпускает OIDC-совместимые JWT-SVID. Актуальный список реализаций см. в разделе Commercial software that implements SPIFFE на сайте проекта SPIFFE.

Федерация работает либо через документ обнаружения OIDC по публичному HTTPS URL (режим discovery, с учётом ограничений URL), либо путём прямой регистрации JWKS (режим inline).

Спецификация JWT-SVID определяет sub как SPIFFE ID рабочей нагрузки, а SPIFFE Workload API требует, чтобы вызывающая сторона предоставила aud во время получения, поэтому эти утверждения (claims) одинаковы во всех реализациях. Anthropic дополнительно требует iss и iat, ни одно из которых спецификация JWT-SVID не предписывает, поэтому настройте вашу реализацию так, чтобы она заполняла оба (в SPIRE iss — это настройка сервера jwt_issuer, а iat устанавливается автоматически). При их наличии разделы Настройка Anthropic, Получение и использование токена и Ограничение области действия правила этого руководства применимы к любой реализации SPIFFE.

SPIFFE назначает каждой рабочей нагрузке стабильный URI идентичности вида spiffe://<trust-domain>/<path>, а SPIRE выдаёт эту идентичность как JWT-SVID по запросу через Workload API. JWT-SVID — это обычный подписанный JWT, чьё утверждение sub является SPIFFE ID рабочей нагрузки, а утверждение aud предоставляется рабочей нагрузкой во время получения.

Мостом от доверенного домена SPIRE к стандартному OIDC является SPIRE OIDC Discovery Provider — автономный вспомогательный сервис, который публикует /.well-known/openid-configuration и конечную точку JWKS для ключей подписи JWT доверенного домена. При работающем провайдере обнаружения JWT-SVID валидируется как любой другой токен OIDC: зарегистрируйте URL обнаружения как издателя федерации, напишите правило федерации, соответствующее SPIFFE ID рабочей нагрузки, и пусть рабочая нагрузка предъявляет свой JWT-SVID конечной точке обмена токенами Anthropic.

Примеры на этой странице используют SPIRE и применимы везде, где работает SPIRE Agent: поды Kubernetes, виртуальные машины и физические хосты.



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

• Знакомство с концепциями WIF: сервисные аккаунты, издатели федерации и правила федерации.
• Развёртывание SPIFFE с выданными идентичностями рабочих нагрузок (примеры на этой странице используют SPIRE Server и Agent) и записями регистрации для рабочих нагрузок, которым нужно вызывать Claude API.
• Конечная точка обнаружения OIDC для доверенного домена (в SPIRE — OIDC Discovery Provider), работающая с публично доступной конечной точкой HTTPS, или JWKS, экспортированный для регистрации в режиме inline.
• Ваш издатель SPIFFE настроен так, чтобы устанавливать утверждение iss в JWT-SVID в значение, которое вы зарегистрируете как issuer_url издателя федерации. Для режима discovery это публичный URL конечной точки обнаружения (в SPIRE — настройка сервера jwt_issuer).
• JWT-SVID доступны вашим рабочим нагрузкам. WIF принимает только JWT-SVID, но не X.509-SVID.
• Разрешение на создание сервисных аккаунтов, издателей федерации и правил федерации в Claude Console для вашей организации Anthropic.

Значение аудитории, которое нужно запрашивать при получении JWT-SVID, всегда равно https://api.anthropic.com. Используйте это значение в jwt_audience spiffe-helper, в вызове Workload API FetchJWTSVID и в сопоставителе audience правила федерации.



Настройка SPIRE

Инструкции в этом разделе специфичны для SPIRE. Если вы используете другого издателя SPIFFE, настройте его конечную точку обнаружения OIDC и получение JWT-SVID согласно его собственной документации, затем продолжите с раздела Настройка Anthropic.

Если вы уже используете SPIRE с OIDC Discovery Provider, для федерации с Anthropic на стороне SPIRE требуются три вещи: jwt_issuer, совпадающий с URL обнаружения, запись регистрации для рабочей нагрузки, которая будет вызывать Claude API, и способ для этой рабочей нагрузки получить JWT-SVID с аудиторией Anthropic. Следующие подразделы рассматривают каждую из них. Фрагменты конфигурации показывают только настройки, относящиеся к федерации с Anthropic, а не полные конфигурации развёртывания SPIRE.



Проверка издателя JWT

Anthropic валидирует JWT-SVID, сопоставляя его утверждение iss с зарегистрированным издателем федерации и получая JWKS из документа обнаружения этого издателя. Две настройки SPIRE должны указывать на один и тот же URL: jwt_issuer SPIRE Server (который становится утверждением iss в каждом выпущенном JWT-SVID) и список domains OIDC Discovery Provider (который определяет хост, с которого обслуживаются документ обнаружения и JWKS). Этот общий URL и есть то, что вы регистрируете в Anthropic.

Доверенный домен и URL издателя независимы. Доверенный домен (spiffe://prod.example.com) определяет область утверждения sub. URL издателя (https://oidc-discovery.prod.example.com) — это место, откуда Anthropic получает ключи подписи. Им не обязательно иметь общее имя хоста.

Убедитесь, что jwt_issuer установлен в конфигурации SPIRE Server и указывает на публичный URL провайдера обнаружения. Следующий пример также показывает время жизни JWT-SVID по умолчанию. Встроенное значение по умолчанию в SPIRE — 5 минут, что достаточно мало, чтобы требовалась непрерывная ротация (см. Запуск spiffe-helper). Конечная точка обмена токенами Anthropic отклоняет любой токен идентичности, время жизни которого превышает настроенный максимум издателя федерации, который по умолчанию составляет 1 час (см. Правила валидации). Эта проверка применяется к каждой реализации SPIFFE, а не только к SPIRE, поэтому держите default_jwt_svid_ttl (или любое переопределение на уровне записи) на уровне этого максимума или ниже.

server {
    trust_domain         = "prod.example.com"
    jwt_issuer           = "https://oidc-discovery.prod.example.com"
    default_jwt_svid_ttl = "5m"
    # ...
}

В конфигурации OIDC Discovery Provider то же имя хоста должно присутствовать в domains, и провайдер должен иметь доступ к сокету API SPIRE Server. Провайдер обслуживает документ обнаружения и JWKS по HTTPS. Терминируйте TLS с помощью его встроенной поддержки ACME или поставьте перед ним балансировщик нагрузки, который это делает.

domains = ["oidc-discovery.prod.example.com"]

server_api {
    address = "unix:///run/spire/sockets/private/api.sock"
}

acme {
    email        = "[email protected]"
    tos_accepted = true
}



Регистрация рабочей нагрузки

Каждой рабочей нагрузке, вызывающей Claude API, нужна запись регистрации SPIRE, которая сопоставляет её селекторы времени выполнения со SPIFFE ID. Если рабочая нагрузка уже зарегистрирована, запишите её SPIFFE ID, который вы используете в subject_prefix правила федерации. Если нет, зарегистрируйте её. Для пода Kubernetes селекторами обычно являются пространство имён и сервисный аккаунт Kubernetes:

# Замените NODE_UID на UID узла:
#   kubectl get node <node-name> -o jsonpath='{.metadata.uid}'
spire-server entry create \
    -spiffeID spiffe://prod.example.com/ns/inference/sa/worker \
    -parentID spiffe://prod.example.com/spire/agent/k8s_psat/prod-cluster/NODE_UID \
    -selector k8s:ns:inference \
    -selector k8s:sa:worker

Рабочие нагрузки вне Kubernetes используют селекторы уровня хоста, такие как unix:uid:1000 (unix:path также доступен, но требует discover_workload_path = true в конфигурации unix workload attestor агента). Кластеры, использующие spire-controller-manager, могут объявлять записи с помощью пользовательского ресурса ClusterSPIFFEID вместо прямого вызова spire-server entry create.



Запуск spiffe-helper

spiffe-helper — это утилита-сайдкар, которая подключается к сокету SPIRE Agent, получает JWT-SVID для заданной аудитории, записывает его в файл и повторно получает его до истечения срока действия. Помощник по умолчанию работает в режиме демона. Следующий пример явно устанавливает daemon_mode = true.

agent_address = "/run/spire/sockets/agent.sock"
# The JWT-SVID file is written under cert_dir
cert_dir      = "/var/run/secrets/anthropic.com"
daemon_mode   = true

jwt_svids = [{
    jwt_audience       = "https://api.anthropic.com"
    jwt_svid_file_name = "token"
}]

В Kubernetes запускайте spiffe-helper как сайдкар-контейнер, который разделяет том emptyDir в памяти (medium: Memory) с вашим контейнером приложения, чтобы bearer SVID никогда не попадал на диск узла. Смонтируйте сокет SPIRE Agent с хоста в сайдкар, смонтируйте общий том по пути /var/run/secrets/anthropic.com в обоих контейнерах и установите ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token в контейнере приложения. На виртуальных машинах и физических хостах запускайте spiffe-helper как системный сервис рядом с рабочей нагрузкой и направьте оба на общий каталог.



Настройка Anthropic

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

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

Издатель федерации: Зарегистрируйте публичный URL OIDC Discovery Provider в режиме discovery. Anthropic получает /.well-known/openid-configuration с этого URL и следует по возвращённому jwks_uri, чтобы получить ключи подписи доверенного домена.

{
  "name": "spire-prod",
  "issuer_url": "https://oidc-discovery.prod.example.com",
  "jwks": { "type": "discovery" }
}

Если провайдер обнаружения недоступен из публичного интернета, получите JWKS самостоятельно (curl https://oidc-discovery.prod.example.com/keys) и зарегистрируйте издателя с "jwks": {"type": "inline", "keys": [...]}, используя содержимое возвращённого массива keys. В режиме inline issuer_url сравнивается только с утверждением iss JWT-SVID. Anthropic никогда не пытается к нему обратиться.

Чтобы автоматизировать обновления JWKS без публикации публичной конечной точки обнаружения, настройте плагин BundlePublisher SPIRE Server (aws_s3, gcp_cloudstorage или k8s_configmap) с format = "jwks", чтобы отправлять ключи подписи JWT во внешнее хранилище при каждой ротации, затем обновляйте inline-ключи издателя через Admin API.

Правило федерации: Сопоставьте sub JWT-SVID (SPIFFE ID) и aud, который вы настроили для запроса в spiffe-helper. SPIFFE ID — это строки URI, и subject_prefix сопоставляет их как непрозрачный текст, поэтому как точное значение, так и сопоставление по префиксу с завершающим * работают с ними. Для более сложных шаблонов используйте condition на CEL.

{
  "name": "spire-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "spiffe://prod.example.com/ns/inference/sa/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
}

token_lifetime_seconds — это время жизни токена доступа Anthropic, который возвращает обмен, а не JWT-SVID. SDK обновляет токен доступа автоматически.

Будьте настолько конкретны, насколько позволяет рабочая нагрузка. Ослабляйте subject_prefix до spiffe://prod.example.com/ns/inference/* только если каждая рабочая нагрузка, зарегистрированная по этому пути, должна сопоставляться с одним и тем же сервисным аккаунтом Anthropic. Добавьте ID правила fdrl_... в переменную окружения ANTHROPIC_FEDERATION_RULE_ID рабочей нагрузки.



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

SDK Anthropic могут либо читать JWT-SVID из файла, который поддерживает spiffe-helper, либо вызывать SPIFFE Workload API напрямую через вызываемый объект-поставщик токенов. Путь через файл — самая простая интеграция, работающая на всех языках SDK. Путь через вызываемый объект устраняет сайдкар, но требует клиента SPIFFE Workload API на языке вашего приложения.

import anthropic

# Считывает JWT-SVID, который spiffe-helper записывает в
# ANTHROPIC_IDENTITY_TOKEN_FILE, а также ANTHROPIC_FEDERATION_RULE_ID,
# ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID и ANTHROPIC_WORKSPACE_ID.
client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))



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

Прежде чем подключать SDK, получите JWT-SVID напрямую от SPIRE Agent и убедитесь, что утверждения соответствуют тому, что ожидает ваше правило федерации. Если вы используете другую реализацию SPIFFE, получите JWT-SVID с помощью её CLI или клиента Workload API и декодируйте полезную нагрузку тем же способом.

spire-agent api fetch jwt \
    -audience https://api.anthropic.com \
    -socketPath /run/spire/sockets/agent.sock \
    -output json \
  | jq -r '.[0].svids[0].svid' \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

Флаг -output json возвращает ответ SVID и ответ бандла как JSON-массив из двух элементов, поэтому jq -r '.[0].svids[0].svid' извлекает сам токен. В более старых версиях SPIRE без -output команда вместо этого выводит блок с метками. В этом случае пропустите вывод по умолчанию через awk '/^[[:space:]]*eyJ/{print $1; exit}', чтобы извлечь строку токена. Проверьте, что iss — это URL OIDC Discovery Provider, который вы зарегистрировали, sub — это SPIFFE ID рабочей нагрузки, а aud содержит https://api.anthropic.com. Затем выполните пример cURL из раздела Получение и использование токена. Успешный обмен возвращает access_token, начинающийся с sk-ant-oat01-. При 400 invalid_grant см. Устранение неполадок при неудачном обмене. Самая распространённая причина на стороне SPIRE — несоответствие между jwt_issuer SPIRE Server и URL, зарегистрированным как издатель федерации.



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

Соглашения о путях SPIFFE ID определяются оператором, поэтому сопоставитель subject_prefix правила федерации должен отражать схему путей, которую используют ваши записи регистрации. Распространённые схемы включают spiffe://<trust-domain>/ns/<namespace>/sa/<service-account> (значение по умолчанию, выдаваемое ресурсом ClusterSPIFFEID в spire-controller-manager) и spiffe://<trust-domain>/host/<hostname>/<service> для рабочих нагрузок на виртуальных машинах и физических хостах.

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

• Привязка к одной рабочей нагрузке: Установите subject_prefix в полный SPIFFE ID без завершающего *.
• Всегда устанавливайте аудиторию: Требуйте audience в правиле и настройте spiffe-helper (или вызов Workload API) с тем же значением, чтобы SVID, выпущенные для других доверяющих сторон, отклонялись.
• Ограничение по сегменту пути: Используйте spiffe://prod.example.com/ns/inference/*, чтобы предоставить доступ каждой рабочей нагрузке, зарегистрированной в пространстве имён, и создавайте отдельное правило и сервисный аккаунт Anthropic для каждого пространства имён вместо расширения одного правила.
• Один издатель на доверенный домен: Каждый доверенный домен SPIRE имеет собственные ключи подписи и OIDC Discovery Provider. Зарегистрируйте каждый как отдельного издателя федерации и привяжите правила к издателю, которому принадлежат SPIFFE ID, которым они соответствуют.



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