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

Прямой путь федерации через переменные окружения активируется только тогда, когда 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 оборачивает сбои обмена в типизированный WorkloadIdentityError, который предоставляет HTTP-статус, тело ответа и request_id.

Каждый отказ в утверждении возвращает одинаковую непрозрачную ошибку 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; причина отказа записывается в истории аутентификации, а не в ответе.

Один распространённый непрозрачный сбой — это повторённое утверждение: утверждение, несущее утверждение 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 от этого эмитента. Это дискриминированное объединение с ключом по type:

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

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

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

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