---
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) (WIF). Пошаговые инструкции по настройке см. в разделе [Поставщики удостоверений](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).

| Поле                 | Обязательное | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `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>`. |
| `token_type`   | string  | Всегда `Bearer`.                                                                                                   |
| `expires_in`   | integer | Количество секунд до истечения срока действия токена.                                                              |
| `scope`        | string  | Область OAuth, предоставленная совпавшим правилом.                                                                 |

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

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

| Переменная                      | Обязательная                       | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Пример                                 |
| ------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `ANTHROPIC_FEDERATION_RULE_ID`  | Да                                 | Тегированный ID правила федерации, которое нужно проверить.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `fdrl_...`                             |
| `ANTHROPIC_ORGANIZATION_ID`     | Да                                 | UUID вашей организации Anthropic. Его можно найти на странице [Организация](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 рабочего пространства, которым ограничивается выпущенный токен. Обязателен, если правило федерации включено более чем для одного рабочего пространства. Необязателен, если правило привязано к одному рабочему пространству. Обмен ограничивает выпущенный токен этим рабочим пространством, поэтому для смены рабочего пространства требуется новый обмен. Без профиля CLI `ant` не передаёт эту переменную в обмен. При использовании CLI `ant` задайте `workspace_id` в профиле федерации и присвойте `ANTHROPIC_PROFILE` его имя. Литерал `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`. SDK также считывает `ANTHROPIC_WORKSPACE_ID`, но этот путь активируется независимо от её наличия.

<Warning>
  Переменная, которой присвоена пустая строка, может занимать свою позицию в цепочке приоритета учётных данных. Удаляйте неиспользуемые переменные учётных данных с помощью unset, а не присваивайте им пустые значения.
</Warning>

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

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

| Порядок | Источник                                                                  | Примечания                                                                                                                                         |
| ------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1       | Аргумент конструктора (ключ API, токен аутентификации или учётные данные) | Всегда переопределяет всё остальное.                                                                                                               |
| 2       | `ANTHROPIC_API_KEY` или `ANTHROPIC_AUTH_TOKEN`                            | Полностью переопределяет федерацию. Удалите эти переменные при переходе с ключей API.                                                              |
| 3       | `ANTHROPIC_PROFILE`                                                       | Загружает `<config_dir>/configs/<name>.json`. Если именованный профиль отсутствует, SDK сообщает об ошибке, а не переходит к следующему источнику. |
| 4       | Переменные окружения федерации                                            | `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`.                 |
| 5       | Активный профиль                                                          | Определяется из `<config_dir>/active_config`, с откатом к профилю с именем `default`.                                                              |

В `ant` CLI настройки для [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ru/build-with-claude/claude-models-on-google-cloud/anthropic-managed#authentication) имеют приоритет ниже переменных окружения федерации и выше активного профиля. К этим настройкам относятся проект, идентификатор рабочего пространства и расположение. Они задаются с помощью флагов `--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 соблюдают тот же порядок определения, поэтому настроенный здесь профиль федерации также аутентифицирует эти инструменты без дополнительной настройки.

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

| Путь                                      | Содержимое                                                                                         | Конфиденциальность                                             |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `<config_dir>/configs/<profile>.json`     | `version`, блок `authentication`, `organization_id`, `workspace_id` и `base_url`.                  | Не секретно. Можно безопасно коммитить или встраивать в образ. |
| `<config_dir>/credentials/<profile>.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 и никогда не требуется управлять файлами, навыками или другими ресурсами.                                                                                                             |
| `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`. Anthropic отклоняет значения вне этого диапазона во время запроса. См. [Время жизни и обновление токена](https://platform.claude.com/docs/ru/manage-claude/workload-identity-federation#token-lifetime-and-refresh).                                                       |

### Поля URL

Anthropic выполняет валидацию полей `issuer_url`, `jwks.discovery_base` и `jwks.url`:

| Ограничение | Подробности                                                                                                                                  |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Схема       | Должна быть `https`.                                                                                                                         |
| Порт        | Должен быть `443` (явно или по умолчанию).                                                                                                   |
| Хост        | Должен быть публичным DNS-именем хоста вашего провайдера OIDC. Должен разрешаться в публичные IP-адреса. Anthropic не принимает IP-литералы. |

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

<Note>
  Ограничения URL применяются только к URL, к которым подключается Anthropic. Anthropic никогда не запрашивает `issuer_url` в режимах `explicit_url` и `inline` «JSON Web Key Set» (набора веб-ключей JSON), или JWKS, а также в режиме `discovery`, когда задан `jwks.discovery_base`. Anthropic лишь сравнивает этот URL с утверждением JWT `iss` как строку, поэтому URL может ссылаться на внутреннее имя хоста или нестандартный порт.
</Note>

### Проверка JWT

| Ограничение               | Подробности                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Максимальный размер       | JWT в `assertion` должен быть не более 16 КиБ.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Алгоритм подписи          | Anthropic принимает только асимметричные алгоритмы (семейства RSA и ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512). HMAC (`HS256`, `HS384`, `HS512`) и `none` отклоняются.                                                                                                                                                                                                                                                                       |
| ID ключа                  | Заголовок JWT должен содержать `kid`, совпадающий с ключом в JWKS издателя. Anthropic отклоняет токены без `kid`.                                                                                                                                                                                                                                                                                                                                                       |
| Обязательные утверждения  | `sub` должно присутствовать. `iat` должно присутствовать и не находиться в будущем. `exp` должно присутствовать и находиться в будущем.                                                                                                                                                                                                                                                                                                                                 |
| Однократное использование | Утверждение (assertion), содержащее утверждение (claim) `jti`, можно обменять только один раз для каждого издателя. Anthropic отклоняет повторный обмен с тем же `jti` как повторное воспроизведение (replay). Поле издателя `check_jti` (включено по умолчанию) управляет этой проверкой. Утверждения без утверждения (claim) `jti` ей не подлежат. См. [справочник API издателей федерации](https://platform.claude.com/docs/ru/api/organization/federation/issuers). |
| Максимальное время жизни  | Время жизни токена (`exp` минус `iat`) не должно превышать настроенный для издателя максимум (по умолчанию 1 час, настраивается для каждого издателя в Claude Console).                                                                                                                                                                                                                                                                                                 |
| Расхождение часов         | Anthropic применяет допуск в 30 секунд к `exp`, `nbf` и `iat`.                                                                                                                                                                                                                                                                                                                                                                                                          |

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

Блок `match` правила федерации определяет, принимает ли Anthropic входящий JWT. JWT должен удовлетворять каждому заполненному сопоставителю. Задайте хотя бы одно из `subject_prefix`, `claims` или `condition`. Anthropic отклоняет блок `match`, содержащий только `audience` или вообще без сопоставителей. Это защищает от правил, которые принимали бы любой токен от издателя.

| Сопоставитель    | Тип                  | Семантика                                                                                                                                                                                                                                                                                                              |
| ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subject_prefix` | string               | Точное совпадение с утверждением `sub` JWT. Завершающий `*` превращает его в сопоставление по префиксу (значение `sub` должно начинаться с символов перед `*`). С учётом регистра.                                                                                                                                     |
| `audience`       | string               | Утверждение JWT `aud` должно содержать именно эту строку. Если `aud` является массивом, проверка выполняется при точном совпадении любого элемента.                                                                                                                                                                    |
| `claims`         | map\<string, string> | Каждый ключ — это имя утверждения верхнего уровня, а каждое значение — требуемое точное строковое значение. Для вложенных, числовых, логических или сложных утверждений, таких как списки и карты, вместо этого используйте `condition` с выражением на «Common Expression Language» (языке общих выражений), или 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"]
```

<Warning>
  Условия CEL являются границами безопасности. Выражение, которое вычисляется в `true` для большего числа входных данных, чем предполагалось, предоставляет более широкий доступ, чем предполагалось. Отдавайте предпочтение статическим сопоставителям, когда они выражают ваше ограничение.
</Warning>

## Ошибки

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

`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-статус и сведения об ошибке из тела ответа. За исключением C# и PHP, SDK также предоставляет ID запроса: в ошибке, в заголовках ответа исключения или в сообщении ошибки.

| Статус | Ошибка                  | Причина                                                                                                                                                                                    | Решение                                                                                                                                                                                                                                                                                                                                                                                     |
| ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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_...`, которым должен ограничиваться токен. При использовании CLI `ant` задайте `workspace_id` в профиле федерации и присвойте `ANTHROPIC_PROFILE` его имя. См. [Запрос на обмен токена](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` без соответствующей записи в истории обычно означает, что Anthropic не распознал `federation_rule_id`.

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

| Симптом                                                            | Причина                                                                                                                                                                                       | Решение                                                                                                                                 |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| SDK сообщает об отсутствии учётных данных вместо выполнения обмена | Одна из переменных `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, `ANTHROPIC_SERVICE_ACCOUNT_ID` или `ANTHROPIC_IDENTITY_TOKEN[_FILE]` не задана, и ни один профиль не активен. | Задайте все четыре переменные или настройте профиль.                                                                                    |
| SDK аутентифицируется с ключом API вместо федерации                | Задана `ANTHROPIC_API_KEY` или `ANTHROPIC_AUTH_TOKEN`, и она имеет приоритет.                                                                                                                 | Удалите переменную ключа или токена.                                                                                                    |
| Ошибка «файл не найден» при первом запросе                         | Путь в `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`. Причина отказа отображается в истории аутентификации, а не в ответе.

<Tip>
  Начните со [страницы истории аутентификации](https://platform.claude.com/settings/workload-identity-federation?tab=history) в Claude Console. Недавние попытки обмена показывают издателя и правило, которые проверил Anthropic, исследованные им утверждения JWT и то, какой шаг валидации не прошёл. Эта информация обычно делает следующие проверки ненужными.
</Tip>

Один из распространённых непрозрачных сбоев — повторно воспроизведённое утверждение. Утверждение, содержащее утверждение (claim) `jti`, можно [обменять только один раз](https://platform.claude.com/docs/ru/manage-claude/wif-reference#jwt-verification). Рабочая нагрузка, которая повторно отправляет тот же JWT (цикл повторных попыток или обновление, перечитывающее неротированный токен), завершается сбоем при втором обмене. Страница истории аутентификации показывает такие попытки с причиной `jti_reused`. Чтобы исправить это, выпускайте новое утверждение для каждого обмена.

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

<Steps>
  <Step title="Декодируйте JWT">
    Декодируйте отправленное утверждение, чтобы сравнить каждое утверждение с конфигурацией издателя и правила:

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

  <Step title="Проверьте, что iss совпадает с издателем">
    Декодированное утверждение `iss` должно побайтово совпадать с зарегистрированным `issuer_url`, включая схему, порт и любой завершающий слеш. Несовпадение даже в одном символе приводит к сбою проверки.
  </Step>

  <Step title="Проверьте, что aud совпадает с правилом">
    Декодированное утверждение `aud` должно содержать значение `audience` правила в точном совпадении. Если `aud` является массивом, один элемент должен совпадать точно.
  </Step>

  <Step title="Проверьте sub и каждую запись claims">
    Сравните `sub` с `subject_prefix` правила. Сравнение выполняется с учётом регистра. Завершающий `*` превращает его в сопоставление по префиксу, а в остальных случаях требуется точное совпадение. Сравните каждый ключ в карте `claims` правила с одноимённым утверждением верхнего уровня.
  </Step>

  <Step title="Проверьте exp, nbf и iat">
    `exp` должно находиться в будущем, а `nbf`/`iat` — в прошлом, в пределах 30-секундного окна расхождения. Если часы хоста рабочей нагрузки сбились, Anthropic отклоняет в остальном корректный токен.
  </Step>

  <Step title="Проверьте доступность JWKS">
    Для режима `discovery` запросите `<jwks.discovery_base or issuer_url>/.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).
  </Step>
</Steps>

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

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

| `jwks.type`                | Форма `jwks`                                                                                                                                          | Поведение                                                                                                                                                                                                   | Когда использовать                                                                                                                                                                       |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `discovery` (по умолчанию) | `{ "type": "discovery", "discovery_base": "https://..." }` (задайте необязательный `discovery_base`, если URL обнаружения отличается от `issuer_url`) | Anthropic запрашивает `<discovery_base or issuer_url>/.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`. Anthropic использует `issuer_url` только для строкового сравнения с утверждением JWT `iss` и никогда к нему не подключается.                                     | Ваш IdP не предоставляет документ обнаружения, или обнаружение доступно только внутри сети, но JWKS доступен публично.                                                                   |
| `inline`                   | `{ "type": "inline", "keys": [...] }`                                                                                                                 | Вы передаёте массив объектов JWK встроенно (массив `keys` из документа JWKS, а не объект-обёртку). Anthropic не выполняет исходящих запросов. Anthropic использует `issuer_url` только для сравнения `iss`. | Изолированные (air-gapped) окружения, самостоятельно управляемые кластеры Kubernetes с внутрикластерными URL издателя или когда вам нужен явный контроль над ротацией ключей.            |

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

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

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

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

<Warning>
  В режиме `inline` автоматическое обновление ключей отсутствует. Когда ваш провайдер удостоверений ротирует ключи подписи, вы должны обновить конфигурацию издателя новым JWKS, иначе все обмены токенов не проходят проверку подписи.
</Warning>
