Autenticación con la propia autoridad de un agente

Los agentes pueden acceder a las Cloud de Confiance APIs y a otros recursos con su propia autoridad. Recomendamos este método para los agentes alojados en Cloud de Confiance para interactuar con otros Cloud de Confiance servicios.

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

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 Cloud de Confiance servicios, pídele a tu administrador que te otorgue los siguientes roles de IAM en el recurso de destino:

• Para otorgar acceso a un agente, haz lo siguiente:
  • Administrador de IAM de proyecto (roles/resourcemanager.projectIamAdmin)
  • Administrador de seguridad (roles/iam.securityAdmin)
• Roles recomendados para la identidad del agente:
  • Editor de contexto del agente (roles/aiplatform.agentContextEditor)
  • Acceso predeterminado del agente (roles/aiplatform.agentDefaultAccess)
  • Usuario de Vertex AI (roles/aiplatform.user)
  • Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer)
  • Navegador (roles/browser)
  • Visualizador de objetos de almacenamiento (roles/storage.objectViewer)

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 Cloud de Confiance 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 los agentes usan identificadores principales.

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

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

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

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

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 SDK 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: Inhabilitar el Acceso adaptado al contexto

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 la puerta de enlace del agente, 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 aplica que se use mTLS para acceder a la puerta de enlace del agente. Esto garantiza que los tokens vinculados a certificados solo se puedan usar desde su entorno de ejecución de confianza previsto (por ejemplo, un contenedor de Cloud Run). 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).

En casos excepcionales, como requisitos específicos de uso compartido de tokens entre agentes, si necesitas insertar el token directamente en el encabezado o si tu agente no puede autenticarse con un error 401 UNAUTHENTICATED, puedes inhabilitar la política predeterminada de Acceso adaptado al contexto. Si inhabilitas esta opción, se quita la protección de la vinculación de tokens, lo que hace que estos tokens de acceso de corta duración sean vulnerables a robos o ataques de reproducción. Por lo tanto, no se recomienda inhabilitar esta opción.

Para inhabilitar esta opción, configura la siguiente variable de entorno cuando implementes tu agente:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

Implementa el agente

Cuando implementes tu agente en Cloud de Confiance by S3NS, asegúrate de que la identidad del agente esté habilitada. Si realizas la implementación en Agent Runtime, 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?

• Autenticación con OAuth de 2 segmentos con el administrador de autenticación
• Autenticación con OAuth de 3 segmentos con el administrador de autenticación
• Autenticación con clave de API con el administrador de autenticación
• Administra proveedores de autenticación de identidad del agente
• Soluciona problemas del administrador de autenticación de identidad del agente
• Descripción general de la identidad del agente