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

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

Настройка Anthropic

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

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

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

Правило федерации: Сопоставляйте и утверждение sub, и утверждение email. email — это читаемый адрес сервисного аккаунта; sub — числовой уникальный идентификатор сервисного аккаунта, который Google никогда не использует повторно, поэтому его закрепление защищает правило на случай, если сервисный аккаунт будет удалён, а позже будет создан новый с тем же адресом электронной почты. Найдите уникальный идентификатор с помощью 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": "[email protected]"
    }
  },
  "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 обрабатывает обмен и цикл обновления за вас, если вы предоставите вызываемый объект — поставщик токенов, который возвращает свежий токен идентификации с сервера метаданных, как показано в следующих примерах.

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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello from Cloud Run"}],
)
print(message.content[0].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 в секундах. При ошибке 400 invalid_grant см. Устранение неполадок при неудачном обмене; наиболее частая причина на стороне 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), чтобы можно было отозвать одно, не затрагивая остальные.