Workload Identity Federation

«Workload Identity Federation» (федерация удостоверений рабочих нагрузок), или WIF, позволяет вашим рабочим нагрузкам аутентифицироваться в Claude API с помощью краткосрочных токенов OpenID Connect (OIDC) вместо долгосрочных ключей API sk-ant-.... Токены поступают от «identity provider» (поставщика удостоверений), или 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, с утверждениями (claims), которые выглядят как Y, могут действовать от имени сервисного аккаунта Z».

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

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

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

Издатели федерации

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

Издатель имеет две части конфигурации:

• URL издателя: Точное значение утверждения iss, которое появляется в JWT поставщика, например https://token.actions.githubusercontent.com или https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• Источник JWKS: Способ, которым 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 — это три отдельных издателя.

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

Правило федерации («federation rule», 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).

У одного издателя может быть много правил: по одному на команду, пространство имён или уровень разрешений. Правила оцениваются по ID: клиент указывает, какое правило использовать, в запросе обмена, а 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 повторно выполняет обмен до истечения срока действия токена.

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

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

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

1. 1

   Откройте Connect workload

   В Claude Console перейдите в Settings → Workload identity и выберите Connect workload.

2. 2

   Выберите вашего поставщика

   Выберите плитку вашего поставщика удостоверений: GitHub Actions, AWS, Google Cloud, Microsoft Entra ID или Kubernetes. Каждая плитка предварительно заполняет шаблон URL издателя и поля соответствия, которые поддерживают JWT этого поставщика. Для любого другого соответствующего стандартам поставщика (например, SPIFFE или Okta) выберите Custom OIDC.

3. 3

   Заполните пошаговые поля

   Мастер проведёт вас через поля, специфичные для поставщика: конфигурацию издателя, условия соответствия для входящих JWT, а также имена сервисного аккаунта и правила федерации, которые он создаёт. Мастер предварительно заполняет oauth_scope=workspace:developer и token_lifetime_seconds=600 (значение по умолчанию в API, когда token_lifetime_seconds опущен, равно 3600); измените их, если вашей рабочей нагрузке нужна другая область действия или время жизни.

4. 4

   Проверьте издателя

   При желании выберите Verify issuer, чтобы выполнить пробный прогон конфигурации издателя до того, как что-либо будет создано. Проверка подтверждает, что Anthropic может получить и разобрать JWKS по введённым вами URL, что позволяет рано выявить ошибки доступности и конфигурации.

5. 5

   Протестируйте соединение

   Мастер создаёт издателя, сервисный аккаунт и правило федерации, а затем в течение 15 минут ожидает успешного обмена токенов. Инициируйте обмен из вашей рабочей нагрузки в течение этого окна (см. Аутентификация из вашей рабочей нагрузки), чтобы подтвердить, что настройка работает. Если окно истечёт, ресурсы сохранятся; вы можете повторно запустить тест со страницы сведений о правиле федерации. Запишите ID правила (fdrl_...) и ID сервисного аккаунта (svac_...), которые создаёт мастер: ваша рабочая нагрузка передаёт оба, вместе с ID вашей организации (и ID вашего рабочего пространства, когда правило охватывает более одного рабочего пространства), в каждом запросе обмена токенов.

Чтобы управлять этими ресурсами программно, см. Управление 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "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 — это меньшее из (a) token_lifetime_seconds правила (по умолчанию 3600 секунд) и (b) удвоенного оставшегося времени жизни предъявленного вами JWT от IdP. Результат никогда не бывает меньше 60 секунд. Второе ограничение не позволяет токену Anthropic пережить вышестоящую идентичность, из которой он был получен, более чем на небольшой запас.

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

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

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

По умолчанию токены идентификации, содержащие утверждение jti, являются одноразовыми: каждый обмен должен предъявлять JWT, который ранее не обменивался, а повторное предъявление завершается неудачей с причиной jti_reused на странице истории аутентификации. Если ваша рабочая нагрузка сама получает токены от вашего поставщика удостоверений, выпускайте свежий JWT для каждого обмена вместо повторного использования кэшированного (частый виновник — циклы повторных попыток). То же относится к токену, читаемому из ANTHROPIC_IDENTITY_TOKEN_FILE: SDK повторно читает файл при каждом обмене, поэтому файл должен содержать новый токен перед каждым обновлением. Обновление, которое повторно читает неротированный токен, или перезапущенный процесс, который повторно предъявляет уже обменянный токен, отклоняется таким же образом. Ротация токена с хорошим запасом в пределах времени жизни выпущенного токена позволяет файлу опережать расписание обновления; если ваш источник токенов не может ротировать их так часто, вы можете в крайнем случае отключить check_jti для этого издателя (это снимает защиту от повторного воспроизведения для каждого правила этого издателя). Подробности см. в разделе Проверка JWT.

Поставщики удостоверений

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

См. также

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