Использование 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 указывается рабочей нагрузкой в момент получения.

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

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

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

• Знакомство с концепциями 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.

Значение аудитории (audience), которое нужно запрашивать при получении JWT-SVID, всегда https://api.anthropic.com. Используйте это значение в jwt_audience spiffe-helper, в вызове FetchJWTSVID Workload API и в сопоставителе 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        = "platform@example.com"
    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-аттестатора рабочих нагрузок агента). Кластеры, в которых работает spire-controller-manager, могут объявлять записи с помощью пользовательского ресурса ClusterSPIFFEID вместо прямого вызова spire-server entry create.

Запуск spiffe-helper

spiffe-helper — это sidecar-утилита, которая подключается к сокету SPIRE Agent, получает JWT-SVID для заданной аудитории, записывает его в файл и повторно получает его до истечения срока действия. По умолчанию helper работает в режиме демона. Следующий пример явно задаёт 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 как sidecar-контейнер, разделяющий том emptyDir в памяти (medium: Memory) с контейнером вашего приложения, чтобы bearer-SVID никогда не попадал на диск узла. Смонтируйте сокет SPIRE Agent с хоста в sidecar, смонтируйте общий том в /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 без публикации публичной конечной точки обнаружения, настройте плагин SPIRE Server BundlePublisher (aws_s3, gcp_cloudstorage или k8s_configmap) с format = "jwks", чтобы отправлять ключи подписи JWT во внешнее хранилище при каждой ротации, а затем обновляйте встроенные ключи издателя через Admin API.

Правило федерации: Сопоставляйте 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
}

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 напрямую через вызываемый объект (callable) поставщика токенов. Путь через файл — самая простая интеграция, работающая на каждом языке SDK. Путь через callable устраняет sidecar, но требует клиента 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-. Если обмен завершается неудачей с непрозрачным ответом 401 authentication_error (сообщение Authentication failed), проверьте причину отказа на странице истории аутентификации и см. Устранение неполадок при неудачном обмене. Самая распространённая причина на стороне 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.

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