--- title: Справочник по WIF url: https://platform.claude.com/docs/ru/manage-claude/wif-reference description: Переменные окружения, правила валидации, конфигурация профилей и справочник ошибок для Workload Identity Federation. --- На этой странице собраны параметры конфигурации, ограничения валидации и соответствия ошибок для [Workload Identity Federation](https://platform.claude.com/docs/ru/manage-claude/workload-identity-federation). Пошаговые инструкции по настройке см. в [руководствах по провайдерам](https://platform.claude.com/docs/ru/manage-claude/workload-identity-federation#identity-providers). ## Запрос на обмен токена `POST /v1/oauth/token` принимает тело JSON с грантом `jwt-bearer` по [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523). SDK формирует этот запрос за вас на основе [переменных окружения](https://platform.claude.com/docs/ru/manage-claude/wif-reference#environment-variables); примеры cURL в каждом руководстве по провайдеру показывают необработанное тело запроса. | Поле | Обязательное | Описание | | -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `grant_type` | Да | Всегда `urn:ietf:params:oauth:grant-type:jwt-bearer`. | | `assertion` | Да | OIDC JWT, выданный вашим провайдером удостоверений. | | `federation_rule_id` | Да | Тегированный ID (`fdrl_...`) правила федерации, которое нужно проверить. | | `organization_id` | Да | UUID вашей организации Anthropic. | | `service_account_id` | Да | Тегированный ID (`svac_...`) целевого сервисного аккаунта. | | `workspace_id` | Условно | Тегированный ID (`wrkspc_...`) рабочего пространства, которым ограничивается выпущенный токен. Обязателен, если правило включено более чем для одного рабочего пространства. Если не указан, сервер выбирает единственное рабочее пространство, для которого включено правило. Литерал `default` также работает для рабочего пространства по умолчанию (Default Workspace) организации, но устарел; используйте ID `wrkspc_...` этого рабочего пространства. | ## Ответ на обмен токена `POST /v1/oauth/token` возвращает стандартный ответ с токеном OAuth 2.0 ([RFC 6749 §5.1](https://www.rfc-editor.org/rfc/rfc6749#section-5.1)): | Поле | Тип | Описание | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | `access_token` | string | Краткосрочный токен Anthropic с префиксом `sk-ant-oat01-...`. Передавайте его как `Authorization: Bearer `. | | `token_type` | string | Всегда `Bearer`. | | `expires_in` | integer | Количество секунд до истечения срока действия токена. | | `scope` | string | Область OAuth, предоставленная совпавшим правилом. | ## Переменные окружения SDK считывает эти переменные, чтобы выполнить федеративный «token exchange» (обмен токена) без аргументов конструктора. | Переменная | Обязательная | Описание | Пример | | ------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `ANTHROPIC_FEDERATION_RULE_ID` | Да | Тегированный ID правила федерации, которое нужно проверить. | `fdrl_...` | | `ANTHROPIC_ORGANIZATION_ID` | Да | UUID вашей организации Anthropic. Его можно найти на странице [Organization](https://platform.claude.com/settings/organization) (`platform.claude.com/settings/organization`) в Claude Console. | `00000000-0000-0000-0000-000000000000` | | `ANTHROPIC_IDENTITY_TOKEN_FILE` | Одна из `_TOKEN_FILE` или `_TOKEN` | Путь в файловой системе к JWT, выданному вашим «identity provider» (провайдером удостоверений), или IdP. SDK перечитывает этот файл при каждом обмене, поэтому проецируемые токены, которые ротируются на диске, всегда актуальны. | `/var/run/secrets/anthropic.com/token` | | `ANTHROPIC_IDENTITY_TOKEN` | Одна из `_TOKEN_FILE` или `_TOKEN` | Сам JWT в виде строки. Используйте, когда ваша платформа внедряет токен как переменную окружения, а не как файл. | `eyJhbGciOiJSUzI1NiIs...` | | `ANTHROPIC_SERVICE_ACCOUNT_ID` | Да | Тегированный ID целевого сервисного аккаунта Anthropic, от имени которого действует выданный токен доступа. | `svac_...` | | `ANTHROPIC_WORKSPACE_ID` | Условно | Тегированный ID рабочего пространства, которым ограничивается выпущенный токен. Обязателен, если правило федерации включено более чем для одного рабочего пространства; необязателен, если правило привязано к одному рабочему пространству. Выпущенный токен ограничивается этим рабочим пространством в момент обмена, поэтому для смены рабочего пространства требуется новый обмен. Литерал `default` также работает для рабочего пространства по умолчанию, но устарел; используйте его ID `wrkspc_...`. | `wrkspc_...` | | `ANTHROPIC_PROFILE` | Нет | Имя [профиля конфигурации](https://platform.claude.com/docs/ru/manage-claude/wif-reference#profile-configuration-file) для загрузки. Имеет приоритет над переменными окружения федерации из этой таблицы. | `staging-profile` | Прямой путь федерации через переменные окружения активируется только тогда, когда заданы все переменные `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` и одна из `ANTHROPIC_IDENTITY_TOKEN_FILE` или `ANTHROPIC_IDENTITY_TOKEN`. `ANTHROPIC_WORKSPACE_ID` считывается вместе с ними, но не влияет на активацию. Переменная, которой присвоена пустая строка, всё равно может занимать свою позицию в цепочке приоритета учётных данных. Удаляйте неиспользуемые переменные учётных данных с помощью unset, а не присваивайте им пустые значения. ### Приоритет учётных данных SDK определяет учётные данные в следующем порядке. Побеждает первый источник, который предоставляет учётные данные. | Порядок | Источник | Примечания | | ------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Аргумент конструктора (`api_key=`, `auth_token=`, `credentials=`) | Всегда переопределяет всё остальное. | | 2 | `ANTHROPIC_API_KEY` или `ANTHROPIC_AUTH_TOKEN` | Полностью перекрывает федерацию. Удалите эти переменные при переходе с ключей API. | | 3 | `ANTHROPIC_PROFILE` | Загружает `/configs/.json`. Отсутствие именованного профиля является ошибкой, а не переходом к следующему источнику. | | 4 | Переменные окружения федерации | `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`. | | 5 | Активный профиль | Определяется из `/active_config`, с откатом к профилю с именем `default`. | Когда профиль загружен, переменные окружения заполняют поля, которые профиль не указывает, но никогда не переопределяют поля, явно заданные в профиле. Например, `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. Содержимое `/active_config` (однострочный файл, записываемый командой `ant profile activate `) 3. Литеральное имя `default` Claude Code и Claude Agent SDK соблюдают тот же порядок определения, поэтому настроенный здесь профиль федерации также аутентифицирует эти инструменты без дополнительной настройки. ### Структура файлов | Путь | Содержимое | Конфиденциальность | | ----------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `/configs/.json` | `version`, блок `authentication`, `organization_id`, `workspace_id` и `base_url`. | Не секретно. Можно безопасно коммитить или встраивать в образ. | | `/credentials/.json` | `version`, кэшированный `access_token`, `expires_at` и (для интерактивного входа) `refresh_token`. | Секретно. Записывается SDK с режимом `0600`. | И файл конфигурации, и файл учётных данных содержат строковое поле верхнего уровня `version` в формате `major.minor` (в настоящее время `"1.0"`). SDK записывает это поле автоматически, чтобы будущие версии могли обнаруживать и мигрировать старые форматы; не указывайте его при ручном создании конфигурации, и SDK будет считать файл текущей версией. ### Пример профиля федерации ```json configs/production.json { "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 может вызывать выпущенный токен доступа. | Область | Предоставляет доступ к | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | Всем неадминистративным эндпоинтам Claude API в рабочем пространстве правила: [Messages](https://platform.claude.com/docs/ru/api/messages) (включая потоковую передачу и подсчёт токенов), [Models](https://platform.claude.com/docs/ru/api/models/list), [Managed Agents](https://platform.claude.com/docs/ru/managed-agents/overview) и их сессиям, [Files](https://platform.claude.com/docs/ru/build-with-claude/files) и [Skills](https://platform.claude.com/docs/ru/build-with-claude/skills-guide). Это соответствует доступу, который имеет ключ API рабочего пространства в том же рабочем пространстве. | | `workspace:inference` | Эндпоинтам инференса в рабочем пространстве правила: [Messages](https://platform.claude.com/docs/ru/api/messages) (включая потоковую передачу и подсчёт токенов), [Models](https://platform.claude.com/docs/ru/api/models/list) и [OpenAI-совместимому эндпоинту чата](https://platform.claude.com/docs/ru/cli-sdks-libraries/libraries/openai-sdk). Используйте для рабочих нагрузок, которым нужно только вызывать Claude и никогда не требуется управлять Files, Skills или другими ресурсами. | | `workspace:manage_tunnels` | [API туннелей MCP](https://platform.claude.com/docs/ru/agents-and-tools/mcp-tunnels/reference#tunnels-api): создание, получение списка и получение туннелей, регистрация и архивирование сертификатов CA, раскрытие и ротация токена туннеля, а также архивирование туннелей. Модальное окно создания туннеля в Console фиксирует эту область, когда вы создаёте правило из него. | | `org:admin` | Полному доступу к [Admin API](https://platform.claude.com/docs/ru/manage-claude/admin-api) (участники организации, приглашения, рабочие пространства, ключи API и прочее). Токен OAuth с `org:admin` может создавать или изменять только правила с областью `workspace:developer` или `workspace:inference` и не может обновлять издателя, на котором основано правило с любой другой областью; см. [ограничения](https://platform.claude.com/docs/ru/manage-claude/wif-admin-api#permissions-and-constraints). | Запрос к эндпоинту вне области токена возвращает HTTP 403. Более детальные области (для отдельных ресурсов или с разделением на чтение и запись) в настоящее время недоступны. ### Границы разрешений `oauth_scope` правила федерации является верхним пределом: выпущенный токен никогда не может его превысить. `organization_role` целевого сервисного аккаунта (`developer` или `admin`) определяет, какие области можно предоставить, поэтому правило, предоставляющее `org:admin`, должно указывать на сервисный аккаунт с `organization_role=admin`. Эффективные разрешения — это пересечение области правила и роли сервисного аккаунта. | `oauth_scope` правила | `organization_role` сервисного аккаунта | Эффективные разрешения | | --------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace:developer` | `admin` | Доступ к Claude API только в рабочем пространстве правила. Область ограничивает токен ниже уровня роли. | | `org:admin` | `admin` | Полный доступ к Admin API (участники организации, приглашения, рабочие пространства, ключи API и прочее), за исключением ограничений для вызывающих через OAuth; см. [ограничения](https://platform.claude.com/docs/ru/manage-claude/wif-admin-api#permissions-and-constraints). | ## Правила валидации Anthropic применяет эти ограничения при создании или обновлении издателей и правил, а также при проверке входящего JWT в момент обмена. Полные сведения о параметрах и схемах ответов см. в [справочнике API сервисных аккаунтов](https://platform.claude.com/docs/ru/api/organization/service_accounts), [справочнике API издателей федерации](https://platform.claude.com/docs/ru/api/organization/federation/issuers) и [справочнике API правил федерации](https://platform.claude.com/docs/ru/api/organization/federation/rules). ### Поля ресурсов | Поле | Ограничение | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` издателя, правила и сервисного аккаунта | Должно соответствовать `^[a-z0-9-]+$`, длина от 1 до 255 символов. | | `workspace_id` | Обязательно при создании, если `applies_to_all_workspaces` не равно true. Рабочее пространство (`wrkspc_...`), квота, биллинг и ограничения скорости которого применяются к токенам, выпущенным по этому правилу. Должно быть рабочим пространством в той же организации, а целевой сервисный аккаунт должен быть участником этого рабочего пространства. | | `applies_to_all_workspaces` | Boolean. Установите `true`, чтобы включить правило во всех рабочих пространствах организации вместо указания одного; при создании обязательно либо это поле, либо `workspace_id`. | | `token_lifetime_seconds` | Целое число от `60` до `86400` (от 1 минуты до 24 часов). По умолчанию `3600`. Значения вне этого диапазона отклоняются во время запроса. См. [Время жизни и обновление токена](https://platform.claude.com/docs/ru/manage-claude/workload-identity-federation#token-lifetime-and-refresh). | ### Поля URL Поля `issuer_url`, `jwks.discovery_base` и `jwks.url` проходят валидацию: | Ограничение | Подробности | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Схема | Должна быть `https`. | | Порт | Должен быть `443` (явно или по умолчанию). | | Хост | Должен быть публичным DNS-именем хоста вашего провайдера OIDC. Должен разрешаться в публичные IP-адреса; IP-литералы не принимаются. | Ошибки валидации URL возвращают `400 invalid_request_error` с именем поля в качестве префикса сообщения об ошибке (например, `issuer_url: url must use https scheme`). Ограничения URL применяются только к URL, к которым подключается Anthropic. В режимах JWKS `explicit_url` и `inline`, а также в режиме `discovery`, когда задан `jwks.discovery_base`, `issuer_url` сравнивается с утверждением JWT `iss` как строка и никогда не запрашивается, поэтому он может ссылаться на внутреннее имя хоста или нестандартный порт. ### Проверка JWT | Ограничение | Подробности | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Максимальный размер | JWT в `assertion` должен быть не более 16 КиБ. | | Алгоритм подписи | Принимаются только асимметричные алгоритмы (семейства RSA и ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512). HMAC (`HS256`, `HS384`, `HS512`) и `none` отклоняются. | | ID ключа | Заголовок JWT должен содержать `kid`, совпадающий с ключом в JWKS издателя. Токены без `kid` отклоняются. | | Обязательные утверждения | `sub` должно присутствовать. `iat` должно присутствовать и не находиться в будущем. `exp` должно присутствовать и находиться в будущем. | | Однократное использование | Утверждение (assertion), содержащее claim `jti`, можно обменять только один раз для каждого издателя: повторный обмен с тем же `jti` отклоняется как повторное воспроизведение (replay). Поле издателя `check_jti` (включено по умолчанию) управляет этой проверкой; утверждения без claim `jti` ей не подлежат. См. [справочник API издателей федерации](https://platform.claude.com/docs/ru/api/organization/federation/issuers). | | Максимальное время жизни | Время жизни токена (`exp` минус `iat`) не должно превышать настроенный для издателя максимум (по умолчанию 1 час, настраивается для каждого издателя в Claude Console). | | Расхождение часов | К `exp`, `nbf` и `iat` применяется допуск в 30 секунд. | ## Семантика сопоставления правил Блок `match` правила федерации определяет, принимается ли входящий JWT. Все заполненные поля оцениваются с семантикой AND: JWT должен удовлетворять каждому заполненному сопоставителю. Должно быть задано хотя бы одно из `subject_prefix`, `claims` или `condition`; блок `match`, содержащий только `audience` (или вообще без сопоставителей), отклоняется. Это защищает от правил, которые принимали бы любой токен от издателя. | Сопоставитель | Тип | Семантика | | ---------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `subject_prefix` | string | Точное совпадение с утверждением JWT `sub`. Завершающий `*` превращает его в сопоставление по префиксу (значение `sub` должно начинаться с символов перед `*`). С учётом регистра. | | `audience` | string | Утверждение JWT `aud` должно содержать именно эту строку. Если `aud` является массивом, проверка выполняется при точном совпадении любого элемента. | | `claims` | map\ | Каждый ключ — это имя утверждения верхнего уровня, а каждое значение — требуемое точное строковое значение. Для вложенных, числовых, логических или сложных утверждений, таких как списки и словари, используйте вместо этого `condition` с выражением CEL. | | `condition` | string (CEL) | Выражение [CEL](https://cel.dev/), которое должно вычисляться в `true`. | ### Среда вычисления CEL Выражение `condition` имеет доступ к одной переменной: | Переменная | Тип | Содержимое | | ---------- | --- | ---------------------------------------------------------------------------------------------- | | `claims` | map | Полный декодированный набор утверждений JWT. Вложенные объекты доступны как вложенные словари. | Пример: ```text wrap claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"] ``` Условия CEL являются границами безопасности. Выражение, которое вычисляется в `true` для большего числа входных данных, чем предполагалось, предоставляет более широкий доступ, чем предполагалось. Отдавайте предпочтение статическим сопоставителям, когда они выражают ваше ограничение. ## Ошибки ### Ошибки обмена токена `POST /v1/oauth/token` возвращает ошибки в стандартном [формате ошибок API](https://platform.claude.com/docs/ru/api/errors). SDK сообщает о сбое обмена как `WorkloadIdentityError` (ruby: `Anthropic::Credentials::WorkloadIdentityError`; go: `error`; java: `UnexpectedStatusCodeException`; csharp: `WorkloadIdentityException`; php: `OAuthException`), что предоставляет HTTP-статус и сведения об ошибке из тела ответа. ID запроса содержится в ошибке в Python, TypeScript и Ruby, а в Java — в заголовках ответа исключения. В Go он есть только в сообщении ошибки, поскольку тип ошибки находится во внутреннем пакете; ошибки C# и PHP его не содержат. | Статус | Ошибка | Причина | Решение | | ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_request_error` | `federation_rule_id` имеет неверный формат или отсутствует обязательное поле запроса. | Проверьте ID `fdrl_` и то, что тело запроса содержит все обязательные поля. | | 400 | `invalid_request_error` | `workspace_id` присутствует, но не является корректным ID `wrkspc_...` или литералом `default`. | Исправьте значение `workspace_id`; в сообщении ответа указан ожидаемый формат. | | 401 | `authentication_error` | Утверждение JWT `iss` не совпадает в точности с зарегистрированным `issuer_url`. | Сравните побайтово, включая завершающие слеши и схему: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`. | | 401 | `authentication_error` | Не удалось получить JWKS, JWKS устарел или JWT подписан ключом, которого нет в JWKS. | Для режима `inline` обновите издателя с ротированными ключами. Для `discovery` и `explicit_url` убедитесь, что эндпоинт JWKS доступен на порту 443; если издатель недавно ротировал ключ подписи, см. [Ротация ключей и кэширование](https://platform.claude.com/docs/ru/manage-claude/wif-reference#key-rotation-and-caching). | | 401 | `authentication_error` | Утверждение JWT `exp` находится в прошлом (за пределами 30-секундного окна расхождения). | Убедитесь, что ваш провайдер удостоверений проецирует свежий токен и что SDK перечитывает файл токена. | | 401 | `authentication_error` | JWT прошёл проверку, но его утверждения не удовлетворяют блоку `match` правила. | Декодируйте JWT и сравните каждое утверждение с правилом. `subject_prefix` учитывает регистр. `audience` требует точного совпадения элемента. | | 401 | `authentication_error` | `federation_rule_id` не существует, заархивирован или JWT не авторизован для него (объединено, чтобы предотвратить перебор). | Проверьте ID правила в Claude Console и убедитесь, что правило не заархивировано. | | 401 | `authentication_error` | Правило федерации включено более чем для одного рабочего пространства, а в запросе отсутствует `workspace_id`. Запись в истории аутентификации показывает причину `workspace_id_required`. | Задайте `ANTHROPIC_WORKSPACE_ID` (или поле тела `workspace_id` в необработанном запросе) равным ID `wrkspc_...`, которым должен ограничиваться токен. См. [Запрос на обмен токена](https://platform.claude.com/docs/ru/manage-claude/wif-reference#token-exchange-request). | Каждый отказ в утверждении возвращает одинаковую непрозрачную ошибку `401` `authentication_error` с фиксированным сообщением `Authentication failed`, независимо от того, какая проверка не пройдена; различимая ошибка позволила бы вызывающей стороне зондировать конфигурацию правил. Причина отказа записывается в запись о попытке в [истории аутентификации](https://platform.claude.com/settings/workload-identity-federation?tab=history) в Claude Console, например `match_subject_prefix`, когда утверждение `sub` не проходит `subject_prefix` правила, или `workspace_id_required`, когда правило охватывает несколько рабочих пространств, а в запросе ни одно не указано. Запросы, отклонённые до подтверждения организации правила (семейство `400 invalid_request_error` выше), не оставляют записи в истории; их сообщения ответа прямо указывают на проблему. Ошибка `401` без соответствующей записи в истории обычно означает, что сам `federation_rule_id` не был распознан. ### Распространённые сбои на стороне SDK | Симптом | Причина | Решение | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | SDK сообщает «no credentials» вместо выполнения обмена | Одна из переменных `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` или `ANTHROPIC_IDENTITY_TOKEN[_FILE]` не задана, и ни один профиль не активен. | Задайте все четыре переменные или настройте профиль. | | SDK аутентифицируется с ключом API вместо федерации | Задана `ANTHROPIC_API_KEY` или `ANTHROPIC_AUTH_TOKEN`, и она имеет приоритет. | Удалите переменную ключа или токена. | | `FileNotFoundError` при первом запросе | Путь в `ANTHROPIC_IDENTITY_TOKEN_FILE` не существует. SDK открывает файл отложенно, в момент обмена. | Убедитесь, что том с проецируемым токеном смонтирован и путь совпадает. | | Обмен токена успешен, но запрос к Claude API возвращает 403 | Область выпущенного токена не предоставляет доступ к этому эндпоинту. | Сверьте `oauth_scope` правила с разделом [Области OAuth](https://platform.claude.com/docs/ru/manage-claude/wif-reference#oauth-scopes). | | Аутентификация не проходит с пустыми учётными данными | Переменная окружения учётных данных экспортирована, но ей присвоена пустая строка. Пустые значения иногда всё равно занимают свою позицию в порядке приоритета. | Удалите переменную с помощью `unset VAR`, а не `VAR=""`. | ## Устранение неполадок при неудачном обмене Ответ `401` `authentication_error` намеренно непрозрачен, и его сообщение всегда `Authentication failed`; причина отказа записывается в историю аутентификации, а не в ответ. Начните со [страницы истории аутентификации](https://platform.claude.com/settings/workload-identity-federation?tab=history) в Claude Console. Недавние попытки обмена показывают проверенных издателя и правило, проанализированные утверждения JWT и то, какой шаг валидации не пройден, что обычно позволяет пропустить следующие проверки. Один из распространённых непрозрачных сбоев — повторно воспроизведённое утверждение: утверждение, содержащее claim `jti`, можно [обменять только один раз](https://platform.claude.com/docs/ru/manage-claude/wif-reference#jwt-verification), поэтому рабочая нагрузка, которая повторно отправляет тот же JWT (цикл повторных попыток или обновление, перечитывающее неротированный токен), отклоняется при втором обмене. Страница истории аутентификации показывает такие попытки с причиной `jti_reused`; решение — выпускать новое утверждение для каждого обмена. Если вам всё же нужно выполнить отладку по самому JWT, выполните следующие проверки по порядку: Декодируйте отправленное утверждение, чтобы сравнить каждое утверждение с конфигурацией издателя и правила: ```bash cURL jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT" ``` Декодированное утверждение `iss` должно побайтово совпадать с зарегистрированным `issuer_url`, включая схему, порт и любой завершающий слеш. Несовпадение даже в одном символе приводит к сбою проверки. Декодированное утверждение `aud` должно содержать значение `audience` правила в точном совпадении. Если `aud` является массивом, один элемент должен совпадать точно. Сравните `sub` с `subject_prefix` правила (с учётом регистра; завершающий `*` означает сопоставление по префиксу, всё остальное — точное совпадение). Сравните каждый ключ в словаре `claims` правила с одноимённым утверждением верхнего уровня. `exp` должно находиться в будущем, а `nbf`/`iat` — в прошлом, в пределах 30-секундного окна расхождения. Если часы хоста рабочей нагрузки сбились, в остальном корректный токен будет отклонён. Для режима `discovery` запросите `/.well-known/openid-configuration` по публичному HTTPS на порту 443 и убедитесь, что `jwks_uri` разрешается. Для `explicit_url` запросите URL JWKS напрямую. Для `inline` убедитесь, что ключ подписи издателя не был ротирован с момента регистрации ключей. Если издатель ротировал ключ подписи и сразу начал подписывать им, обмены могут завершаться сбоем в течение до одной минуты, пока обновляется кэш JWKS Anthropic. См. [Ротация ключей и кэширование](https://platform.claude.com/docs/ru/manage-claude/wif-reference#key-rotation-and-caching). ## Режимы источника JWKS При регистрации издателя федерации поле `jwks` определяет, как Anthropic получает открытые ключи, используемые для проверки подписей JWT от этого издателя. Это размеченное объединение (discriminated union) с ключом `type`: | `jwks.type` | Форма `jwks` | Поведение | Когда использовать | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `discovery` (по умолчанию) | `{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` необязателен; задайте его, если URL обнаружения отличается от `issuer_url`) | Anthropic запрашивает `/.well-known/openid-configuration`, считывает `jwks_uri` из документа обнаружения и получает JWKS оттуда. | Ваш IdP предоставляет стандартный документ обнаружения OIDC в публичном интернете. Большинство управляемых провайдеров (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) это поддерживают. | | `explicit_url` | `{ "type": "explicit_url", "url": "https://..." }` | Anthropic получает JWKS напрямую из `url`. `issuer_url` используется только для строкового сравнения с утверждением JWT `iss` и никогда не запрашивается. | Ваш IdP не предоставляет документ обнаружения, или обнаружение доступно только внутри сети, но JWKS доступен публично. | | `inline` | `{ "type": "inline", "keys": [...] }` | Вы передаёте массив объектов JWK встроенно (массив `keys` из документа JWKS, а не объект-обёртку). Anthropic не выполняет исходящих запросов. `issuer_url` используется только для сравнения `iss`. | Изолированные (air-gapped) окружения, самостоятельно управляемые кластеры Kubernetes с внутрикластерными URL издателя или когда вам нужен явный контроль над ротацией ключей. | Размеченное объединение по своей конструкции делает сопутствующие поля взаимоисключающими. И `discovery`, и `explicit_url` также принимают необязательную строку `ca_cert_pem` для издателей, которые обслуживают TLS с помощью частного CA. ### Ротация ключей и кэширование В режимах `discovery` и `explicit_url` Anthropic кэширует полученный JWKS. Если ваш провайдер удостоверений публикует новый ключ подписи и сразу начинает подписывать им токены, обмены с такими токенами могут завершаться ошибкой подписи в течение до 1 минуты, пока обновляется кэш. Чтобы избежать этого окна, публикуйте новый ключ подписи в JWKS как минимум за 15 минут до того, как ваш провайдер удостоверений начнёт подписывать им токены, и сохраняйте заменённый ключ в JWKS, пока не истечёт срок действия подписанных им токенов. Управляемые провайдеры удостоверений обычно сами соблюдают эту практику. Если вы управляете собственным издателем (самостоятельно управляемый кластер Kubernetes, провайдер обнаружения SPIRE OIDC или пользовательский сервер авторизации Okta с настроенной периодичностью ротации), убедитесь, что ваша политика ротации публикует новые ключи заранее, до их первого использования. В режиме `inline` автоматическое обновление ключей отсутствует. Когда ваш провайдер удостоверений ротирует ключи подписи, вы должны обновить конфигурацию издателя новым JWKS, иначе все обмены токенов не пройдут проверку подписи.