Справочник WIF

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

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

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

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

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

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

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

Прямой путь федерации через переменные окружения активируется только тогда, когда ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID и одна из ANTHROPIC_IDENTITY_TOKEN_FILE или ANTHROPIC_IDENTITY_TOKEN все установлены. ANTHROPIC_WORKSPACE_ID читается наряду с ними, но не управляет активацией.

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

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

Когда профиль загружен, переменные окружения заполняют любые поля, которые профиль опускает, но никогда не переопределяют поля, которые профиль устанавливает явно. Например, 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 соблюдают этот же порядок разрешения, поэтому профиль федерации, настроенный здесь, также аутентифицирует эти инструменты без дополнительной настройки.

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

И файл конфигурации, и файл учётных данных несут строковое поле 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

oauth_scope, который вы устанавливаете для правила федерации, определяет, какие конечные точки Claude API может вызывать выпущенный токен доступа.

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

Границы разрешений

oauth_scope правила федерации — это потолок: выпущенный токен никогда не может его превысить. organization_role целевой сервисной учётной записи (developer или admin) определяет, какие области действия можно предоставить, поэтому правило, предоставляющее org:admin, должно нацеливаться на сервисную учётную запись с organization_role=admin. Эффективные разрешения — это пересечение области действия правила и роли сервисной учётной записи.

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

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

Полные сведения о параметрах и схемах ответов см. в справочнике по API сервисных учётных записей, справочнике по API эмитентов федерации и справочнике по API правил федерации.

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

Поля URL

Поля issuer_url, jwks.discovery_base и jwks.url валидируются:

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

Проверка JWT

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

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

Среда оценки CEL