Autenticación de Agent2Agent (A2A)

El protocolo Agent2Agent (A2A) permite a los agentes invocar a otros agentes. La mayoría de los puntos de conexión A2A requieren autenticación para acceder al punto de conexión y a su servicio subyacente. La configuración de la autenticación garantiza que solo los usuarios autorizados puedan invocar las herramientas A2A en el Foundry Agent Service.

En este artículo se explican los métodos de autenticación disponibles para las conexiones A2A y se ayuda a elegir el enfoque adecuado para su escenario.

Escenarios de autenticación

En general, hay dos escenarios de autenticación:

  • Autenticación compartida: cada usuario del agente usa la misma identidad para autenticarse en el punto de conexión de A2A. El contexto de usuario individual no persiste. Este enfoque es ideal cuando todos los usuarios deben tener el mismo nivel de acceso. Por ejemplo, si crea un agente de chat para recuperar información de Azure Cosmos DB de la organización, es posible que quiera que todos los usuarios accedan al mismo contenedor compartido sin necesidad de iniciar sesión individual.
  • Autenticación individual: cada usuario del agente se autentica con su propia cuenta, por lo que su contexto de usuario persiste en las interacciones. Este enfoque es esencial cuando las acciones deben limitarse a los permisos del usuario. Por ejemplo, si crea un agente de codificación que recupera confirmaciones y solicitudes de incorporación de cambios de GitHub, quiere que cada desarrollador inicie sesión con su propia cuenta de GitHub para que solo vean los repositorios a los que tienen acceso.

Requisitos previos

Antes de elegir un método de autenticación, necesita lo siguiente:

  • Acceso al portal de Foundry y a un proyecto. Si no tiene uno, consulte Creación de proyectos en Foundry.
  • El rol Azure AI User o superior en tu proyecto. Este rol concede permisos para crear conexiones de proyecto y configurar agentes. Para obtener más información, consulte Control de acceso basado en rol en el portal de Foundry.
  • La dirección URL del punto de conexión de A2A a la que quiere conectarse. Póngase en contacto con el publicador de puntos de conexión para confirmar qué métodos de autenticación admite el punto de conexión.
  • Credenciales para el método de autenticación seleccionado:
    • Basado en claves: una clave de API, un token de acceso personal (PAT) u otro token secreto proporcionado por el publicador del punto de conexión.
    • autenticación de Microsoft Entra: asignación de roles para la identidad de agente o la identidad gestionada del proyecto en el servicio subyacente. Los roles específicos dependen del servicio (por ejemplo, Lector de datos de base de datos deCosmos para Azure Cosmos DB).

Elección de un método de autenticación

El método de autenticación que elija depende de si necesita contexto de usuario compartido o individual y de qué protocolos de autenticación admite el punto de conexión A2A.

Use la tabla siguiente para elegir el método adecuado para su escenario:

Su objetivo Método recomendado
Uso de una identidad compartida para todos los usuarios Autenticación basada en claves o autenticación de Microsoft Entra
Conservar la identidad y los permisos de cada usuario Transferencia de identidad de OAuth
Evite administrar secretos cuando el servicio subyacente admita Microsoft Entra autenticación de Microsoft Entra
Conexión a un punto de conexión de A2A que no requiere autenticación Acceso no autenticado

Métodos de autenticación admitidos

En la tabla siguiente se resumen los métodos de autenticación disponibles para las conexiones A2A:

Método Descripción El contexto de usuario persiste
Basado en claves Proporcione una clave de API o un token de acceso para autenticarse con el punto de conexión de A2A. Lo mejor para los puntos de conexión que usan la autenticación simple basada en tokens. No
Microsoft Entra ID: identidad del agente Use la identidad administrada del agente para autenticarse. Requiere asignaciones de roles en el servicio subyacente. Ideal para Azure servicios que admiten identidades administradas. No
Microsoft Entra ID: identidad administrada del proyecto Use la identidad administrada del proyecto para autenticarse. Requiere asignaciones de roles en el servicio subyacente. Use esta opción cuando quiera que todos los agentes de un proyecto compartan la misma identidad. No
Transferencia de identidad de OAuth Pida a los usuarios que inicien sesión y autoricen el acceso al punto de conexión de A2A. Se requiere cuando necesite permisos por usuario. Sí
Acceso no autenticado No se requiere autenticación. Use este método solo para puntos de conexión A2A a los que se pueda acceder públicamente o no requiera autenticación. No

Autenticación basada en claves

Nota

Cualquier persona con acceso al proyecto puede acceder a secretos almacenados en una conexión de proyecto. Almacene solo secretos compartidos en las conexiones del proyecto. Para el acceso específico del usuario, use el passthrough de identidad de OAuth en su lugar.

Use la autenticación basada en claves cuando el punto de conexión A2A acepte una clave de API, un token de acceso personal (PAT) u otra credencial secreta. Para mejorar la seguridad, almacene las credenciales compartidas en una conexión de proyecto en lugar de pasarlas en tiempo de ejecución.

Al conectar el punto de conexión de A2A a un agente en el portal de Foundry, Foundry crea una conexión de proyecto automáticamente. Proporcione el nombre de credencial (el nombre del encabezado HTTP) y el valor de credencial (el valor de encabezado). El formato depende de lo que espera el punto de conexión.

Formatos de credenciales comunes:

Tipo de punto de conexión Nombre de credencial Valor de credencial
Token de portador Authorization Bearer <your-token>
Clave de API en el encabezado x-api-key <your-api-key>
Encabezado personalizado <custom-header-name> <your-secret-value>

Cuando el agente invoca el punto de conexión A2A, el servicio del agente recupera las credenciales de la conexión del proyecto e las incluye en los encabezados de solicitud.

Procedimientos recomendados de seguridad para la autenticación basada en claves

  • Usar credenciales con privilegios mínimos: solicite solo los permisos mínimos necesarios para las tareas del agente.
  • Rotar tokens con regularidad: establezca un recordatorio para volver a generar tokens antes de que expiren.
  • Restringir el acceso al proyecto: limite quién puede acceder a los proyectos que contienen secretos compartidos.
  • Auditar el uso de credenciales: Monitorear el acceso a conexiones de proyectos en los registros de actividad de Azure.

autenticación de Microsoft Entra ID

Utilice la autenticación de Microsoft Entra ID cuando el punto de conexión A2A y su servicio subyacente aceptan tokens de Microsoft Entra ID. Este método elimina la necesidad de administrar secretos porque Azure controla automáticamente la adquisición y renovación de tokens.

Identidad del agente

Use la identidad administrada del agente para autenticarse con puntos de conexión A2A que admitan la autenticación Microsoft Entra ID. Al crear un agente en el servicio del agente, el agente recibe automáticamente una identidad administrada.

Ciclo de vida de la identidad:

  • Antes de publicar: todos los agentes del mismo proyecto comparten una identidad común. Esto simplifica el desarrollo y las pruebas.
  • Después de la publicación: cada agente publicado recibe una identidad única. Esto proporciona aislamiento y habilita el control de acceso pormenorizado.

Para obtener más información sobre el ciclo de vida de la identidad del agente, consulte Conceptos de identidad deAgent en Microsoft Foundry.

Para configurar la autenticación de identidad del agente:

  1. Identifique el servicio subyacente que activa el punto de conexión A2A (por ejemplo, Azure Cosmos DB o Azure Storage).
  2. Asigne los roles necesarios a la identidad del agente en ese servicio. Los roles específicos dependen del servicio y de las operaciones que el agente debe realizar.
  3. Configure la conexión A2A para usar la autenticación de identidad del agente.

Cuando el agente invoca el punto de conexión A2A, el servicio del agente usa la identidad del agente para solicitar un token de autorización de Microsoft Entra ID e incluirlo en la solicitud.

Identidad administrada del proyecto Foundry

Use la identidad administrada del proyecto Foundry para autenticarse en puntos de conexión de A2A. Esta opción es útil cuando desea que todos los agentes de un proyecto compartan la misma identidad para acceder a los recursos.

Para configurar la autenticación de identidad administrada del proyecto:

  1. Identifique el servicio subyacente que impulsa el punto de conexión A2A.
  2. Asigne los roles necesarios a la identidad administrada del proyecto en ese servicio.
  3. Configure la conexión A2A para usar la autenticación de identidad administrada del proyecto.

Cuando el agente invoca el punto de conexión A2A, el servicio del agente usa la identidad administrada del proyecto para solicitar un token de autorización de Microsoft Entra ID e incluirlo en la solicitud.

Transferencia de identidad de OAuth

Nota

Para usar la autenticación directa de identidad de OAuth, los usuarios que interactúan con su agente necesitan al menos el rol Usuario de IA de Azure en el proyecto.

El paso directo de identidad de OAuth permite al agente actuar en nombre de usuarios individuales. Use este método cuando las acciones deben tener como ámbito los permisos de cada usuario, como el acceso a sus archivos personales, repositorios u otros recursos protegidos.

La transferencia directa de identidad de OAuth funciona con puntos de conexión A2A de Microsoft y de terceros que admiten OAuth 2.0, incluidos los servicios que usan Microsoft Entra ID.

Funcionamiento de la autenticación delegada de la identidad de OAuth

  1. Primera interacción: cuando un usuario interactúa por primera vez con el agente, el servicio del agente genera un vínculo de consentimiento.
  2. Consentimiento del usuario: el usuario abre el vínculo, inicia sesión en el servicio subyacente y autoriza al agente a acceder a sus datos.
  3. Almacenamiento de Tokens: Servicio del Agente almacena de forma segura los tokens de OAuth del usuario (token de acceso y token de actualización). Estos tokens se limitan a esa combinación específica de usuario y agente.
  4. Solicitudes posteriores: cuando el agente invoca el punto de conexión A2A, el servicio del agente incluye el token de acceso del usuario en la solicitud. Si el token de acceso expira, el servicio del agente usa el token de actualización para obtener uno nuevo.

Tipos de token de OAuth

OAuth usa dos tipos de tokens:

Tipo de token Propósito Ciclo de vida
Token de acceso Autoriza las llamadas API al servicio subyacente. Periodo de corta duración (normalmente 1 hora) para limitar la exposición si se ve comprometida.
Token de actualización Obtiene nuevos tokens de acceso sin necesidad de que el usuario vuelva a iniciar sesión. Duración más larga (horas a semanas o hasta que se revoque)

Los ámbitos de OAuth definen lo que el agente puede acceder y hacer en nombre del usuario. Los ámbitos se especifican al configurar la conexión y se presentan al usuario durante el flujo de consentimiento. Para obtener más información sobre OAuth, consulte la documentación de seguridad de Microsoft.

OAuth administrado frente a OAuth personalizado

El servicio del agente admite dos opciones de configuración de OAuth:

Opción Descripción Cuándo usar
OAuth administrado Microsoft o el publicador de puntos de conexión de A2A administra el registro de la aplicación OAuth. Use cuando esté disponible. Simplifica la configuración y reduce los errores de configuración.
OAuth personalizado Usted proporciona su propio registro de aplicación OAuth de Microsoft Entra ID u otro proveedor de identidades. Use cuando OAuth administrado no esté disponible o cuando necesite ámbitos personalizados o personalización de marca.

Para configurar OAuth personalizado, proporcione la siguiente información:

  • ID de cliente: el ID de tu registro de aplicación OAuth.
  • Secreto de cliente (si es necesario): el secreto asociado al registro de la aplicación.
  • Dirección URL de autorización: punto de conexión donde los usuarios autorizan el acceso.
  • Dirección URL del token: el punto de conexión en el que el servicio del agente intercambia el código de autorización para los tokens.
  • URL de actualización: punto final para refrescar los tokens de acceso expirados.
  • Scopes: los permisos que necesita el agente (por ejemplo, repo para GitHub o Files.Read para Microsoft Graph).

Importante

Si usa OAuth personalizado, recibirá una dirección URL de redireccionamiento de Agent Service. Agregue esta dirección URL a los URI de redirección permitidos del registro de la aplicación de OAuth, permitiendo que el Servicio del Agente complete el flujo de autorización.

Acceso no autenticado

Use acceso no autenticado solo cuando el punto de conexión A2A sea accesible públicamente y no requiera autenticación. Esta opción es poco frecuente en escenarios de producción, pero puede ser adecuada para:

  • API públicas que no requieren autenticación
  • Puntos finales de desarrollo o pruebas internas
  • Puntos de conexión protegidos por seguridad de nivel de red (como puntos de conexión privados) en lugar de autenticación

Configuración de la autenticación para una conexión A2A

Siga estos pasos para configurar la autenticación para una conexión A2A:

  1. Identifique el punto de conexión A2A y los métodos de autenticación admitidos. Póngase en contacto con el publicador de puntos de conexión o compruebe la documentación del punto de conexión para determinar qué métodos de autenticación se admiten.

  2. Recopile las credenciales necesarias en función del método de autenticación elegido:

    • Basado en clave: obtenga la clave de API o el token del proveedor del punto de conexión.
    • Microsoft Entra ID: identifique las asignaciones de roles necesarias para el servicio subyacente.
    • OAuth: determine si OAuth administrado está disponible o recopile los detalles de registro de aplicaciones de OAuth personalizados.

  3. Cree una conexión de proyecto en el portal de Foundry. La conexión almacena la dirección URL del punto de conexión de A2A, el método de autenticación y las credenciales.

  4. Configurar las asignaciones de roles (solo autenticación Microsoft Entra ID). Asigne los roles necesarios a la identidad del agente o a la identidad administrada del proyecto en el servicio subyacente.

  5. Agregue la herramienta A2A a su agente. Consulte la conexión del proyecto que creó y configure las herramientas del punto de conexión de A2A que su agente puede invocar.

Validación de la autenticación

Después de configurar la autenticación, pruebe la conexión para confirmar que funciona correctamente.

Validación de la autenticación basada en claves o Microsoft Entra ID

  1. Abra el agente en el portal Foundry.
  2. Inicie una conversación y desencadene una acción que invoque la herramienta A2A.
  3. Confirme que la llamada a la herramienta se completa correctamente. Si se produce un error en la llamada, compruebe el mensaje de error y consulte Solución de problemas.

Validar la autenticación de identidad OAuth

  1. Abra el agente en el portal de Foundry mediante una cuenta de usuario de prueba que no haya consentido previamente.
  2. Inicie una conversación y desencadene una acción que invoque la herramienta A2A.
  3. Confirme que aparece un vínculo de consentimiento en la respuesta del agente.
  4. Abra el vínculo de consentimiento e inicie sesión con las credenciales del usuario de prueba.
  5. Autorice los permisos solicitados.
  6. Vuelva al agente y active la herramienta A2A de nuevo.
  7. Confirme que la llamada a la herramienta se completa correctamente con las credenciales del usuario de prueba.
  8. (Opcional) Pruebe con otra cuenta de usuario para confirmar que los flujos de consentimiento funcionan para varios usuarios.

Solución de problemas

Use la tabla siguiente para diagnosticar y resolver problemas comunes de autenticación:

Problema Causa posible Resolución
Error de autenticación basada en claves con 401 No autorizado Token no válido o expirado Vuelva a generar el token desde el publicador del punto de conexión y actualice la conexión del proyecto.
Error de autenticación basada en claves con 400 solicitudes incorrectas Formato incorrecto de nombre o valor de encabezado Compruebe la documentación del punto de conexión para ver el formato de encabezado esperado. Entre los formatos comunes se incluyen Authorization: Bearer <token> y x-api-key: <key>.
La autenticación de Microsoft Entra ID falla con el error 403 Prohibido. La identidad no tiene las asignaciones de roles necesarias Asigne los roles necesarios a la identidad del agente o a la identidad administrada del proyecto en el servicio subyacente. Los cambios de asignación de roles pueden tardar hasta 10 minutos en propagarse.
error de autenticación de Microsoft Entra ID con 401 No autorizado El servicio subyacente no acepta tokens de Microsoft Entra ID o la audiencia es incorrecta. Confirme que el servicio subyacente admite la autenticación Microsoft Entra ID. Compruebe que el punto de conexión A2A está configurado para aceptar tokens para la audiencia correcta.
El consentimiento se completa, pero se produce un error en las llamadas a herramientas El usuario no tiene permisos en el servicio subyacente Confirme que el usuario tiene los permisos necesarios en el servicio subyacente. Confirme también que el usuario tiene al menos el rol Azure AI User en el proyecto Foundry.
No aparece ningún vínculo de consentimiento para OAuth El paso de identidad de OAuth no está configurado o el agente no invocó la herramienta A2A. Compruebe que la conexión del proyecto está configurada para el paso a través de la identidad de OAuth. Desencadene una acción que invoque la herramienta A2A.
Aparece el vínculo de consentimiento, pero se produce un error en el inicio de sesión La configuración personalizada de OAuth es incorrecta Para OAuth personalizado, compruebe que la dirección URL de autorización, el identificador de cliente y la dirección URL de redirección son correctas. Confirme que la dirección URL de redireccionamiento se agrega al registro de la aplicación OAuth.
El token de actualización ha expirado El usuario no ha interactuado con el agente durante un período prolongado El usuario debe volver a pasar por el flujo de consentimiento. Este es el comportamiento esperado para la seguridad.

Contenido relacionado

  • Last updated on