Usar WIF com o Google Cloud

Qualquer ambiente de computação do Google Cloud com acesso ao servidor de metadados da instância (Cloud Run, Cloud Functions, App Engine, Compute Engine (GCE) e GKE com Workload Identity) pode solicitar um token de identidade assinado pelo Google para sua conta de serviço anexada. O emissor do token é https://accounts.google.com, e a Anthropic pode validá-lo diretamente por meio da descoberta OIDC padrão, sem necessidade de configuração adicional no Google Cloud.

Este guia mostra como registrar o emissor do Google na Anthropic, vincular uma conta de serviço do Google a uma conta de serviço da Anthropic e fazer com que sua carga de trabalho troque seu token de identidade por um token de acesso de curta duração à Claude API.

Pré-requisitos

• Familiaridade com os conceitos de WIF: contas de serviço, emissores de federação e regras de federação.
• Um projeto do Google Cloud com uma carga de trabalho em execução no Cloud Run, Cloud Functions, App Engine, Compute Engine ou GKE.
• Uma conta de serviço do Google gerenciada pelo usuário anexada a essa carga de trabalho (não a conta de serviço padrão do Compute Engine).
• Permissão para criar contas de serviço, emissores de federação e regras de federação no Claude Console para sua organização da Anthropic.

Configurar o Google Cloud

O Google emite tokens de identidade automaticamente para qualquer carga de trabalho com uma conta de serviço anexada. Não há nada a habilitar no lado do Google além de anexar a conta de serviço correta, mas as etapas diferem ligeiramente entre computação padrão e 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
}

Configurar a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione o bloco Google Cloud. O assistente orienta você no registro do emissor, na criação de uma conta de serviço e na criação de uma regra de federação.

O assistente cria esses recursos para você. Use os seguintes valores, seja inserindo-os no assistente ou enviando-os para a Admin API:

Emissor de federação: o Google publica seu documento de descoberta OIDC publicamente, portanto use o modo de descoberta. Esse único emissor cobre todas as superfícies do Google Cloud (Cloud Run, GCE, Cloud Functions, App Engine e GKE com Workload Identity). Diferencie as cargas de trabalho com regras, não com emissores.

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

Regra de federação: faça a correspondência tanto na claim sub quanto na claim email. email é o endereço legível da conta de serviço; sub é o ID exclusivo numérico da conta de serviço, que o Google nunca reutiliza, portanto fixá-lo protege a regra caso a conta de serviço seja excluída e uma nova seja criada posteriormente com o mesmo email. Encontre o ID exclusivo com 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
}

Obter e usar o token

Dentro da sua carga de trabalho do Google Cloud, obtenha o token de identidade do servidor de metadados, troque-o em POST /v1/oauth/token e use o token bearer retornado para chamar a Claude API. Cada SDK da Anthropic cuida do ciclo de troca e renovação para você quando você fornece um callable provedor de token que retorna um token de identidade novo do servidor de metadados, como mostrado nos exemplos a seguir.

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"))

Os tokens de identidade do Google expiram após aproximadamente uma hora. Os SDKs invocam novamente o provedor de token e refazem a troca automaticamente antes da expiração. Para scripts de shell que executam por mais tempo do que o expires_in do token de acesso, renove com um temporizador e repita a troca.

Verificar a configuração

De dentro da sua carga de trabalho, decodifique o token de identidade e confirme que as claims correspondem à sua regra:

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'

Verifique que iss é https://accounts.google.com, aud é https://api.anthropic.com e email corresponde ao valor na sua regra de federação. Em seguida, execute a troca da seção anterior. Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Se a troca falhar com a resposta opaca 401 authentication_error (mensagem Authentication failed), verifique a página de histórico de autenticação para ver o motivo da negação e consulte Solucionar problemas de uma troca com falha; a causa mais comum no lado do Google Cloud é a ausência da claim email (solicite o token com format=full para que ela seja incluída).

Restringir o escopo da sua regra

Restrinja o bloco match da regra ao escopo mais estreito que atenda ao seu caso de uso:

• Corresponda sub exatamente: defina o ID exclusivo numérico completo em claims.sub e nunca use subject_prefix para tokens do Google.
• Fixe a claim email: adicione claims.email junto com sub para que tanto o ID estável quanto o endereço legível precisem corresponder.
• Fixe o audience: defina audience com o valor exato que você solicita ao servidor de metadados, para que tokens emitidos para outros consumidores sejam rejeitados.
• Fixe o projeto no GKE: para tokens format=full, adicione uma condition como claims.google.compute_engine.project_id == "my-project" para restringir a regra aos nós de um único projeto.

Próximos passos

• Leia a página Workload Identity Federation para conhecer o modelo de recursos completo e a precedência de credenciais dos SDKs.
• Adicione uma regra de federação separada por ambiente (produção, staging) para que você possa revogar uma sem afetar as outras.