Protección de llamadas a herramientas OpenAPI desde el Foundry Agent Service

El Servicio Agente de Foundry puede llamar anónimamente a un endpoint OpenAPI de App Service o con identidad gestionada. Utiliza la identidad gestionada cuando la autenticación por App Service protege el endpoint.

Este escenario contiene dos direcciones de identidad gestionadas independientes:

• Cuando App Service llama a Foundry, el llamante es la identidad gestionada asignada por el sistema de App Service. El control de acceso basado en roles (RBAC) de Azure en el recurso o proyecto de Foundry autoriza la llamada.
• Cuando Foundry llama al endpoint OpenAPI del servicio de aplicaciones, el llamador es la identidad gestionada asignada al sistema de recursos de Foundry padre. La validación de tokens de autenticación de App Service y las listas de permisos autorizan la llamada.

La aplicación de autenticación de servicio de aplicaciones Microsoft Entra es el recurso protegido de la API. Tampoco sustituye el uso de la identidad administrada.

La siguiente tabla resume las identidades y aplicaciones en este escenario.

Prerrequisitos

• Una aplicación de App Service con puntos de conexión de OpenAPI. Si necesita agregar funcionalidad de OpenAPI a la aplicación, consulte uno de los siguientes tutoriales:

  • Adición de una aplicación de App Service como herramienta en Foundry Agent Service (.NET)
  • Adición de una aplicación de App Service como herramienta en Foundry Agent Service (Java)
  • Adición de una aplicación de App Service como herramienta en Foundry Agent Service (Python)
  • Adición de una aplicación de App Service como herramienta en Foundry Agent Service (Node.js)

• Un proyecto de Microsoft Foundry donde añades tu aplicación como una herramienta OpenAPI.

Encuentra los IDs de identidad gestionada del recurso principal de Foundry

El Servicio de Agentes de Foundry utiliza la identidad gestionada asignada por el sistema del recurso principal de Foundry cuando llama a una herramienta OpenAPI. No utiliza la identidad gestionada del proyecto Foundry para esta solicitud.

Necesitas dos identificadores para la identidad del recurso padre:

• ID de aplicación (ID de cliente): Aparece en la reclamación del azp token de acceso y se utiliza para la comprobación de la aplicación de cliente permitida por autenticación por servicio de aplicaciones.
• ID del objeto (principal): Aparece en la reclamación del oid token y se usa cuando la autenticación por App Service restringe el acceso a identidades específicas.

1. En el portal de Foundry, abre tu proyecto y luego selecciona Gestionar en el menú superior.

2. Selecciona el recurso principal en detalles de Project y luego selecciona Abrir en el portal de Azure.

3. En el menú izquierdo del recurso Foundry, seleccione Gestión de recursos>Identidad.

4. En Asignado por el sistema, copie el valor de ID de objeto (principal) para su uso posterior.

5. En Azure Portal, busque y seleccione Microsoft Entra ID.

6. En el cuadro de búsqueda, busque el identificador de objeto que copió y selecciónelo en los resultados de búsqueda.

7. En la página Información general , copie el valor de Id. de aplicación.

   El ID de objeto es el mismo que se muestra para la identidad gestionada asignada por el sistema. Guarda tanto el ID de aplicación como el ID de objeto para configurar la autenticación de App Service.

Configuración de la autenticación de Microsoft Entra para la aplicación

1. En Azure Portal, vaya a la aplicación de App Service.

2. En el menú izquierdo de la aplicación, seleccione Configuración>Autenticación y, a continuación, seleccione Agregar proveedor de identidades.

3. En la página Agregar un proveedor de identidades , seleccione Microsoft como proveedor de identidades para crear un nuevo registro de aplicaciones.

4. En Restringir acceso, seleccione Requerir autenticación.

5. En Comprobaciones adicionales, en Requisitos de aplicación cliente, seleccione Permitir solicitudes de aplicaciones cliente específicas.

6. Selecciona el icono del lápiz y configura las aplicaciones cliente permitidas:

   • Añade el identificador de aplicación que copiaste en Buscar los identificadores de identidad administrada del recurso Foundry principal. Este identificador permite los tokens solicitados por la identidad del recurso Foundry primario.
   • Si la app admite el inicio de sesión interactivo en el navegador, también añade el identificador de aplicación (cliente) de la propia aplicación de Microsoft Entra para la autenticación de App Service. Este ID permite que se emitan tokens a la aplicación web durante el inicio de sesión del usuario. Si vas a crear un nuevo registro en la app, añade este ID después de crear el proveedor de identidad.

7. Configurar requisito de identidad:

   • Para la política más restrictiva en un endpoint invocado solo por Foundry, seleccione “Permitir solicitudes de identidades específicas”. Selecciona el icono del lápiz y añade el identificador de objeto de la identidad principal del recurso Foundry.
   • Si la app también permite iniciar sesión interactivo en el navegador, selecciona Permitir solicitudes desde cualquier identidad para que los usuarios inquilinos no queden bloqueados. Esta configuración no permite acceso anónimo. Las solicitudes deben seguir conteniendo un token válido de una aplicación cliente permitida y del inquilino configurado.

8. Para el requisito de inquilino, selecciona Permitir solicitudes solo del inquilino emisor. La identidad del recurso principal de Foundry y cualquier usuario que inicie sesión debe estar en este tenant.

9. Configurar solicitudes no autenticadas:

   • Si la app solo sirve a clientes API, selecciona HTTP 401 No autorizado: recomendado para APIs.
   • Si la aplicación admite el inicio de sesión interactivo en el navegador, selecciona HTTP 302 Found redirect y luego selecciona Microsoft como proveedor de redirección.

10. Seleccione Agregar para crear el proveedor de identidades.

    La siguiente imagen muestra la configuración más estrecha solo de Foundry.

    

11. Si la app admite inicio de sesión interactivo en el navegador, edita el proveedor y asegúrate de que la tienda de Tokens esté habilitada. Si creaste un nuevo registro de aplicación, añade su ID de aplicación a las aplicaciones del cliente permitidas.

Necesitas ambos IDs de aplicación cuando la app admite inicio de sesión interactivo en el navegador. Una API exclusiva de Foundry requiere solo el ID de aplicación de la identidad de recurso de Foundry padre.

Actualizar el id. de aplicación de registro de la aplicación URI

Un URI de ID de aplicación identifica la API protegida como un recurso OAuth. Para una herramienta OpenAPI de identidad gestionada, la audiencia debe coincidir exactamente con un URI de ID de aplicación registrado en la aplicación de autenticación de servicio de aplicaciones Microsoft Entra. Foundry utiliza ese valor como audiencia cuando solicita un token de acceso con la identidad del recurso principal de Foundry.

El ID de aplicación y el URI del ID de aplicación son propiedades diferentes:

• El ID de la aplicación, también llamado ID de cliente, es un GUID generado.
• Un URI de ID de aplicación es un URI que identifica una API o recurso propiedad de la aplicación. No tiene por qué contener el ID del cliente de la aplicación.

Elige un URI de ID de aplicación estable y trátalo como parte del contrato de la API:

El URI debe ser válido, único en el tenant y aceptado por la política de URI de ID de aplicación del tenant. Una cadena simple como some-random-string no es un identificador URI de aplicación válido.

Esta guía utiliza la URL completa del servicio de aplicaciones HTTPS:

https://<app-name>.azurewebsites.net

1. Una vez completada la configuración del proveedor de Microsoft, selecciónela en la columna Proveedor de identidades para abrir la página de registro de la aplicación.

2. En el menú de la izquierda, seleccione Administrar>exponer una API.

3. Junto a URI de id. de aplicación, seleccione Editar.

4. Cambia el valor a la URL HTTPS completa de tu app de App Service, como https://<app-name>.azurewebsites.net.

   Puede encontrar el nombre de host de la aplicación en la página Información general del dominio predeterminado.

5. Para un nuevo registro de aplicación, asegúrate de que la versión del token de acceso esté configurada en 2.

6. Haga clic en Guardar.

Cambiar el URI del ID de aplicación posteriormente requiere actualizar la audiencia de la herramienta Foundry y todos los demás clientes que solicitan tokens para la API.

La configuración correspondiente de autenticación de la herramienta OpenAPI es:

{
  "type": "managed_identity",
  "security_scheme": {
    "audience": "https://<app-name>.azurewebsites.net"
  }
}

No necesitas indicar el público de la herramienta en Audiencias de token permitidas. La autenticación de App Service reconoce identificadores de recursos que registras en su aplicación Microsoft Entra. Por el contrario, agregar un valor únicamente a Allowed token audiences no registra un recurso de OAuth ni permite que Microsoft Entra emita un token para ese recurso.

No uses el endpoint del proyecto Foundry ni el ID del cliente del servicio de aplicaciones como audiencia a menos que también configures ese valor exacto como el URI del ID de la aplicación. Otros formatos válidos de URI de identificador de aplicación, incluidos los URI api://, funcionan cuando el valor registrado y el valor de audiencia coinciden exactamente. Para casos límite relacionados, véase Preguntas frecuentes.

Configurar la API protegida de forma declarativa

Utiliza Bicep para configurar la API protegida y la política de autenticación de servicios de aplicaciones. El siguiente patrón asume:

• webApp es el recurso del Servicio de Aplicaciones.
• entraAppes un módulo que crea la aplicación de autenticación de servicios de aplicaciones Microsoft Entra.
• foundryAccountClientId es el identificador de aplicación de la identidad del recurso Foundry primario.
• appServiceAuthCredentialSettingName es el nombre de la configuración de la app que contiene el secreto del cliente de autenticación de App Service existente.

En el módulo de aplicación Microsoft Graph Bicep, configura la URL del Servicio de Aplicaciones como URI de identificador y solicita tokens de acceso versión 2:

extension microsoftGraphV1

param environmentName string
param appServiceUrl string

resource app 'Microsoft.Graph/applications@v1.0' = {
  uniqueName: 'my-app-${environmentName}'
  displayName: 'My app (${environmentName})'
  signInAudience: 'AzureADMyOrg'
  identifierUris: [
    appServiceUrl
  ]
  api: {
    requestedAccessTokenVersion: 2
  }
  web: {
    homePageUrl: appServiceUrl
    redirectUris: [
      '${appServiceUrl}/.auth/login/aad/callback'
    ]
  }
}

output clientId string = app.appId
output webAppUrl string = appServiceUrl

El siguiente authsettingsV2 ejemplo permite tanto iniciar sesión interactivamente por el navegador como llamadas a Foundry OpenAPI:

@description('Parent Foundry resource identity application ID')
param foundryAccountClientId string = ''

resource webAppAuthSettings 'Microsoft.Web/sites/config@2024-11-01' = {
  name: '${webApp.name}/authsettingsV2'
  properties: {
    platform: {
      enabled: true
    }
    globalValidation: {
      requireAuthentication: true
      unauthenticatedClientAction: 'RedirectToLoginPage'
      redirectToProvider: 'azureActiveDirectory'
    }
    identityProviders: {
      azureActiveDirectory: {
        enabled: true
        registration: {
          clientId: entraApp.outputs.clientId
          clientSecretSettingName: appServiceAuthCredentialSettingName
          openIdIssuer: 'https://login.microsoftonline.com/${tenant().tenantId}/v2.0'
        }
        validation: {
          allowedAudiences: [
            'api://${entraApp.outputs.clientId}'
          ]
          defaultAuthorizationPolicy: {
            allowedApplications: concat(
              [
                entraApp.outputs.clientId
              ],
              empty(foundryAccountClientId) ? [] : [foundryAccountClientId]
            )
            allowedPrincipals: {}
          }
        }
      }
    }
    login: {
      tokenStore: {
        enabled: true
      }
    }
    httpSettings: {
      requireHttps: true
    }
  }
}

Pase el ID de aplicación de la identidad del recurso de Foundry mediante la CLI para desarrolladores de Azure (AZD):

{
  "foundryAccountClientId": {
    "value": "${AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID=}"
  }
}

Luego configura el entorno y vuelve a desplegar:

azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision

Configuración de la herramienta OpenAPI en Microsoft Foundry

1. De nuevo en el portal de Foundry, seleccione su agente.

2. Busque la herramienta OpenAPI y seleccione ...>Editar.

3. Verifica que la caja de esquema OpenAPI 3.0+ contenga el esquema de tu app de App Service. Si no es así, pega tu esquema OpenAPI. Para obtener más información, consulte Uso de OpenAPI con el servicio Foundry Agent.

4. En Método de autenticación, seleccione Identidad administrada.

5. Para Audiencia, introduce el URI del ID de aplicación que configuraste antes. Para la configuración de esta guía, utiliza la URL HTTPS completa de tu app de Servicio de Aplicaciones, como https://<app-name>.azurewebsites.net. Los valores deben coincidir exactamente.

6. Seleccione Actualizar herramienta.

Prueba del agente

1. En el portal de Foundry, seleccione su agente y seleccione Probar en la zona de pruebas.

2. Chatear con el agente para probar los puntos de conexión de OpenAPI. Por ejemplo:

   • Muéstrame todas las tareas.
   • Cree una tarea denominada "Comprar comestibles".
   • Actualice esa tarea a "Comprar comestibles y cocinar cena".

Si configuras correctamente la autenticación, el agente llama a las APIs de tu app a través de la herramienta OpenAPI.

Preguntas más frecuentes

¿Por qué puedo guardar la herramienta OpenAPI antes de configurar la autorización de los servicios de aplicaciones?

Cuando guardas una herramienta OpenAPI, Foundry valida su esquema, formato de audiencia y definición. No llama al endpoint del servicio de aplicaciones. Por tanto, puedes guardar la herramienta antes de añadir la identidad del recurso principal de Foundry a la lista de permisos del servicio de aplicaciones.

Configura la lista de permisos antes de invocar la herramienta en el playground o en tiempo de ejecución. Hasta entonces, el servicio de aplicaciones rechaza llamadas a herramientas.

¿Por qué a veces falla la audiencia por defecto api://<client-id> ?

El portal de Servicios de Aplicaciones suele crear una aplicación Microsoft Entra con api://<application-client-id> como URI de ID de aplicación. En ese caso, Foundry puede aprovechar el mismo valor que su público.

El aprovisionamiento personalizado o declarativo puede dejar vacía la colección identifierUris de la aplicación Microsoft Entra incluso cuando la autenticación de App Service muestre api://<client-id> en Audiencias de token permitidas. En ese estado, Foundry no puede obtener un token de identidad gestionado para ese valor porque no es un identificador de recurso registrado.

Para solucionar el problema, utiliza una de estas opciones:

• Registra api://<client-id> como el URI de identificador de la aplicación y úsalo como audiencia para Foundry.
• Registra la URL HTTPS del servicio de aplicaciones como el URI del ID de la aplicación y usa esa URL como audiencia de Foundry.

No soluciones la discrepancia añadiendo cadenas arbitrarias a allowedAudiences.

¿Puede funcionar la autenticación de App Service sin un URI de ID de aplicación?

El inicio de sesión interactivo del navegador puede funcionar sin un URI de ID de aplicación porque el flujo del navegador utiliza un token ID para el ID de cliente de la aplicación web.

El flujo OpenAPI de identidad gestionada por Foundry necesita un token de acceso para un recurso de API registrado. Para este flujo, configura un URI de ID de aplicación y utiliza el mismo valor que la audiencia de la herramienta.

Resolución de problemas de autenticación y autorización

La herramienta OpenAPI recibe HTTP 401

Una respuesta HTTP 401 significa que la autenticación de App Service no pudo autenticar la solicitud. Las causas probables incluyen:

• No seleccionaste identidad gestionada para la herramienta OpenAPI.
• La audiencia no coincide exactamente con el URI del ID de aplicación de Microsoft Entra.
• El emisor o inquilino del token no coincide con la autenticación de App Service.
• No configuraste el URI del ID de aplicación en la aplicación Microsoft Entra.

Verifica que la audiencia de OpenAPI coincida exactamente con un URI del identificador de aplicación registrado. Para la configuración de esta guía, el valor es la URL HTTPS completa del servicio de aplicaciones.

La herramienta OpenAPI recibe HTTP 403

Una respuesta HTTP 403 significa que la autenticación ha tenido éxito, pero las comprobaciones de autorización rechazaron al llamante. Las causas probables incluyen:

• Añadiste la identidad del proyecto Foundry a la lista de permisos en lugar de la identidad del recurso principal de Foundry.
• Has introducido el ID del objeto donde la autenticación por App Service requiere un ID de aplicación.
• No añadiste el ID de la aplicación de recurso principal a allowedApplications.
• No añadiste el ID del objeto de recurso padre a la lista de identidades permitidas para una configuración solo de Foundry.

Inspecciona las reclamaciones del token de acceso:

• azp debe coincidir con el identificador de aplicación de la identidad del recurso Foundry primario.
• oid debe ser igual al identificador de objeto de la identidad del recurso Foundry principal.

Los usuarios del navegador reciben HTTP 403 tras iniciar sesión

Para una aplicación que permita iniciar sesión interactivo en el navegador, verifica estos ajustes:

• El ID de cliente propio de la aplicación web permanece en allowedApplications.
• El requisito de identidad permite usuarios normales de inquilinos.
• Las solicitudes de navegador no autenticadas usan HTTP 302 en lugar de HTTP 401.

La herramienta funciona de forma anónima pero falla una vez habilitada la autenticación

Actualiza la herramienta de Anónimo a identidad administrada, configura la audiencia como un URI de identificador de aplicación registrado y permite la identidad del recurso Foundry primario.

Limpieza de recursos

Cuando eliminas o reemplazas recursos de este escenario:

• Quita la identidad del recurso Foundry primario de la autenticación de App Service cuando elimines o sustituyas el recurso Foundry.
• Elimina la aplicación Microsoft Entra de autenticación de Servicio de Aplicaciones cuando elimines permanentemente la aplicación de Servicio de Aplicaciones. Este paso también evita el riesgo, descrito anteriormente, de que el URI del identificador de la aplicación quede huérfano.
• Si usas una credencial de identidad asignada por el usuario y una credencial de identidad federada para autenticación sin servicios de aplicaciones secretas, elimina esa identidad y la credencial federada con la app.

Contenido relacionado

• Configuración de una aplicación de App Service o Azure Functions para usar el inicio de sesión de Microsoft Entra
• Integración de la inteligencia artificial en las aplicaciones de Azure App Service
• ¿Qué es Foundry Agent Service?