--- 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 читает эти переменные для выполнения федеративного обмена токенами без аргументов конструктора. | Переменная | Обязательная | Описание | Пример | | ------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `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, выданному вашим провайдером идентификации (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` читается наряду с ними, но не управляет активацией. Переменная, установленная в пустую строку, всё равно занимает свой слот в цепочке приоритета учётных данных. Если экспортирована `ANTHROPIC_API_KEY=""`, SDK выбирает путь ключа API с пустым ключом, а не переходит к федерации. Сбрасывайте неиспользуемые переменные учётных данных, а не обнуляйте их. ### Приоритет учётных данных 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` | Булево значение. Установите `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` должно присутствовать и находиться в будущем. | | Однократное использование | Утверждение, содержащее утверждение `jti`, может быть обменено только один раз для каждого эмитента: повторный обмен с тем же `jti` отклоняется как повтор. Поле эмитента `check_jti` (включено по умолчанию) управляет этой проверкой; утверждения без `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` имеет неправильный формат или отсутствует обязательное поле запроса. | Проверьте `fdrl_` ID и то, что тело запроса включает все обязательные поля. | | 400 | `invalid_request_error` | `workspace_id` присутствует, но не является корректно сформированным `wrkspc_...` ID или литералом `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` в необработанном запросе) в `wrkspc_...` ID, к которому вы хотите привязать токен. См. [Запрос обмена токенами](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, которые были проверены, и какой шаг валидации не удался, что обычно сокращает следующие проверки. Один распространённый непрозрачный сбой — это повторённое утверждение: утверждение, несущее утверждение `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 от этого эмитента. Это дискриминированное объединение с ключом по `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`. | Изолированные окружения, самоуправляемые кластеры 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, иначе все обмены токенами не пройдут проверку подписи.