Workload Identity Federation

«Workload Identity Federation» (федерация идентификации рабочих нагрузок), или WIF, позволяет вашим рабочим нагрузкам аутентифицироваться в Claude API с помощью короткоживущих токенов OpenID Connect (OIDC) вместо долгоживущих ключей API вида sk-ant-.... Токены поступают от поставщика идентификации (IdP), которым вы уже управляете: AWS IAM, Google Cloud или любого соответствующего стандартам OIDC-эмитента, такого как GitHub Actions, Kubernetes, SPIFFE, Microsoft Entra ID или Okta.

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

Workload Identity Federation укрепляет вашу безопасность, заменяя статические ключи API токенами, срок действия которых истекает через минуты, а не никогда. Сама по себе она не является полноценным решением безопасности: федеративная аутентификация надёжна лишь настолько, насколько надёжен вышестоящий поставщик идентификации, подписывающий JWT. Для глубокоэшелонированной защиты сочетайте Workload Identity Federation с механизмами контроля, которые уже поддерживает ваш IdP (привязка идентификации рабочих нагрузок, условный доступ, журналирование аудита).



Концепции

Прежде чем какая-либо рабочая нагрузка сможет использовать федерацию, вы настраиваете три ресурса в Claude Console. Вместе они выражают правило: «токены, подписанные эмитентом X, с утверждениями, которые выглядят как Y, могут действовать от имени сервисного аккаунта Z».



Сервисные аккаунты

Сервисный аккаунт (svac_...) — это именованная нечеловеческая идентичность внутри вашей организации Anthropic. Это субъект, от имени которого действует федеративный токен. Сервисные аккаунты существуют на уровне организации и становятся активными в рабочем пространстве, когда вы добавляете их в качестве участников этого рабочего пространства. В момент обмена Anthropic проверяет, что рабочее пространство правила федерации совпадает с одним из членств сервисного аккаунта в рабочих пространствах; выпущенный токен затем подчиняется ограничениям скорости и атрибуции использования этого рабочего пространства — так же, как и ключ API. В отличие от пользователя-человека, у сервисного аккаунта нет электронной почты, пароля и входа в Console. Каждый сервисный аккаунт неявно является участником рабочего пространства по умолчанию вашей организации; добавьте явные членства для любого другого рабочего пространства, в котором он должен действовать.

Ключевое отличие от ключа API: ключ API является учётными данными, тогда как для сервисного аккаунта учётные данные выпускаются по требованию. Вы можете проводить аудит того, какие рабочие нагрузки действовали от имени какого сервисного аккаунта.



Эмитенты федерации

Эмитент федерации (fdis_...) регистрирует поставщика идентификации OIDC в вашей организации. Регистрация эмитента сообщает Anthropic: «JWT, подписанные этим поставщиком, могут подтверждать идентичность рабочих нагрузок для моей организации».

Эмитент имеет два параметра конфигурации:

• Issuer URL: Точное значение утверждения iss, которое появляется в JWT поставщика, например https://token.actions.githubusercontent.com или https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• JWKS source: Способ, которым Anthropic получает открытые ключи для проверки подписей JWT. Используйте discovery (значение по умолчанию) для любого поставщика, который обслуживает /.well-known/openid-configuration по своему URL эмитента. Используйте explicit_url, чтобы указать непосредственно на конечную точку JWKS, или inline, чтобы загрузить набор ключей для эмитентов, недоступных из публичного интернета (например, приватный кластер Kubernetes).

URL эмитента и JWKS должны использовать https, порт 443 и публичное DNS-имя хоста, которое разрешается в публичные IP-адреса; IP-литералы не принимаются. Эти ограничения применяются только к URL, которые Anthropic запрашивает; в режимах explicit_url и inline значение issuer_url сравнивается как строка и может ссылаться на внутреннее имя хоста.

Обычно вы регистрируете по одному эмитенту на окружение: ваш продакшен-кластер EKS, ваш staging-кластер и GitHub Actions — это три отдельных эмитента.



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

Правило федерации (fdrl_...) — это мост между эмитентом и сервисным аккаунтом: «когда JWT от эмитента X имеет утверждения, которые выглядят как Y, выпустить токен для сервисного аккаунта Z с областью действия S».

Правило определяет условия соответствия, цель, а также область авторизации и время жизни токена, которые применяются при совпадении правила:

• Match: Условия, которым должен удовлетворять входящий JWT. Вы можете сопоставлять по subject_prefix (например, system:serviceaccount:prod:worker или с завершающим * для сопоставления по префиксу), точному audience, карте точных значений утверждений, выражению condition на языке CEL для сложной логики или любой их комбинации. Должен быть задан хотя бы один из параметров subject_prefix, claims или condition, и все настроенные сопоставители должны пройти проверку, чтобы JWT был принят.
• Target: Сервисный аккаунт, на который отображается совпавший JWT.
• Authorization: OAuth-область scope, предоставляемая выпущенному токену. По умолчанию это workspace:developer, что даёт тот же доступ, что и ключ API, выпущенный для этого рабочего пространства. Некоторые продукты фиксируют область действия при создании правила из своего потока; например, модальное окно создания туннеля в MCP tunnels создаёт правила с областью workspace:manage_tunnels. См. Области OAuth. Правило также задаёт token_lifetime_seconds (от 60 до 86400, по умолчанию 3600).

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



Как это работает

1. Ваш IdP выдаёт JWT рабочей нагрузке. На большинстве платформ это происходит автоматически: проецируемый токен сервисного аккаунта Kubernetes, сервер метаданных Google Cloud, Azure IMDS или конечная точка OIDC GitHub Actions. Утверждение iss в JWT идентифицирует поставщика, а sub и другие утверждения идентифицируют конкретную рабочую нагрузку.
2. SDK обменивает JWT на токен доступа Anthropic. SDK отправляет JWT на POST /v1/oauth/token, используя грант jwt-bearer из RFC 7523. Anthropic проверяет JWT по JWKS эмитента и условиям соответствия правила федерации, затем возвращает короткоживущий токен sk-ant-oat01-..., который действует от имени целевого сервисного аккаунта правила.
3. SDK отправляет токен с каждым запросом и обновляет его до истечения срока действия. Код вашего приложения создаёт клиент без api_key и вызывает API как обычно. SDK повторно выполняет обмен до истечения срока действия токена.



Настройка федерации

Вам потребуется роль администратора, владельца или основного владельца в вашей организации Anthropic, поставщик идентификации с поддержкой OIDC и доступной конечной точкой JWKS (или документ JWKS, который вы можете вставить, для изолированных кластеров), а также рабочая нагрузка, которая может получить токен идентификации от этого поставщика.

Мастер Connect workload создаёт все три ресурса (эмитент, сервисный аккаунт и правило федерации) в одном пошаговом потоке, а затем проверяет соединение от начала до конца.

Чтобы управлять этими ресурсами программно, см. Управление WIF с помощью Admin API для пошагового руководства с curl или см. справочник API сервисных аккаунтов, справочник API эмитентов федерации и справочник API правил федерации для полных сведений о параметрах и схемах ответов.



Аутентификация из вашей рабочей нагрузки

После настройки федерации ваша рабочая нагрузка обменивает выданный IdP JWT на токен Anthropic во время выполнения. SDK обрабатывают цикл обмена и обновления за вас. Вкладка cURL показывает базовый HTTP-обмен для shell-скриптов, отладки или языков без поддержки SDK.



Создание клиента SDK

Вы можете создать клиент с явными учётными данными или без аргументов. Без аргументов SDK разрешает учётные данные из переменных окружения или активного профиля, как описано в разделе Приоритет учётных данных. Форма без аргументов — рекомендуемый шаблон для продакшен-нагрузок: поставляйте один и тот же образ контейнера везде и внедряйте ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID и ANTHROPIC_IDENTITY_TOKEN_FILE для каждого окружения.

from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile

client = Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile(
            "/var/run/secrets/anthropic.com/token"
        ),
        federation_rule_id="fdrl_...",
        organization_id="00000000-0000-0000-0000-000000000000",
        service_account_id="svac_...",
        workspace_id="wrkspc_...",
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

Ответ на обмен токенами соответствует RFC 6749 §5.1. См. Ответ на обмен токенами для справки по полям.



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

Каждый SDK разрешает учётные данные в одном и том же пятиуровневом порядке: аргументы конструктора, затем ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, затем явный ANTHROPIC_PROFILE, затем переменные окружения федерации, затем неявный активный профиль. Побеждает первый источник, который предоставляет учётные данные.

Полную таблицу приоритетов, семантику каждого уровня и схему файла профиля см. в разделе Приоритет учётных данных справочника WIF.



Миграция с ключей API

Чтобы переключить существующую рабочую нагрузку со статического ключа API на федерацию без простоя:

1. Настройте федерацию параллельно. Выполните пошаговую настройку и убедитесь, что правило федерации соответствует токену вашей рабочей нагрузки. Пока оставьте существующий ANTHROPIC_API_KEY на месте.
2. Проверьте, какие учётные данные побеждают. Запустите ant auth status изнутри рабочей нагрузки (или изучите отладочные логи SDK). Поскольку ANTHROPIC_API_KEY находится выше уровней федерации в цепочке приоритетов, на этом этапе всё ещё побеждает ключ API.
3. Удалите ANTHROPIC_API_KEY везде, где он внедряется. Удалите его из секретов CI, окружения контейнера и профилей оболочки (см. предыдущее предупреждение). Повторно запустите ant auth status и убедитесь, что теперь выбран источник федерации.
4. Отзовите ключ API. Как только рабочая нагрузка работает на федеративном токене, удалите ключ в Claude Console в разделе Settings → API keys.



Время жизни токена и обновление

Время жизни выпущенного токена Anthropic — это меньшее из (а) значения token_lifetime_seconds правила (по умолчанию 3600 секунд) и (б) удвоенного оставшегося времени жизни предъявленного вами JWT от IdP. Результат никогда не меньше 60 секунд. Второе ограничение не позволяет токену Anthropic пережить вышестоящую идентичность, из которой он был получен, более чем на небольшой запас.

SDK кэшируют токен и обновляют его по двухуровневому расписанию, смоделированному по образцу botocore:

• Рекомендательное обновление за 120 секунд до истечения срока действия. SDK пытается выполнить новый обмен. Если конечная точка токенов недоступна, SDK продолжает использовать кэшированный токен, который остаётся действительным ещё примерно 90 секунд.
• Обязательное обновление за 30 секунд до истечения срока действия. Неудачный обмен на этом этапе вызывает ошибку. Кэшированный токен слишком близок к истечению срока действия, чтобы быть безопасным.

Поскольку SDK перечитывает ANTHROPIC_IDENTITY_TOKEN_FILE при каждом обмене, он прозрачно подхватывает ротированные проецируемые токены (например, токены сервисных аккаунтов Kubernetes ротируются задолго до их exp).



Поставщики идентификации

Каждое руководство описывает, откуда берётся JWT на данной платформе, как выглядят его утверждения, а также конфигурацию эмитента и правила для регистрации.



См. также

• Управление WIF с помощью Admin API: создание эмитентов, сервисных аккаунтов и правил из инфраструктуры как кода
• Справочник WIF: переменные окружения, схема файла профиля, правила валидации и коды ошибок
• Аутентификация: все варианты аутентификации в SDK Anthropic
• Справочник Admin API: сгенерированные схемы запросов и ответов для каждой конечной точки Admin API