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

SPIFFE — это стандарт CNCF для выдачи идентификаторов рабочим нагрузкам. SPIRE — его эталонная реализация с открытым исходным кодом; ряд коммерческих продуктов также выдаёт идентификаторы, совместимые со SPIFFE. Anthropic поддерживает федерацию с любой реализацией SPIFFE, которая выпускает JWT-SVID, совместимые с OIDC. Федерация работает либо через документ обнаружения OIDC по публичному HTTPS-URL (режим discovery; см. ограничения на URL), либо через прямую регистрацию JWKS (режим inline). Спецификация JWT-SVID определяет sub как SPIFFE ID рабочей нагрузки, а SPIFFE Workload API требует, чтобы вызывающая сторона передавала aud в момент получения токена, поэтому эти утверждения одинаковы во всех реализациях. Anthropic дополнительно требует iss и iat, ни одно из которых спецификация JWT-SVID не предписывает, поэтому настройте свою реализацию так, чтобы она заполняла оба (в SPIRE iss задаётся серверной настройкой jwt_issuer, а iat устанавливается автоматически). После этого разделы Настройка Anthropic, Получение и использование токена и Ограничение области действия правила данного руководства применимы к любой реализации SPIFFE. Актуальный список см. в разделе Commercial software that implements SPIFFE на сайте проекта 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:

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 агента). Кластеры, в которых работает spire-controller-manager, могут объявлять записи с помощью пользовательского ресурса ClusterSPIFFEID вместо прямого вызова spire-server entry create.

Запуск spiffe-helper

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

agent_address = "/run/spire/sockets/agent.sock"
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) с контейнером вашего приложения, чтобы SVID-токен никогда не попадал на диск узла. Смонтируйте сокет SPIRE Agent с хоста в сайдкар, смонтируйте общий том по пути /var/run/secrets/anthropic.com в обоих контейнерах и установите ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token в контейнере приложения. На виртуальных машинах и физических серверах запускайте spiffe-helper как системную службу рядом с рабочей нагрузкой и направьте обе на общий каталог.

Настройка Anthropic

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

Эмитент федерации: Зарегистрируйте публичный 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 без публикации открытой конечной точки обнаружения, настройте плагин SPIRE Server BundlePublisher (aws_s3, gcp_cloudstorage или k8s_configmap) с format = "jwks", чтобы при каждой ротации выгружать ключи подписи JWT во внешнее хранилище, а затем синхронизируйте их во встроенные ключи эмитента.

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

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

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

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

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

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

Прежде чем подключать 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.

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

• Workload Identity Federation: концепции, процесс обмена токенами и параметры конфигурации SDK.
• Справочник по WIF: переменные окружения, режимы источника JWKS и режимы сопоставления правил.
• Использование WIF с Kubernetes: для кластеров, использующих нативные проецируемые токены сервисных аккаунтов вместо SPIRE.