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

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

gcloud run deploy my-service \
  --service-account [email protected]

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": "[email protected]",
  "email_verified": true,
  "exp": 1775527120
}



Настройка Anthropic

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

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

Издатель федерации: Google публикует свой документ обнаружения OIDC публично, поэтому используйте режим обнаружения. Этот единственный издатель охватывает все поверхности 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": "[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-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 в секундах. При ошибке 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), чтобы вы могли отозвать одно, не затрагивая остальные.