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

Los agentes pueden acceder a las Google Cloud APIs 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 Google Cloud servicios.

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

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 de agente a los Google Cloud servicios, 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 mediante roles personalizados o cualquier otro rol predefinido.

Otorgar acceso a los agentes

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

En las políticas de permiso de IAM, las identidades de agente usan identificadores principales.

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

Console

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

      Ve a la página IAM

    • Para otros recursos, ve a la página de ese recurso y haz clic en la Permisos o IAM tab.
  2. Haz clic en Otorgar acceso.
  3. En el campo Principales nuevas, ingresa el identificador 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 de agente a un recurso, ejecuta el siguiente comando: 
gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

Reemplaza lo siguiente:

  • SERVICE: El Google Cloud servicio (por ejemplo, storage o bigquery).
  • RESOURCE_NAME: El nombre del recurso (por ejemplo, el nombre del bucket o el ID del conjunto de datos).
  • PRINCIPAL_IDENTIFIER: El identificador 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: Tu Google Cloud ID de organización.
  • PROJECT_NUMBER: Tu Google Cloud número de proyecto.
  • LOCATION: La ubicación de tu agente (por ejemplo, us-central1). (Solo es obligatorio para el acceso de un solo agente).
  • ENGINE_ID: El ID de tu motor de razonamiento. (Solo es obligatorio para el acceso de un solo agente).
  • ROLE: El rol de IAM que deseas otorgar.

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

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

En el siguiente fragmento de Python, se muestra cómo usar de forma manual las credenciales de identidad de 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 de acceso adaptado al contexto predeterminada administrada por Google ayuda a proteger las credenciales de identidad de agente. Más allá del Agent Gateway, la política aplica la demostración de prueba de posesión (DPoP) mediante la autenticación del token de acceso del agente. La política también requiere TLS mutua (mTLS) para acceder al Agent Gateway. Este requisito ayuda a garantizar que solo el entorno de ejecución de confianza previsto, 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 reproducir, 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:

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

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

No se recomiendainhabilitar la política de acceso adaptado al contexto predeterminada y los tokens vinculados a certificados en 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 y los tokens de ID de OIDC Google Cloud , lo que hace que estos tokens de corta duración sean vulnerables al robo o a los ataques de reproducción.

Sin embargo, puedes inhabilitar el entorno de ejecución en los siguientes casos poco frecuentes:

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

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

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

Inhabilita las solicitudes individuales de tokens de ID

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 mediante la inclusión de la huella digital del certificado en la declaración cnf (x5t#S256) del token.

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

Python

En la biblioteca google-auth de Python (2.61.0 o versiones posteriores en GKE y 2.62.0 o versiones posteriores en Cloud Run), establece 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 de 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 de agente esté habilitada. Si realizas la implementación en Agent Runtime en Gemini Enterprise Agent Platform , usa la identity_type=AGENT_IDENTITY marca:

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?