Usar WIF con Google Cloud

Cualquier entorno de cómputo de Google Cloud con acceso al servidor de metadatos de la instancia (Cloud Run, Cloud Functions, App Engine, Compute Engine (GCE) y GKE con Workload Identity) puede solicitar un token de identidad firmado por Google para su cuenta de servicio asociada. El emisor del token es https://accounts.google.com, y Anthropic puede validarlo directamente mediante el descubrimiento OIDC estándar, sin necesidad de configuración adicional en Google Cloud.

Esta guía muestra cómo registrar el emisor de Google en Anthropic, vincular una cuenta de servicio de Google a una cuenta de servicio de Anthropic y hacer que tu carga de trabajo intercambie su token de identidad por un token de acceso de corta duración para la Claude API.

Requisitos previos

• Familiaridad con los conceptos de WIF: cuentas de servicio, emisores de federación y reglas de federación.
• Un proyecto de Google Cloud con una carga de trabajo ejecutándose en Cloud Run, Cloud Functions, App Engine, Compute Engine o GKE.
• Una cuenta de servicio de Google administrada por el usuario asociada a esa carga de trabajo (no la cuenta de servicio predeterminada de Compute Engine).
• Permiso para crear cuentas de servicio, emisores de federación y reglas de federación en la Claude Console para tu organización de Anthropic.

Configurar Google Cloud

Google emite tokens de identidad automáticamente a cualquier carga de trabajo con una cuenta de servicio asociada. No hay nada que habilitar del lado de Google más allá de asociar la cuenta de servicio correcta, pero los pasos difieren ligeramente entre el cómputo estándar y 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 Anthropic

En la Claude Console, abre Settings → Workload identity, haz clic en Connect workload y selecciona el mosaico Google Cloud. El asistente te guía a través del registro del emisor, la creación de una cuenta de servicio y la creación de una regla de federación.

El asistente crea estos recursos por ti. Usa los siguientes valores, ya sea que los ingreses en el asistente o los envíes a la Admin API:

Emisor de federación: Google publica su documento de descubrimiento OIDC de forma pública, así que usa el modo de descubrimiento. Este único emisor cubre todas las superficies de Google Cloud (Cloud Run, GCE, Cloud Functions, App Engine y GKE con Workload Identity). Diferencia las cargas de trabajo con reglas, no con emisores.

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

Regla de federación: Haz coincidir tanto el claim sub como el claim email. email es la dirección legible de la cuenta de servicio; sub es el ID único numérico de la cuenta de servicio, que Google nunca reutiliza, por lo que fijarlo protege la regla si la cuenta de servicio se elimina y más tarde se crea una nueva con el mismo email. Encuentra el ID único con 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
}

Obtener y usar el token

Dentro de tu carga de trabajo de Google Cloud, obtén el token de identidad del servidor de metadatos, intercámbialo en POST /v1/oauth/token y usa el token bearer devuelto para llamar a la Claude API. Cada SDK de Anthropic gestiona el intercambio y el ciclo de renovación por ti cuando proporcionas un callable proveedor de tokens que devuelve un token de identidad nuevo del servidor de metadatos, como se muestra en los siguientes ejemplos.

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

Los tokens de identidad de Google expiran después de aproximadamente una hora. Los SDK vuelven a invocar al proveedor de tokens y repiten el intercambio automáticamente antes de la expiración. Para scripts de shell que se ejecutan durante más tiempo que el expires_in del token de acceso, renueva con un temporizador y repite el intercambio.

Verificar la configuración

Desde dentro de tu carga de trabajo, decodifica el token de identidad y confirma que los claims coinciden con tu regla:

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'

Comprueba que iss sea https://accounts.google.com, que aud sea https://api.anthropic.com y que email coincida con el valor de tu regla de federación. Luego ejecuta el intercambio de la sección anterior. Un intercambio exitoso devuelve un access_token que comienza con sk-ant-oat01- y un valor expires_in en segundos. Si el intercambio falla con la respuesta opaca 401 authentication_error (mensaje Authentication failed), revisa la página de historial de autenticación para ver el motivo del rechazo y consulta Solucionar un intercambio fallido; la causa más común del lado de Google Cloud es la ausencia del claim email (solicita el token con format=full para que se incluya).

Delimitar tu regla

Restringe el bloque match de la regla al alcance más estrecho que se ajuste a tu caso de uso:

• Haz coincidir sub exactamente: Establece el ID único numérico completo en claims.sub y nunca uses subject_prefix para tokens de Google.
• Fija el claim email: Agrega claims.email junto con sub para que tanto el ID estable como la dirección legible deban coincidir.
• Fija el audience: Establece audience en el valor exacto que solicitas al servidor de metadatos para que los tokens emitidos para otros consumidores sean rechazados.
• Fija el proyecto en GKE: Para tokens format=full, agrega una condition como claims.google.compute_engine.project_id == "my-project" para restringir la regla a los nodos de un solo proyecto.

Próximos pasos

• Lee la página de Workload Identity Federation para conocer el modelo de recursos completo y la precedencia de credenciales de los SDK.
• Agrega una regla de federación separada por entorno (producción, staging) para que puedas revocar una sin afectar a las demás.