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, с утверждениями, которые выглядят как Y, могут действовать как сервисный аккаунт Z».



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

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

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



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

Эмитент федерации (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, ваш промежуточный кластер и GitHub Actions — это три отдельных эмитента.



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

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

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

• Соответствие: Условия, которым должен удовлетворять входящий JWT. Вы можете сопоставлять по subject_prefix (например, system:serviceaccount:prod:worker, или с завершающим * для сопоставления по префиксу), точному audience, карте точных значений утверждений, выражению condition на CEL для сложной логики или любой их комбинации. Должен быть задан хотя бы один из subject_prefix, claims или condition, и все настроенные сопоставители должны пройти, чтобы JWT был принят.
• Цель: Сервисный аккаунт, на который отображается соответствующий JWT.
• Авторизация: Область 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 повторно выполняет обмен до истечения срока действия токена.



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

Вам нужна роль администратора, владельца или основного владельца в вашей организации 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-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 правила (по умолчанию 3 600 секунд) и (b) удвоенного оставшегося времени жизни предъявленного вами 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