Limita los permisos de los agentes con credenciales con alcance

Cuando tu agente de organización llama a un agente Agent2Agent (A2A) remoto, las credenciales de alcance ayudan a garantizar que el agente remoto reciba solo los permisos necesarios para esa solicitud. Después de descubrir un agente en el Registro de agentes, puedes incluir las credenciales de tu usuario o generar tokens con permisos con el administrador de autenticación de Agent Identity con permisos de OAuth restringidos o límites de acceso a credenciales para Cloud Storage.

Antes de comenzar

Antes de limitar los permisos de los agentes con credenciales con alcance para las llamadas de A2A, completa los siguientes pasos:

  1. Configura el Registro de agentes.
  2. Para una configuración de un solo proyecto, obtén el ID del proyecto del proyecto de administración en el que está habilitado el Registro de agentes. Si configuraste un límite de administración para varios proyectos, usa el ID de tu proyecto de administración para el descubrimiento y el registro en todo el límite, o especifica un ID del proyecto miembro para las operaciones de un solo proyecto.

  3. Si deseas restringir los tokens de Cloud Storage, habilita la API de Security Token Service (sts.googleapis.com) en tu proyecto.

  4. Instala las bibliotecas de Python google-auth y requests:

    pip install --upgrade google-auth requests
    
  5. Configura las credenciales predeterminadas de la aplicación (ADC) para el desarrollo local. De lo contrario, adjunta una cuenta de servicio o una configuración de credenciales de la federación de identidades para cargas de trabajo:

    gcloud auth application-default login
    

Roles obligatorios

Puedes usar tu cuenta de usuario para el desarrollo local, o bien una cuenta de servicio o un principal del agente para que tu agente de organización descubra agentes registrados y llame a los agentes A2A de destino. La cuenta de usuario, la cuenta de servicio o la principal del agente deben tener los roles adecuados para completar estas tareas.

Para asegurarte de que tu cuenta de usuario, cuenta de servicio o principal del agente tenga los permisos necesarios para descubrir agentes A2A en el Registro de agentes y llamar a los agentes A2A de destino , pídele a tu administrador que otorgue los siguientes roles de IAM a tu cuenta de usuario, cuenta de servicio o principal del agente:

  • Para descubrir agentes en Agent Registry: Visualizador de la API de Agent Registry (roles/agentregistry.viewer) en el proyecto de administración donde Agent Registry está habilitado
  • Para llamar a un agente A2A de destino en el entorno de ejecución: El rol de entorno de ejecución o de puerta de enlace para el servicio que aloja al agente de destino, necesario para llamar a ese agente. Por ejemplo, si el agente de destino se ejecuta en Cloud Run, la cuenta o el principal deben tener el rol de invocador de Cloud Run (roles/run.invoker).

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

Es posible que tu administrador también pueda otorgar a tu cuenta de usuario, cuenta de servicio o principal del agente los permisos necesarios a través de roles personalizados o de otros roles predefinidos.

Cómo se pasan las credenciales entre agentes

Cuando un cliente de A2A o un agente de organización envía un mensaje a un agente remoto, los servicios downstream verifican los permisos según cómo se autentica la solicitud:

  • En nombre de un usuario: Un usuario accede a tu agente de organización, que pasa un token de OAuth 2.0 autorizado por el usuario o un token administrado por el administrador de autenticación al agente A2A remoto. Google Cloud Las APIs verifican el token y comprueban los permisos de Identity and Access Management (IAM) del usuario para que el agente remoto no pueda acceder a los recursos a los que el usuario no tiene permiso para acceder.
  • Usa la identidad propia del agente: Cuando un agente de organización se ejecuta sin un usuario que haya accedido, se autentica con su propia identidad de agente o cuenta de servicio. Los servicios downstream verifican los roles otorgados a la principal de ese agente (principal://), un conjunto de principales coincidente (principalSet://) o su cuenta de servicio.
  • Desde cargas de trabajo externas o multinube: Los agentes que se ejecutan fuera de Google Cloud intercambian tokens de un proveedor de identidad externo a través de la federación de identidades para cargas de trabajo para obtener tokens de acceso de Google Cloud federados antes de llamar a los extremos de los agentes A2A de destino.

Para limitar los permisos que un token otorga a un agente remoto, puedes limitar el alcance de los tokens de OAuth con vinculaciones para agentes A2A de terceros o de SaaS.

También puedes restringir los tokens de Cloud Storage con un límite de acceso a las credenciales para restringir un token de acceso de Google Cloud a buckets u objetos específicos de Cloud Storage. Los límites de acceso a credenciales solo admiten permisos de Cloud Storage (storage.googleapis.com). Para otras APIs de Google Cloud y llamadas de agentes A2A, define el alcance del acceso a través de vinculaciones del administrador de autenticación, identidades de agentes con privilegios mínimos con políticas de permisos y denegación de IAM, o Agent Gateway.

Si esas opciones no se ajustan a tu caso de uso y tu agente de organización se autentica con una cuenta de servicio, también puedes usar la identidad temporal como cuenta de servicio para solicitar un token de corta duración para una cuenta de servicio dedicada que solo tenga los roles necesarios para una tarea específica.

Limita el alcance de los tokens de OAuth con vinculaciones

Cuando llames a un agente A2A de terceros o de SaaS que use OAuth 2.0 de 2 o 3 segmentos, crea un proveedor de autenticación en el administrador de autenticación y adjunta un recurso Binding en el registro de agentes que enumere solo los scopes de OAuth que necesita el agente remoto. Cuando el Kit de desarrollo de agentes (ADK) recupera el agente remoto con get_remote_a2a_agent(), solicita tokens limitados a los permisos de esa vinculación. Para conocer los pasos de configuración, consulta Autentica en herramientas y recursos y Administra vinculaciones.

Restringe los tokens de Cloud Storage

Si tu agente de organización pasa un token de acceso de OAuth 2.0 a un agente o una herramienta que lee o escribe datos de Cloud Storage, puedes reducir los permisos del token para permitir solo el acceso a buckets o prefijos de objetos específicos. Usa el Servicio de tokens de seguridad para aplicar un límite de acceso a las credenciales antes de enviar la solicitud:

import google.auth
from google.auth import downscoped
from google.auth.transport.requests import Request

source_creds, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

access_boundary_rule = downscoped.AccessBoundaryRule(
    available_resource=(
        "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
    ),
    available_permissions=["inRole:roles/storage.objectViewer"],
)
cab = downscoped.CredentialAccessBoundary(rules=[access_boundary_rule])

downscoped_creds = downscoped.Credentials(
    source_credentials=source_creds,
    credential_access_boundary=cab,
)
downscoped_creds.refresh(Request())

Reemplaza BUCKET_NAME por el nombre del bucket de Cloud Storage que el agente remoto puede leer.

Controles de seguridad adicionales

Puedes combinar el alcance de las credenciales con las políticas de red y la inspección de instrucciones:

  • Políticas de acceso a la red: Enrutan las llamadas de A2A a través de Agent Gateway para aplicar las políticas de acceso unificado (UAP) de Identity-Aware Proxy (IAP) en los recursos de Agent registrados.
  • Inspección de instrucciones y respuestas: Configura la integración de Model Armor con Agent Gateway y las vinculaciones de extensiones de servicio para inspeccionar las instrucciones y respuestas de A2A compatibles en busca de inyección de instrucciones y exposición de datos sensibles.

¿Qué sigue?