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

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

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

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

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

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

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

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

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

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

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

В ant CLI настройки для Claude Models on Google Cloud (Anthropic managed) имеют приоритет ниже переменных окружения федерации и выше активного профиля. К этим настройкам относятся проект, идентификатор рабочего пространства и расположение. Они задаются с помощью флагов --google-cloud-* или переменных ANTHROPIC_GOOGLE_CLOUD_*. CLI использует эти настройки, если задана хотя бы одна из них. С этими настройками CLI получает учётные данные из Google Application Default Credentials.

Когда профиль загружен, переменные окружения заполняют поля, которые профиль не указывает, но никогда не переопределяют поля, явно заданные в профиле. Например, 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 сообщает о сбое обмена как WorkloadIdentityError, что предоставляет HTTP-статус и сведения об ошибке из тела ответа. ID запроса содержится в ошибке в Python, TypeScript и Ruby, а в Java — в заголовках ответа исключения. В Go он есть только в сообщении ошибки, поскольку тип ошибки находится во внутреннем пакете; ошибки C# и PHP его не содержат.

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

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

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

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

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

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

1. 1

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

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

   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 от этого издателя. Это размеченное объединение (discriminated union) с ключом type:

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

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

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

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