Использование WIF с Google Cloud

Любая вычислительная среда Google Cloud с доступом к серверу метаданных экземпляра (Cloud Run, Cloud Functions, App Engine, Compute Engine (GCE) и GKE с Workload Identity) может запросить подписанный Google токен идентификации (identity token) для прикреплённого к ней сервисного аккаунта. Издатель токена — https://accounts.google.com, и Anthropic может проверить его напрямую через стандартное обнаружение OIDC (OIDC discovery) без какой-либо дополнительной настройки Google Cloud.

В этом руководстве показано, как зарегистрировать издателя Google в Anthropic, привязать сервисный аккаунт Google к сервисному аккаунту Anthropic и настроить вашу рабочую нагрузку так, чтобы она обменивала свой токен идентификации на краткосрочный токен доступа к Claude API.

Предварительные требования

• Знакомство с концепциями WIF: сервисные аккаунты, издатели федерации и правила федерации.
• Проект Google Cloud с рабочей нагрузкой, запущенной в Cloud Run, Cloud Functions, App Engine, Compute Engine или GKE.
• Управляемый пользователем сервисный аккаунт Google, прикреплённый к этой рабочей нагрузке (не сервисный аккаунт Compute Engine по умолчанию).
• Разрешение на создание сервисных аккаунтов, издателей федерации и правил федерации в Claude Console для вашей организации Anthropic.

Настройка Google Cloud

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

gcloud run deploy my-service \
  --service-account inference-worker@my-project.iam.gserviceaccount.com

GET http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full
Metadata-Flavor: Google

gcloud auth print-identity-token \
  --audiences="https://api.anthropic.com" \
  --include-email

{
  "iss": "https://accounts.google.com",
  "aud": "https://api.anthropic.com",
  "sub": "104892...",
  "azp": "104892...",
  "email": "inference-worker@my-project.iam.gserviceaccount.com",
  "email_verified": true,
  "exp": 1775527120
}

Настройка Anthropic

В Claude Console откройте Settings → Workload identity, нажмите Connect workload и выберите плитку Google Cloud. Мастер проведёт вас через регистрацию издателя, создание сервисного аккаунта и создание правила федерации.

Мастер создаёт эти ресурсы за вас. Используйте следующие значения независимо от того, вводите ли вы их в мастере или отправляете в Admin API:

Издатель федерации: Google публикует свой документ обнаружения OIDC в открытом доступе, поэтому используйте режим обнаружения (discovery mode). Этот единственный издатель охватывает все среды Google Cloud (Cloud Run, GCE, Cloud Functions, App Engine и GKE с Workload Identity). Различайте рабочие нагрузки с помощью правил, а не издателей.

{
  "name": "gcp",
  "issuer_url": "https://accounts.google.com",
  "jwks": { "type": "discovery" }
}

Правило федерации: Сопоставляйте оба утверждения — sub и email. email — это читаемый адрес сервисного аккаунта; sub — числовой уникальный идентификатор сервисного аккаунта, который Google никогда не использует повторно, поэтому его закрепление защищает правило в случае, если сервисный аккаунт будет удалён, а позже будет создан новый с тем же email. Найдите уникальный идентификатор с помощью gcloud iam service-accounts describe SA_EMAIL --format='value(uniqueId)'.

{
  "name": "gcp-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "audience": "https://api.anthropic.com",
    "claims": {
      "sub": "104892101234567890123",
      "email": "inference-worker@my-project.iam.gserviceaccount.com"
    }
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

Получение и использование токена

Внутри вашей рабочей нагрузки Google Cloud получите токен идентификации с сервера метаданных, обменяйте его через POST /v1/oauth/token и используйте возвращённый bearer-токен для вызова Claude API. Каждый SDK Anthropic выполняет обмен и цикл обновления за вас, если вы предоставите вызываемый объект поставщика токенов (token provider), возвращающий свежий токен идентификации с сервера метаданных, как показано в следующих примерах.

import os
import anthropic
import google.auth.transport.requests
import google.oauth2.id_token
from anthropic import WorkloadIdentityCredentials

AUDIENCE = "https://api.anthropic.com"


def fetch_google_identity_token() -> str:
    request = google.auth.transport.requests.Request()
    return google.oauth2.id_token.fetch_id_token(request, AUDIENCE)


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_google_identity_token,
        federation_rule_id=os.environ["ANTHROPIC_FEDERATION_RULE_ID"],
        organization_id=os.environ["ANTHROPIC_ORGANIZATION_ID"],
        service_account_id=os.environ["ANTHROPIC_SERVICE_ACCOUNT_ID"],
        workspace_id=os.environ.get("ANTHROPIC_WORKSPACE_ID"),
    ),
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Cloud Run"}],
)
print(next(block.text for block in message.content if block.type == "text"))

Срок действия токенов идентификации Google истекает примерно через один час. SDK повторно вызывают поставщика токенов и автоматически выполняют повторный обмен до истечения срока. Для shell-скриптов, которые выполняются дольше, чем значение expires_in токена доступа, обновляйте токен по таймеру и повторяйте обмен.

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

Изнутри вашей рабочей нагрузки декодируйте токен идентификации и убедитесь, что утверждения соответствуют вашему правилу:

curl -sS -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://api.anthropic.com&format=full" \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

Проверьте, что iss равно https://accounts.google.com, aud равно https://api.anthropic.com, а email совпадает со значением в вашем правиле федерации. Затем выполните обмен из предыдущего раздела. Успешный обмен возвращает access_token, начинающийся с sk-ant-oat01-, и значение expires_in в секундах. Если обмен завершается неудачей с непрозрачным ответом 401 authentication_error (сообщение Authentication failed), проверьте страницу истории аутентификации, чтобы узнать причину отказа, и см. раздел Устранение неполадок при неудачном обмене; наиболее частая причина на стороне Google Cloud — отсутствие утверждения email (запрашивайте токен с format=full, чтобы оно было включено).

Ограничение области действия правила

Ограничьте блок match правила самой узкой областью, подходящей для вашего сценария использования:

• Точное сопоставление sub: Укажите полный числовой уникальный идентификатор в claims.sub и никогда не используйте subject_prefix для токенов Google.
• Закрепление утверждения email: Добавьте claims.email вместе с sub, чтобы совпадать должны были и стабильный идентификатор, и читаемый адрес.
• Закрепление аудитории: Установите audience в точное значение, которое вы запрашиваете у сервера метаданных, чтобы токены, выпущенные для других потребителей, отклонялись.
• Закрепление проекта в GKE: Для токенов format=full добавьте condition, например claims.google.compute_engine.project_id == "my-project", чтобы ограничить правило узлами одного проекта.

Следующие шаги

• Прочитайте страницу Workload Identity Federation, чтобы ознакомиться с полной моделью ресурсов и приоритетом учётных данных в SDK.
• Добавьте отдельное правило федерации для каждой среды (production, staging), чтобы вы могли отозвать одно, не затрагивая остальные.