Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Эта страница собирает конфигурационные поверхности, ограничения валидации и сопоставления ошибок для 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 | Да | Тегированный ID (fdrl_...) правила федерации для оценки. |
organization_id | Да | UUID вашей организации Anthropic. |
service_account_id | Да | Тегированный ID (svac_...) целевого сервисного аккаунта. |
workspace_id | Условно | Тегированный 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 | Да | Тегированный 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 | Да | Тегированный ID целевого сервисного аккаунта Anthropic, от имени которого действует выданный токен доступа. | svac_... |
ANTHROPIC_WORKSPACE_ID | Условно | Тегированный 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>)defaultClaude 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 будет рассматривать файл как текущую версию.
{
"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_scope, который вы задаёте для правила федерации, определяет, какие конечные точки Claude API может вызывать выпущенный токен доступа.
| Область действия | Предоставляет доступ к |
|---|---|
workspace:developer | Все неадминистративные конечные точки Claude API в рабочем пространстве правила: Messages (включая потоковую передачу и подсчёт токенов), Models, Managed Agents и их сессии, Files и Skills. Это соответствует доступу, который имеет ключ API, выданный для того же рабочего пространства. |
workspace:inference | Конечные точки инференса в рабочем пространстве правила: Messages (включая потоковую передачу и подсчёт токенов), Models и OpenAI-совместимая конечная точка чата. Используйте это для рабочих нагрузок, которым нужно только вызывать Claude и никогда не нужно управлять Files, Skills или другими ресурсами. |
workspace:manage_tunnels | API туннелей MCP: создание, перечисление и получение туннелей, регистрация и архивирование сертификатов CA, раскрытие и ротация токена туннеля, а также архивирование туннелей. Модальное окно создания туннеля в Console фиксирует эту область действия, когда вы создаёте правило из него. |
org:admin | Полный доступ к Admin API (участники организации, приглашения, рабочие пространства, ключи API и остальное). Токен OAuth org:admin может создавать или изменять только правила с областью действия workspace:developer или workspace:inference и не может обновлять эмитента, который обеспечивает правило с любой другой областью действия; см. ограничения. |
Запрос к конечной точке вне области действия токена возвращает 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-вызывающих; см. ограничения. |
Anthropic применяет эти ограничения при создании или обновлении эмитентов и правил, а также при проверке входящего JWT во время обмена.
Полные сведения о параметрах и схемы ответов см. в справочнике API сервисных аккаунтов, справочнике API эмитентов федерации и справочнике API правил федерации.
| Поле | Ограничение |
|---|---|
name эмитента, правила и сервисного аккаунта | Должно соответствовать ^[a-z0-9-]+$, длина от 1 до 255 символов. |
workspace_id | Обязателен при создании, если applies_to_all_workspaces не равен true. Рабочее пространство (wrkspc_...), чьи квоты, биллинг и ограничения скорости применяются к токенам, выпущенным по этому правилу. Должно быть рабочим пространством в той же организации, и целевой сервисный аккаунт должен быть участником этого рабочего пространства. |
applies_to_all_workspaces | Булево значение. Установите true, чтобы включить правило в каждом рабочем пространстве организации вместо указания одного; при создании требуется либо это поле, либо workspace_id. |
token_lifetime_seconds | Целое число от 60 до 86400 (от 1 минуты до 24 часов). По умолчанию 3600. Значения вне этого диапазона отклоняются во время запроса. См. Время жизни и обновление токена. |
Поля 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 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. |
Выражение 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 имеет неверный формат или отсутствует обязательное поле запроса. | Проверьте ID fdrl_ и то, что тело запроса включает все обязательные поля. |
| 400 | invalid_request | workspace_id_required: правило федерации включено более чем для одного рабочего пространства, а в запросе опущен workspace_id. | Установите ANTHROPIC_WORKSPACE_ID (или поле тела workspace_id в необработанном запросе) в 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 не авторизован для него (объединено для предотвращения перечисления). | Подтвердите ID правила в Claude Console и то, что правило не было архивировано. |
Все сбои invalid_grant возвращают HTTP 400; конкретная причина логируется только на стороне сервера и не раскрывается в ответе.
| Симптом | Причина | Решение |
|---|---|---|
| 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, чтобы сравнить каждое утверждение с конфигурацией вашего эмитента и правила:
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 or issuer_url>/.well-known/openid-configuration через публичный HTTPS на порту 443 и убедитесь, что jwks_uri разрешается. Для explicit_url запросите URL JWKS напрямую. Для inline убедитесь, что ключ подписи эмитента не был ротирован с момента регистрации ключей.
Если эмитент ротировал свой ключ подписи и сразу начал подписывать им, обмены могут завершаться сбоем до минуты, пока кэш JWKS Anthropic обновляется. См. Ротация ключей и кэширование.
Когда вы регистрируете эмитента федерации, поле 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. 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. Если ваш провайдер идентификации публикует новый ключ подписи и сразу начинает подписывать им токены, обмены, предъявляющие эти токены, могут завершаться сбоем с ошибкой подписи до 1 минуты, пока кэш обновляется.
Чтобы избежать этого окна, публикуйте новый ключ подписи в JWKS как минимум за 15 минут до того, как ваш провайдер идентификации начнёт подписывать им токены, и сохраняйте заменённый ключ в JWKS до тех пор, пока подписанные им токены не истекут. Управляемые провайдеры идентификации обычно соблюдают эту дисциплину самостоятельно. Если вы управляете собственным эмитентом (самоуправляемый кластер Kubernetes, провайдер обнаружения SPIRE OIDC или пользовательский сервер авторизации Okta с настроенной периодичностью ротации), убедитесь, что ваша политика ротации публикует новые ключи до первого использования.
В режиме inline нет автоматического обновления ключей. Когда ваш провайдер идентификации ротирует свои ключи подписи, вы должны обновить конфигурацию эмитента новым JWKS, иначе все обмены токенов будут завершаться сбоем проверки подписи.
Was this page helpful?