АдминистрированиеАутентификация

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

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

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

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

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

Поле	Обязательное	Описание
`grant_type`	Да	Всегда `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Да	OIDC JWT, выданный вашим провайдером идентификации.
`federation_rule_id`	Да	Тегированный идентификатор (`fdrl_...`) правила федерации, которое нужно применить.
`organization_id`	Да	UUID вашей организации Anthropic.
`service_account_id`	Да	Тегированный идентификатор (`svac_...`) целевой сервисной учётной записи.
`workspace_id`	Условно	Тегированный идентификатор (`wrkspc_...`) рабочего пространства, которым будет ограничен выпущенный токен, или литерал `default` для рабочего пространства организации по умолчанию. Обязателен, если правило включено более чем для одного рабочего пространства. Если опущен, сервер выбирает единственное включённое рабочее пространство правила.

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

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

Поле	Тип	Описание
`access_token`	string	Короткоживущий токен Anthropic с префиксом `sk-ant-oat01-...`. Передавайте его как `Authorization: Bearer <token>`.
`token_type`	string	Всегда `Bearer`.
`expires_in`	integer	Количество секунд до истечения срока действия токена.
`scope`	string	Область действия OAuth, предоставленная сработавшим правилом.

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

SDK считывает эти переменные для выполнения федеративного обмена токена без аргументов конструктора.

Переменная	Обязательная	Описание	Пример
`ANTHROPIC_FEDERATION_RULE_ID`	Да	Тегированный идентификатор правила федерации, которое нужно применить.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	Да	UUID вашей организации Anthropic. Найдите его в Claude Console в разделе Settings > Organization.	`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`	Да	Тегированный идентификатор целевой сервисной учётной записи Anthropic, от имени которой действует выпущенный токен доступа.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Условно	Тегированный идентификатор рабочего пространства, которым будет ограничен выпущенный токен, или литерал `default`. Обязательна, если правило федерации включено более чем для одного рабочего пространства; необязательна, если правило привязано к единственному рабочему пространству. Выпущенный токен ограничивается этим рабочим пространством в момент обмена, поэтому для переключения рабочих пространств требуется новый обмен.	`wrkspc_...`
`ANTHROPIC_PROFILE`	Нет	Имя профиля конфигурации для загрузки. Имеет приоритет над переменными окружения федерации из этой таблицы.	`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`	Загружает `<config_dir>/configs/<name>.json`. Отсутствующий именованный профиль — это ошибка, а не переход к следующему источнику.
4	Переменные окружения федерации	`ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` + `ANTHROPIC_SERVICE_ACCOUNT_ID` + `ANTHROPIC_IDENTITY_TOKEN[_FILE]`.
5	Активный профиль	Определяется из `<config_dir>/active_config`, с откатом к профилю с именем `default`.

Когда профиль загружен, переменные окружения заполняют любые поля, которые профиль опускает, но никогда не переопределяют поля, которые профиль задаёт явно. Например, ANTHROPIC_WORKSPACE_ID заполняет workspace_id только тогда, когда активный профиль его не задаёт.

Файл конфигурации профиля

Профиль — это именованный файл конфигурации, который читают как SDK, так и CLI ant. Профили позволяют поставлять параметры федерации вместе с образом контейнера или переключаться между окружениями без изменения кода.

Каталог конфигурации

SDK находит каталог конфигурации в следующем порядке:

$ANTHROPIC_CONFIG_DIR
~/.config/anthropic в Linux и macOS
%APPDATA%\Anthropic в Windows

Активный профиль

Имя активного профиля определяется в следующем порядке:

$ANTHROPIC_PROFILE
Содержимое <config_dir>/active_config (однострочный файл, записываемый командой ant profile activate <name>)
Литеральное имя 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 будет считать файл текущей версией.

Пример профиля федерации

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 (включая потоковую передачу и подсчёт токенов), Models, Managed Agents и их сессии, Files и Skills. Это соответствует доступу, который имеет ключ API, выпущенный для того же рабочего пространства.

org:manage_tunnels API туннелей MCP: получение списка и отдельных туннелей, регистрация и архивирование CA-сертификатов, раскрытие и ротация токена туннеля, а также архивирование туннелей. Модальное окно создания туннеля в Console фиксирует эту область действия при создании правила из него.

Область действия	Предоставляет доступ к
`workspace:developer`	Все неадминистративные конечные точки Claude API в рабочем пространстве правила: Messages (включая потоковую передачу и подсчёт токенов), Models, Managed Agents и их сессии, Files и Skills. Это соответствует доступу, который имеет ключ API, выпущенный для того же рабочего пространства.
`org:manage_tunnels`	API туннелей MCP: получение списка и отдельных туннелей, регистрация и архивирование CA-сертификатов, раскрытие и ротация токена туннеля, а также архивирование туннелей. Модальное окно создания туннеля в Console фиксирует эту область действия при создании правила из него.

Запрос к конечной точке за пределами области действия токена возвращает HTTP 403. Более детальные области действия (по ресурсам или разделение на чтение и запись) в настоящее время недоступны.

Правила валидации

Anthropic применяет эти ограничения при создании или обновлении эмитентов и правил, а также при проверке входящего JWT в момент обмена.

Поля ресурсов

Поле	Ограничение
`name` эмитента, правила и сервисной учётной записи	Должно соответствовать `^[a-z0-9-]+$`, длина от 1 до 255 символов.
`workspace_id`	Необязательно. Рабочее пространство (`wrkspc_...`), чьи квоты, биллинг и ограничения скорости применяются к токенам, выпущенным по этому правилу. Должно быть рабочим пространством в той же организации, а целевая сервисная учётная запись должна быть членом этого рабочего пространства. Может быть опущено для правил, настроенных только для одного рабочего пространства.
`token_lifetime_seconds`	Целое число от `60` до `86400` (от 1 минуты до 24 часов). По умолчанию `3600`. Значения вне этого диапазона отклоняются во время запроса. См. Время жизни токена и обновление.

Поля 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 сравнивается с утверждением iss JWT как строка и никогда не запрашивается, поэтому оно может ссылаться на внутреннее имя хоста или нестандартный порт.

Проверка JWT

Ограничение	Подробности
Максимальный размер	JWT в `assertion` должен быть не более 16 КиБ.
Алгоритм подписи	Принимаются только асимметричные алгоритмы (семейства RSA и ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512). HMAC (`HS256`, `HS384`, `HS512`) и `none` отклоняются.
Идентификатор ключа	Заголовок JWT должен содержать `kid`, соответствующий ключу в JWKS эмитента. Токены без `kid` отклоняются.
Обязательные утверждения	`sub` должно присутствовать. `iat` должно присутствовать и не быть в будущем. `exp` должно присутствовать и быть в будущем.
Максимальное время жизни	Время жизни токена (`exp` минус `iat`) не должно превышать настроенный максимум эмитента (1 час по умолчанию, настраивается для каждого эмитента в Claude Console).
Расхождение часов	К `exp`, `nbf` и `iat` применяется допуск в 30 секунд.

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

Блок match правила федерации определяет, принимается ли входящий JWT. Все заполненные поля оцениваются с семантикой AND: JWT должен удовлетворять каждому заполненному сопоставителю. Должно быть задано хотя бы одно из subject_prefix, claims или condition; блок match, содержащий только audience (или вообще без сопоставителей), отклоняется. Это защищает от правил, которые принимали бы любой токен от эмитента.

Сопоставитель	Тип	Семантика
`subject_prefix`	string	Точное совпадение с утверждением `sub` JWT. Завершающий `` делает его префиксным совпадением (значение `sub` должно начинаться с символов перед ``). Чувствительно к регистру.
`audience`	string	Утверждение `aud` JWT должно содержать эту точную строку. Если `aud` — массив, проверку удовлетворяет любой элемент, совпадающий точно.
`claims`	map<string, string>	Каждый ключ — это имя утверждения верхнего уровня, а каждое значение — требуемое точное строковое значение. Для вложенных, числовых, булевых или сложных утверждений, таких как списки и карты, используйте `condition` с CEL-выражением.
`condition`	string (CEL)	Выражение CEL, которое должно вычисляться в `true`.

Среда выполнения CEL

Выражение condition имеет доступ к единственной переменной:

Переменная	Тип	Содержимое
`claims`	map	Полный декодированный набор утверждений JWT. Вложенные объекты доступны как вложенные карты.

Пример:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

CEL-условия являются границами безопасности. Выражение, которое вычисляется в true для большего числа входных данных, чем предполагалось, предоставляет более широкий доступ, чем предполагалось. Предпочитайте статические сопоставители, когда они выражают ваше ограничение.

Ошибки

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

POST /v1/oauth/token возвращает ошибки в стандартной форме ошибок API. SDK оборачивает сбои обмена в типизированную ошибку FederationExchangeError (или эквивалент для конкретного языка), которая предоставляет HTTP-статус, тело ответа и request_id.

Статус	Ошибка	Причина	Решение
400	`invalid_request`	`federation_rule_id` имеет неверный формат или отсутствует обязательное поле запроса.	Проверьте идентификатор `fdrl_` и убедитесь, что тело запроса включает все обязательные поля.
400	`invalid_request`	`workspace_id_required`: правило федерации включено более чем для одного рабочего пространства, а в запросе опущен `workspace_id`.	Задайте `ANTHROPIC_WORKSPACE_ID` (или поле `workspace_id` в теле необработанного запроса) равным идентификатору `wrkspc_...`, которым вы хотите ограничить токен. См. Запрос на обмен токена.
400	`invalid_grant`	Утверждение `iss` JWT не совпадает точно с зарегистрированным `issuer_url`.	Сравните побайтово, включая завершающие слэши и схему: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`.
400	`invalid_grant`	Не удалось получить JWKS, JWKS устарел или JWT подписан ключом, отсутствующим в JWKS.	Для режима `inline` обновите эмитент с ротированными ключами. Для `discovery` и `explicit_url` убедитесь, что конечная точка JWKS доступна на порту 443; если эмитент недавно ротировал свой ключ подписи, см. Ротация ключей и кэширование.
400	`invalid_grant`	Утверждение `exp` JWT находится в прошлом (за пределами 30-секундного окна допуска).	Убедитесь, что ваш провайдер идентификации проецирует свежий токен и что SDK перечитывает файл токена.
400	`invalid_grant`	JWT был проверен, но его утверждения не удовлетворяют блоку `match` правила.	Декодируйте JWT и сравните каждое утверждение с правилом. `subject_prefix` чувствителен к регистру. `audience` требует точного совпадения элемента.
400	`invalid_grant`	`federation_rule_id` не существует, архивирован или JWT не авторизован для него (объединено для предотвращения перебора).	Проверьте идентификатор правила в Claude Console и убедитесь, что правило не было архивировано.

Все сбои invalid_grant возвращают HTTP 400; конкретная причина логируется только на стороне сервера и не раскрывается в ответе.

Распространённые сбои на стороне 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.
Аутентификация завершается сбоем с пустыми учётными данными	Переменная окружения учётных данных экспортирована, но установлена в пустую строку. Пустые значения всё равно выигрывают свой слот приоритета.	Удалите переменную с помощью `unset VAR`, а не `VAR=""`.

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

Ответ 400 invalid_grant намеренно непрозрачен; конкретная причина логируется только на стороне сервера.

Начните со страницы истории аутентификации в Claude Console. Недавние попытки обмена показывают эмитент и правило, которые были применены, утверждения JWT, которые были проверены, и какой шаг валидации завершился сбоем, что обычно позволяет пропустить следующие проверки.

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

Декодируйте JWT
Декодируйте отправленный вами assertion, чтобы сравнить каждое утверждение с конфигурацией вашего эмитента и правила:
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
Проверьте, что iss совпадает с эмитентом
Декодированное утверждение iss должно совпадать с зарегистрированным issuer_url побайтово, включая схему, порт и любой завершающий слэш. Несовпадение даже в одном символе приводит к сбою проверки.
Проверьте, что aud совпадает с правилом
Декодированное утверждение aud должно содержать значение audience правила как точное совпадение. Если aud — массив, один элемент должен совпадать точно.
Проверьте sub и каждую запись claims
Сравните sub с subject_prefix правила (чувствительно к регистру; завершающий * означает префиксное совпадение, всё остальное — точное). Сравните каждый ключ в карте claims правила с одноимённым утверждением верхнего уровня.
Проверьте exp, nbf и iat
exp должно быть в будущем, а nbf/iat — в прошлом, в пределах 30-секундного окна допуска. Если часы хоста рабочей нагрузки сбились, в остальном валидный токен будет отклонён.
Проверьте доступность JWKS
Для режима discovery запросите <jwks.discovery_base или issuer_url>/.well-known/openid-configuration по публичному HTTPS на порту 443 и убедитесь, что jwks_uri разрешается. Для explicit_url запросите URL JWKS напрямую. Для inline убедитесь, что ключ подписи эмитента не был ротирован с момента регистрации ключей.
Если эмитент ротировал свой ключ подписи и сразу начал подписывать им, обмены могут завершаться сбоем до одной минуты, пока кэш JWKS Anthropic обновляется. См. Ротация ключей и кэширование.

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

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

`jwks.type`	Форма `jwks`	Поведение	Используйте, когда
`discovery` (по умолчанию)	`{ "type": "discovery", "discovery_base": "https://..." }` (`discovery_base` необязателен; задайте его, если URL обнаружения отличается от `issuer_url`)	Anthropic запрашивает `<discovery_base или 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`. `issuer_url` используется только для строкового сравнения с утверждением `iss` JWT и никогда не запрашивается.	Ваш 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. Если ваш провайдер идентификации публикует новый ключ подписи и сразу начинает подписывать им токены, обмены, предъявляющие эти токены, могут завершаться сбоем с ошибкой подписи до одной минуты, пока кэш обновляется.

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

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

Was this page helpful?

АдминистрированиеАутентификация

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

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

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

Поле	Обязательное	Описание
`grant_type`	Да	Всегда `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	Да	OIDC JWT, выданный вашим провайдером идентификации.
`federation_rule_id`	Да	Тегированный идентификатор (`fdrl_...`) правила федерации, которое нужно применить.
`organization_id`	Да	UUID вашей организации Anthropic.
`service_account_id`	Да	Тегированный идентификатор (`svac_...`) целевой сервисной учётной записи.
`workspace_id`	Условно	Тегированный идентификатор (`wrkspc_...`) рабочего пространства, которым будет ограничен выпущенный токен, или литерал `default` для рабочего пространства организации по умолчанию. Обязателен, если правило включено более чем для одного рабочего пространства. Если опущен, сервер выбирает единственное включённое рабочее пространство правила.

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

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

Поле	Тип	Описание
`access_token`	string	Короткоживущий токен Anthropic с префиксом `sk-ant-oat01-...`. Передавайте его как `Authorization: Bearer <token>`.
`token_type`	string	Всегда `Bearer`.
`expires_in`	integer	Количество секунд до истечения срока действия токена.
`scope`	string	Область действия OAuth, предоставленная сработавшим правилом.

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

SDK считывает эти переменные для выполнения федеративного обмена токена без аргументов конструктора.

Переменная	Обязательная	Описание	Пример
`ANTHROPIC_FEDERATION_RULE_ID`	Да	Тегированный идентификатор правила федерации, которое нужно применить.	`fdrl_...`
`ANTHROPIC_ORGANIZATION_ID`	Да	UUID вашей организации Anthropic. Найдите его в Claude Console в разделе Settings > Organization.	`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`	Да	Тегированный идентификатор целевой сервисной учётной записи Anthropic, от имени которой действует выпущенный токен доступа.	`svac_...`
`ANTHROPIC_WORKSPACE_ID`	Условно	Тегированный идентификатор рабочего пространства, которым будет ограничен выпущенный токен, или литерал `default`. Обязательна, если правило федерации включено более чем для одного рабочего пространства; необязательна, если правило привязано к единственному рабочему пространству. Выпущенный токен ограничивается этим рабочим пространством в момент обмена, поэтому для переключения рабочих пространств требуется новый обмен.	`wrkspc_...`
`ANTHROPIC_PROFILE`	Нет	Имя профиля конфигурации для загрузки. Имеет приоритет над переменными окружения федерации из этой таблицы.	`staging-profile`

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

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

Файл конфигурации профиля

Каталог конфигурации

SDK находит каталог конфигурации в следующем порядке:

$ANTHROPIC_CONFIG_DIR
~/.config/anthropic в Linux и macOS
%APPDATA%\Anthropic в Windows

Активный профиль

Имя активного профиля определяется в следующем порядке:

$ANTHROPIC_PROFILE
Содержимое <config_dir>/active_config (однострочный файл, записываемый командой ant profile activate <name>)
Литеральное имя default

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

Путь	Содержимое	Чувствительность
`<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`.

Пример профиля федерации

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

Область действия Предоставляет доступ к

Область действия	Предоставляет доступ к
`workspace:developer`	Все неадминистративные конечные точки Claude API в рабочем пространстве правила: Messages (включая потоковую передачу и подсчёт токенов), Models, Managed Agents и их сессии, Files и Skills. Это соответствует доступу, который имеет ключ API, выпущенный для того же рабочего пространства.
`org:manage_tunnels`	API туннелей MCP: получение списка и отдельных туннелей, регистрация и архивирование CA-сертификатов, раскрытие и ротация токена туннеля, а также архивирование туннелей. Модальное окно создания туннеля в Console фиксирует эту область действия при создании правила из него.

Правила валидации

Поля ресурсов

Поле	Ограничение
`name` эмитента, правила и сервисной учётной записи	Должно соответствовать `^[a-z0-9-]+$`, длина от 1 до 255 символов.
`workspace_id`	Необязательно. Рабочее пространство (`wrkspc_...`), чьи квоты, биллинг и ограничения скорости применяются к токенам, выпущенным по этому правилу. Должно быть рабочим пространством в той же организации, а целевая сервисная учётная запись должна быть членом этого рабочего пространства. Может быть опущено для правил, настроенных только для одного рабочего пространства.
`token_lifetime_seconds`	Целое число от `60` до `86400` (от 1 минуты до 24 часов). По умолчанию `3600`. Значения вне этого диапазона отклоняются во время запроса. См. Время жизни токена и обновление.

Поля URL

Поля issuer_url, jwks.discovery_base и jwks.url проходят валидацию:

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

Проверка JWT

Ограничение	Подробности
Максимальный размер	JWT в `assertion` должен быть не более 16 КиБ.
Алгоритм подписи	Принимаются только асимметричные алгоритмы (семейства RSA и ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512). HMAC (`HS256`, `HS384`, `HS512`) и `none` отклоняются.
Идентификатор ключа	Заголовок JWT должен содержать `kid`, соответствующий ключу в JWKS эмитента. Токены без `kid` отклоняются.
Обязательные утверждения	`sub` должно присутствовать. `iat` должно присутствовать и не быть в будущем. `exp` должно присутствовать и быть в будущем.
Максимальное время жизни	Время жизни токена (`exp` минус `iat`) не должно превышать настроенный максимум эмитента (1 час по умолчанию, настраивается для каждого эмитента в Claude Console).
Расхождение часов	К `exp`, `nbf` и `iat` применяется допуск в 30 секунд.

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

Сопоставитель	Тип	Семантика
`subject_prefix`	string	Точное совпадение с утверждением `sub` JWT. Завершающий `` делает его префиксным совпадением (значение `sub` должно начинаться с символов перед ``). Чувствительно к регистру.
`audience`	string	Утверждение `aud` JWT должно содержать эту точную строку. Если `aud` — массив, проверку удовлетворяет любой элемент, совпадающий точно.
`claims`	map<string, string>	Каждый ключ — это имя утверждения верхнего уровня, а каждое значение — требуемое точное строковое значение. Для вложенных, числовых, булевых или сложных утверждений, таких как списки и карты, используйте `condition` с CEL-выражением.
`condition`	string (CEL)	Выражение CEL, которое должно вычисляться в `true`.

Среда выполнения CEL

Выражение condition имеет доступ к единственной переменной:

Переменная	Тип	Содержимое
`claims`	map	Полный декодированный набор утверждений JWT. Вложенные объекты доступны как вложенные карты.

Пример:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Ошибки

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

Статус	Ошибка	Причина	Решение
400	`invalid_request`	`federation_rule_id` имеет неверный формат или отсутствует обязательное поле запроса.	Проверьте идентификатор `fdrl_` и убедитесь, что тело запроса включает все обязательные поля.
400	`invalid_request`	`workspace_id_required`: правило федерации включено более чем для одного рабочего пространства, а в запросе опущен `workspace_id`.	Задайте `ANTHROPIC_WORKSPACE_ID` (или поле `workspace_id` в теле необработанного запроса) равным идентификатору `wrkspc_...`, которым вы хотите ограничить токен. См. Запрос на обмен токена.
400	`invalid_grant`	Утверждение `iss` JWT не совпадает точно с зарегистрированным `issuer_url`.	Сравните побайтово, включая завершающие слэши и схему: `jq -rR 'split(".")[1] \| gsub("-";"+") \| gsub("_";"/") \| @base64d \| fromjson \| .iss' <<< "$JWT"`.
400	`invalid_grant`	Не удалось получить JWKS, JWKS устарел или JWT подписан ключом, отсутствующим в JWKS.	Для режима `inline` обновите эмитент с ротированными ключами. Для `discovery` и `explicit_url` убедитесь, что конечная точка JWKS доступна на порту 443; если эмитент недавно ротировал свой ключ подписи, см. Ротация ключей и кэширование.
400	`invalid_grant`	Утверждение `exp` JWT находится в прошлом (за пределами 30-секундного окна допуска).	Убедитесь, что ваш провайдер идентификации проецирует свежий токен и что SDK перечитывает файл токена.
400	`invalid_grant`	JWT был проверен, но его утверждения не удовлетворяют блоку `match` правила.	Декодируйте JWT и сравните каждое утверждение с правилом. `subject_prefix` чувствителен к регистру. `audience` требует точного совпадения элемента.
400	`invalid_grant`	`federation_rule_id` не существует, архивирован или JWT не авторизован для него (объединено для предотвращения перебора).	Проверьте идентификатор правила в Claude Console и убедитесь, что правило не было архивировано.

Распространённые сбои на стороне 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.
Аутентификация завершается сбоем с пустыми учётными данными	Переменная окружения учётных данных экспортирована, но установлена в пустую строку. Пустые значения всё равно выигрывают свой слот приоритета.	Удалите переменную с помощью `unset VAR`, а не `VAR=""`.

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

Ответ 400 invalid_grant намеренно непрозрачен; конкретная причина логируется только на стороне сервера.

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

Декодируйте JWT
Декодируйте отправленный вами assertion, чтобы сравнить каждое утверждение с конфигурацией вашего эмитента и правила:
cURL
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"
Проверьте, что iss совпадает с эмитентом
Декодированное утверждение iss должно совпадать с зарегистрированным issuer_url побайтово, включая схему, порт и любой завершающий слэш. Несовпадение даже в одном символе приводит к сбою проверки.
Проверьте, что aud совпадает с правилом
Декодированное утверждение aud должно содержать значение audience правила как точное совпадение. Если aud — массив, один элемент должен совпадать точно.
Проверьте sub и каждую запись claims
Сравните sub с subject_prefix правила (чувствительно к регистру; завершающий * означает префиксное совпадение, всё остальное — точное). Сравните каждый ключ в карте claims правила с одноимённым утверждением верхнего уровня.
Проверьте exp, nbf и iat
exp должно быть в будущем, а nbf/iat — в прошлом, в пределах 30-секундного окна допуска. Если часы хоста рабочей нагрузки сбились, в остальном валидный токен будет отклонён.
Проверьте доступность JWKS
Для режима discovery запросите <jwks.discovery_base или issuer_url>/.well-known/openid-configuration по публичному HTTPS на порту 443 и убедитесь, что jwks_uri разрешается. Для explicit_url запросите URL JWKS напрямую. Для inline убедитесь, что ключ подписи эмитента не был ротирован с момента регистрации ключей.
Если эмитент ротировал свой ключ подписи и сразу начал подписывать им, обмены могут завершаться сбоем до одной минуты, пока кэш JWKS Anthropic обновляется. См. Ротация ключей и кэширование.

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

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

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

Was this page helpful?