Справочник по WIF

На этой странице собраны поверхности конфигурации, ограничения валидации и сопоставления ошибок для Workload Identity Federation (федерации удостоверений рабочих нагрузок), или WIF. Пошаговые инструкции по настройке см. в руководствах по провайдерам.

Запрос обмена токена

POST /v1/oauth/token принимает тело JSON, использующее грант jwt-bearer из RFC 7523. SDK формируют этот запрос за вас на основе переменных окружения; примеры cURL в каждом руководстве по провайдеру показывают необработанное тело запроса.

Ответ обмена токена

POST /v1/oauth/token возвращает стандартный ответ с токеном OAuth 2.0 (RFC 6749 §5.1):

Переменные окружения

SDK читает эти переменные, чтобы выполнить федеративный обмен токена без аргументов конструктора.

Прямой путь федерации через переменные окружения активируется только тогда, когда заданы все переменные ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID и одна из ANTHROPIC_IDENTITY_TOKEN_FILE или ANTHROPIC_IDENTITY_TOKEN. ANTHROPIC_WORKSPACE_ID читается вместе с ними, но не влияет на активацию.

Приоритет учётных данных

SDK разрешает учётные данные в следующем порядке. Побеждает первый источник, который даёт учётные данные.

Когда профиль загружен, переменные окружения заполняют любые поля, которые профиль опускает, но никогда не переопределяют поля, которые профиль задаёт явно. Например, ANTHROPIC_WORKSPACE_ID заполняет workspace_id только тогда, когда активный профиль его не задаёт.

Файл конфигурации профиля

Профиль — это именованный файл конфигурации, который читают и SDK, и CLI ant. Профили позволяют поставлять параметры федерации вместе с образом контейнера или переключаться между окружениями без изменения кода.

Каталог конфигурации

SDK находит каталог конфигурации в следующем порядке:

1. $ANTHROPIC_CONFIG_DIR
2. ~/.config/anthropic в Linux и macOS
3. %APPDATA%\Anthropic в Windows

Активный профиль

Имя активного профиля разрешается в следующем порядке:

1. $ANTHROPIC_PROFILE
2. Содержимое <config_dir>/active_config (однострочный файл, записываемый командой ant profile activate <name>)
3. Литеральное имя default

Claude Code и Claude Agent SDK соблюдают тот же порядок разрешения, поэтому профиль федерации, настроенный здесь, также аутентифицирует эти инструменты без дополнительной настройки.

Структура файлов

И файл конфигурации, и файл учётных данных содержат строковое поле верхнего уровня version в формате major.minor (в настоящее время "1.0"). SDK записывает это поле автоматически, чтобы будущие выпуски могли обнаруживать и мигрировать старые форматы; опустите его при написании конфигурации вручную, и SDK будет считать файл соответствующим текущей версии.

Пример профиля федерации

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

Если authentication.identity_token опущен, SDK использует ANTHROPIC_IDENTITY_TOKEN_FILE или ANTHROPIC_IDENTITY_TOKEN из окружения.

Области OAuth

oauth_scope, который вы задаёте в правиле федерации, определяет, какие конечные точки Claude API может вызывать выпущенный токен доступа.

Запрос к конечной точке вне области токена возвращает HTTP 403. Более детальные области (по ресурсу или чтение против записи) в настоящее время недоступны.

Границы разрешений

oauth_scope правила федерации — это потолок: выпущенный токен никогда не может его превысить. organization_role целевого сервисного аккаунта (developer или admin) определяет, какие области могут быть предоставлены, поэтому правило, предоставляющее org:admin, должно быть нацелено на сервисный аккаунт с organization_role=admin. Эффективные разрешения — это пересечение области правила и роли сервисного аккаунта.

Правила валидации

Anthropic применяет эти ограничения, когда вы создаёте или обновляете издателей и правила, а также при проверке входящего JWT в момент обмена.

Полные сведения о параметрах и схемы ответов см. в справочнике API сервисных аккаунтов, справочнике API издателей федерации и справочнике API правил федерации.

Поля ресурсов

Поля URL

Поля issuer_url, jwks.discovery_base и jwks.url проходят валидацию:

Ошибки валидации URL возвращают 400 invalid_request_error с именем поля в качестве префикса сообщения об ошибке (например, issuer_url: url must use https scheme).

Проверка JWT

Семантика сопоставления правил

Блок match правила федерации определяет, принимается ли входящий JWT. Все заполненные поля оцениваются с семантикой AND: JWT должен удовлетворять каждому заполненному сопоставителю. Должно быть задано хотя бы одно из subject_prefix, claims или condition; блок match, содержащий только audience (или вообще не содержащий сопоставителей), отклоняется. Это защищает от правил, которые принимали бы любой токен от издателя.

Среда вычисления CEL

Выражение condition имеет доступ к единственной переменной:

Пример:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Ошибки

Ошибки обмена токена

POST /v1/oauth/token возвращает ошибки в стандартной форме ошибок API. SDK оборачивает сбои обмена в типизированную FederationExchangeError (или эквивалент для языка), которая предоставляет HTTP-статус, тело ответа и request_id.

Каждый отказ по assertion возвращает одну и ту же непрозрачную ошибку 401 authentication_error с фиксированным сообщением Authentication failed, независимо от того, какая проверка не прошла; различимая ошибка позволила бы вызывающему зондировать конфигурацию правила. Причина отказа записывается в записи о попытке в истории аутентификации, например match_subject_prefix, когда утверждение sub не проходит subject_prefix правила, или workspace_id_required, когда правило охватывает несколько рабочих пространств, а запрос не указывает ни одного. Запросы, отклонённые до подтверждения организации правила (семейство 400 invalid_request_error выше), не оставляют записи в истории; их сообщения ответа прямо называют проблему. 401 без соответствующей записи в истории обычно означает, что сам federation_rule_id не был распознан.

Распространённые сбои на стороне SDK

Устранение неполадок при неудачном обмене

Ответ 401 authentication_error намеренно непрозрачен, и его сообщение всегда Authentication failed; причина отказа записывается в истории аутентификации, а не в ответе.

Один из распространённых непрозрачных сбоев — повторно воспроизведённый assertion: assertion, содержащий утверждение jti, может быть обменян только один раз, поэтому рабочая нагрузка, повторно отправляющая тот же JWT (цикл повторных попыток или обновление, перечитывающее неротированный токен), отклоняется при втором обмене. Страница истории аутентификации показывает эти попытки с причиной jti_reused; решение — выпускать свежий assertion для каждого обмена.

Если вам всё же нужно отлаживать по самому JWT, пройдите эти проверки по порядку:

1. 1

   Декодируйте JWT

   Декодируйте отправленный вами assertion, чтобы сравнить каждое утверждение с конфигурацией вашего издателя и правила:

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   Проверьте, что iss совпадает с издателем

   Декодированное утверждение iss должно побайтово совпадать с зарегистрированным issuer_url, включая схему, порт и любой завершающий слэш. Несовпадение в одном символе приводит к сбою проверки.

3. 3

   Проверьте, что aud совпадает с правилом

   Декодированное утверждение aud должно содержать значение audience правила как точное совпадение. Когда aud — массив, один элемент должен совпадать точно.

4. 4

   Проверьте sub и каждую запись claims

   Сравните sub с subject_prefix правила (чувствителен к регистру; завершающий * означает совпадение по префиксу, всё остальное — точное совпадение). Сравните каждый ключ в карте claims правила с одноимённым утверждением верхнего уровня.

5. 5

   Проверьте exp, nbf и iat

   exp должен быть в будущем, а nbf/iat должны быть в прошлом, в пределах 30-секундного окна расхождения. Если часы хоста рабочей нагрузки ушли, в остальном действительный токен отклоняется.

6. 6

   Проверьте доступность JWKS

   Для режима discovery запросите <jwks.discovery_base or issuer_url>/.well-known/openid-configuration по публичному HTTPS на порту 443 и убедитесь, что jwks_uri разрешается. Для explicit_url запросите URL JWKS напрямую. Для inline убедитесь, что ключ подписи издателя не ротировался с момента регистрации ключей.

   Если издатель ротировал свой ключ подписи и сразу начал им подписывать, обмены могут завершаться сбоем в течение до одной минуты, пока обновляется кэш JWKS Anthropic. См. Ротация ключей и кэширование.

Режимы источника JWKS

Когда вы регистрируете издателя федерации, поле jwks управляет тем, как Anthropic получает открытые ключи, используемые для проверки подписей JWT от этого издателя. Это размеченное объединение с дискриминатором type:

Размеченное объединение делает сопутствующие поля взаимоисключающими по построению. И discovery, и explicit_url также принимают необязательную строку ca_cert_pem для издателей, которые обслуживают TLS от частного CA.

Ротация ключей и кэширование

В режимах discovery и explicit_url Anthropic кэширует полученный JWKS. Если ваш провайдер удостоверений публикует новый ключ подписи и сразу начинает подписывать им токены, обмены, предъявляющие эти токены, могут завершаться ошибкой подписи в течение до 1 минуты, пока обновляется кэш.

Чтобы избежать этого окна, публикуйте новый ключ подписи в JWKS как минимум за 15 минут до того, как ваш провайдер удостоверений начнёт подписывать им токены, и сохраняйте заменённый ключ в JWKS до тех пор, пока не истекут подписанные им токены. Управляемые провайдеры удостоверений обычно соблюдают эту дисциплину самостоятельно. Если вы эксплуатируете собственного издателя (самостоятельно управляемый кластер Kubernetes, провайдер обнаружения OIDC SPIRE или пользовательский сервер авторизации Okta с настроенной периодичностью ротации), убедитесь, что ваша политика ротации публикует новые ключи до их первого использования.