Autentícate en Google Cloud con la identidad propia de un agente

Los agentes pueden acceder a las APIs de Google Cloud y a otros recursos con su propia identidad. Google recomienda este método para que los agentes alojados en Google Cloud interactúen con otros servicios de Google Cloud .

Cuando un agente actúa bajo su propia autoridad, usa su identidad de SPIFFE principal para solicitar tokens de acceso de Google Cloud .

Antes de comenzar

  1. Verifica que hayas elegido el método de autenticación correcto.
  2. Crea e implementa un agente con la identidad de agente habilitada.
  3. Verifica que tengas los roles necesarios para completar esta tarea.

Roles obligatorios

Para obtener los permisos que necesitas para otorgar acceso a un agente a los servicios de Google Cloud , pídele a tu administrador que te otorgue los siguientes roles de IAM en el recurso de destino:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Otorga acceso a los agentes

Para permitir que tu agente acceda a un servicio de Google Cloud , debes otorgar a la identidad del agente los roles necesarios en el recurso de destino.

En las políticas de permisos de IAM, las identidades de los agentes usan identificadores de principales.

Para otorgar acceso a un recurso a un agente, usa la consola de Google Cloud o la gcloud CLI.

Console

  1. En la consola de Google Cloud , ve a la página IAM del recurso al que deseas otorgar acceso.
    • Para un proyecto, ve a la página IAM:

      Ir a la página IAM

    • Para otros recursos, ve a la página de ese recurso y haz clic en la pestaña Permisos o IAM.
  2. Haz clic en Otorgar acceso.
  3. En el campo Principales nuevas, ingresa el identificador de principal que coincida con el nivel de acceso que deseas otorgar:
    • Un solo agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Todos los agentes de un proyecto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Todos los agentes de una organización: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  4. En el campo Selecciona un rol, busca y selecciona el rol que deseas otorgar.
  5. Haz clic en Guardar.

Google Cloud CLI

Para otorgar acceso a un recurso a un agente, ejecuta el siguiente comando: 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Reemplaza lo siguiente:

  • SERVICE: Es el servicio de Google Cloud (por ejemplo, storage o bigquery).
  • RESOURCE_NAME: Es el nombre del recurso (por ejemplo, el nombre del bucket o el ID del conjunto de datos).
  • PRINCIPAL_IDENTIFIER: Es el identificador de la principal que coincide con el nivel de acceso que deseas otorgar:
    • Un solo agente: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
    • Todos los agentes de un proyecto: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
    • Todos los agentes de una organización: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
  • ORGANIZATION_ID: Es el ID de tu organización de Google Cloud .
  • PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
  • LOCATION: Es la ubicación de tu agente (por ejemplo, us-central1). (Solo se requiere para el acceso de un solo agente).
  • ENGINE_ID: Es el ID de tu motor de razonamiento. (Solo se requiere para el acceso de un solo agente).
  • ROLE: Es el rol de IAM que deseas otorgar.

Haz referencia a la identidad del agente en tu código

Las bibliotecas cliente de Google Cloud usan automáticamente la identidad del agente cuando este se implementa en un entorno de Google Cloud compatible.

En el siguiente fragmento de Python, se muestra cómo usar de forma manual las credenciales de identidad del agente para llamar a la API de Cloud Vision con el Kit de desarrollo de agentes (ADK).

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

Opcional: Inhabilita los tokens vinculados a certificados

Una política predeterminada de Acceso adaptado al contexto administrada por Google ayuda a proteger las credenciales de identidad del agente. Más allá de Agent Gateway, la política aplica la demostración de prueba de posesión (DPoP) autenticando el token de acceso del agente. La política también requiere TLS mutua (mTLS) para acceder a Agent Gateway. Este requisito ayuda a garantizar que solo el entorno de ejecución previsto y de confianza, como un contenedor de Cloud Run o un Pod de Google Kubernetes Engine (GKE), pueda usar los tokens vinculados a certificados. Esta línea de base de seguridad hace que las credenciales robadas no se puedan volver a usar, lo que ayuda a proteger contra el robo de credenciales y la apropiación de cuentas (ATO).

La vinculación de certificados ayuda a proteger dos tipos de credenciales de agente:

  • Tokens de acceso deGoogle Cloud : Son tokens de acceso de OAuth 2.0 de corta duración que autentican solicitudes a las APIs de Google Cloud y otros recursos (*.googleapis.com).
  • Tokens de ID de OpenID Connect (OIDC): Son tokens web JSON (JWT) que autentican solicitudes a servicios externos y a herramientas y servicios alojados en entornos de ejecución de Google Cloud , como Cloud Run (*.mtls.run.app) o GKE.

Inhabilitar la vinculación para todos los tokens de acceso y de ID

No se recomienda inhabilitar la política de acceso adaptado al contexto predeterminada ni los tokens vinculados a certificados en todo el entorno de ejecución. Si configuras GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false, se quita la protección de vinculación de tokens para los tokens de acceso de Google Cloud y los tokens de ID de OIDC, lo que hace que estos tokens de corta duración sean vulnerables a robos o ataques de repetición.

Sin embargo, puedes inhabilitar la función en todo el entorno de ejecución en los siguientes casos excepcionales:

  • Tienes requisitos específicos para compartir tokens entre agentes.
  • Debes insertar el token directamente en el encabezado de la solicitud.
  • Tu agente no puede autenticarse y devuelve un error 401 UNAUTHENTICATED.

Para inhabilitar la recopilación en todo el entorno de ejecución, establece la siguiente variable de entorno cuando implementes el agente:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

Inhabilita las solicitudes de tokens de ID individuales

De forma predeterminada, las bibliotecas cliente de Google Auth compatibles vinculan criptográficamente los tokens de ID de OIDC al certificado X.509 único del agente incluyendo la huella digital del certificado en la reclamación cnf (x5t#S256) del token.

Algunos servicios, como Cloud Run, aplican la vinculación de certificados cuando la reclamación cnf está presente. Si tu agente llama a estos servicios a través de un extremo que no es de mTLS, como una URL estándar de *.run.app, o si un extremo de destino no requiere la vinculación de certificados, puedes inhabilitar las solicitudes de tokens de ID individuales. Este parámetro de configuración solo afecta a esa solicitud y no inhabilita la vinculación de certificados para los tokens de acceso de Google Cloud .

Python

En la biblioteca de Python google-auth (2.61.0 o una versión posterior en GKE y 2.62.0 o una versión posterior en Cloud Run), configura bind_id_token=False:

from google.auth.transport.requests import AuthorizedSession
from google.auth.transport.requests import Request
from google.oauth2 import id_token

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

Reemplaza TARGET_SERVICE_URL por el URI o la URL del público del servicio receptor al que llama tu agente.

Implementa el agente

Cuando implementes tu agente en Google Cloud, asegúrate de que la identidad del agente esté habilitada. Si implementas en Agent Runtime en Gemini Enterprise Agent Platform, usa la marca identity_type=AGENT_IDENTITY:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

¿Qué sigue?