Aplicación en tiempo de consulta de etiquetas de confidencialidad de Microsoft Purview en Búsqueda de Azure AI (versión preliminar)

En el momento de la consulta, Búsqueda de Azure AI puede aplicar directivas de etiqueta de confidencialidad definidas en Microsoft Purview. Estas directivas incluyen la evaluación de los derechos deEXTRACT uso asociados a cada documento, lo que garantiza que los usuarios solo puedan recuperar documentos a los que tienen permiso para acceder.

Esta funcionalidad amplía control de acceso a nivel de documento para alinearse con los requisitos de protección y cumplimiento de información de su organización administrados en Microsoft Purview.

Cuando se habilita la indexación de etiquetas de confidencialidad de Purview, Búsqueda de Azure AI comprueba los metadatos de etiqueta de cada documento durante el tiempo de consulta. Aplica filtros de acceso basados en directivas de Purview para devolver solo los resultados a los que puede acceder el usuario solicitante.

En este artículo se explica cómo funciona la aplicación de etiquetas de confidencialidad en tiempo de consulta y cómo emitir consultas de búsqueda seguras.

Requisitos previos

• Complete todos los pasos descritos en Uso de indizadores de Búsqueda de Azure AI para ingerir etiquetas de confidencialidad de Microsoft Purview.

• Tanto el servicio Búsqueda de Azure AI como el usuario que emite la consulta deben estar en el mismo inquilino Microsoft Entra.

• API REST versión 2025-11-01-preview o un paquete del SDK de versión preliminar equivalente para consultar el índice. La funcionalidad de lectura con privilegios elevados y el registro de auditoría de Purview requieren 2026-05-01-preview o una versión posterior.

• Autentique las consultas mediante Azure control de acceso basado en rol (RBAC), no claves de API. Cuando las etiquetas de confidencialidad de Purview están habilitadas, el acceso a la clave de API está restringido a la recuperación del esquema de índice.

Limitaciones

• No se admiten las cuentas de invitado ni las consultas entre inquilinos.

• Las API de Autocompletar y Suggest no se admiten para los índices habilitados para Purview.

• Si se produce un error en la evaluación de etiquetas (por ejemplo, las API de Purview no están disponibles temporalmente), el servicio devuelve 5xx y no devuelve un conjunto de resultados parcial o sin filtrar.

• El sistema evalúa las etiquetas solo tal como existían en el momento de la última ejecución del indexador. Es posible que los cambios de etiqueta recientes no se reflejen hasta la siguiente reindexación programada.

Cómo funciona la aplicación de la confidencialidad de las etiquetas en tiempo de consulta

Al consultar un índice que incluye etiquetas de confidencialidad de Microsoft Purview, Búsqueda de Azure AI comprueba las directivas de Purview asociadas antes de devolver los resultados. De este modo, la consulta devuelve solo los documentos a los que se permite el acceso del token de usuario.

1. Entrada de identidad de usuario y rol de aplicación

En el momento de la consulta, Búsqueda de Azure AI valida ambas:

• El rol de RBAC de la aplicación que realizar la llamada, que se indica en el encabezado Authorization. El rol mínimo necesario es Search Index Data Reader. Para obtener más información, revise la guía Búsqueda de Azure AI RBAC.
• La identidad del usuario mediante el token, proporcionada en el x-ms-query-source-authorization del encabezado.

Ambos son necesarios para autorizar la visibilidad basada en etiquetas.

2. Evaluación de etiquetas de sensibilidad

Cuando se recibe una solicitud de consulta, Búsqueda de Azure AI evalúa:

1. Campo sensitivityLabel de cada documento indexado (extraído de Microsoft Purview durante la ingesta).
2. Los permisos efectivos de Purview del usuario, definidos por Microsoft Entra ID y la directiva de etiquetas de Purview.

Si el usuario no está autorizado para la etiqueta de confidencialidad de un documento con EXTRACT permisos, ese documento se excluye de los resultados de la consulta.

3. Filtrado seguro de resultados

Búsqueda de Azure AI aplica el filtro de seguridad después de todos los filtros definidos por el usuario y los pasos de puntuación.
Solo se incluye un documento en el conjunto de resultados final si:

• La aplicación que realiza la llamada tiene una asignación de roles válida (a través de RBAC) y
• El token de identidad de usuario representado por x-ms-query-source-authorization es válido y se permite ver el contenido con la etiqueta de confidencialidad del documento.

Si se produce un error en cualquiera de las condiciones, se omite el documento de los resultados.

Adquisición de un token de acceso de usuario

Para consultar Búsqueda de Azure AI mediante el contexto de usuario, debe adquirir un token de acceso que represente al usuario que ha iniciado sesión. El enfoque que use depende de si está probando localmente con su propio token, si tiene acceso al documento de origen o implementa el flujo de aplicación que requiere pasar el token de usuario final.

Para escenarios de prueba

Para las pruebas locales, puede recuperar un token de acceso de usuario mediante CLI de Azure:

$token = az account get-access-token `
  --resource https://search.azure.com `
  --query accessToken `
  --output tsv

Este método usa la sesión de inicio de la CLI de Azure actual, para que pueda usar el contexto de los documentos que tengan asignados permisos EXTRACT a través de etiquetas de confidencialidad. Este método está pensado solo para escenarios de desarrollo y validación.

Adquisición de tokens para escenarios de OBO

Las aplicaciones que implementen el flujo con derechos delegados (OBO) deben adquirir los tokens a través de Microsoft Entra ID mediante una biblioteca de autenticación compatible, como la Biblioteca de autenticación de Microsoft (MSAL).

En escenarios de OBO, el token debe solicitarse para la API de bajada a la que llama la aplicación. Por ejemplo, al llamar a Búsqueda de Azure AI, el URI del recurso es https://search.azure.com/.default.

El parámetro de acceso .default solicita todos los permisos delegados que se han otorgado previamente en la aplicación para el recurso especificado.

Los permisos de etiqueta de confidencialidad, incluidos EXTRACT, no se representan como ámbitos de OAuth. El servicio descendente evalúa estos permisos en tiempo de ejecución, como por ejemplo Búsqueda de Azure AI, basándose en la identidad del usuario en el token y la directiva de etiqueta de confidencialidad aplicada.

Ejemplo de consulta

Este es un ejemplo de una solicitud de consulta mediante la aplicación de etiquetas de confidencialidad de Microsoft Purview.

El token de aplicación se pasa como un token de portador en el encabezado Authorization. El token de usuario se pasa como valor sin formato del token en el encabezado x-ms-query-source-authorization sin el prefijo Bearer.

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2025-11-01-preview
Authorization: Bearer {{app-query-token}}
x-ms-query-source-authorization: {{user-query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Lectura con privilegios elevados para investigaciones administrativas (versión preliminar)

La lectura elevada permite a un desarrollador autorizado devolver documentos etiquetados que el usuario que realiza la llamada normalmente no podría ver, a la vez que genera una entrada en el registro de auditoría de Microsoft Purview por cada documento devuelto por la solicitud. Úselo para revisiones de cumplimiento, eDiscovery, respuesta a incidentes y otras investigaciones administrativas en las que se requiere un registro auditable de acceso.

La lectura con privilegios elevados está disponible en los índices habilitados para Purview en la API REST versión 2026-05-01-preview y versiones posteriores.

Cómo funciona la lectura con privilegios elevados

1. La aplicación que realiza la llamada establece el x-ms-enable-elevated-read: true encabezado en la solicitud de búsqueda.

2. Búsqueda de Azure AI omite la comprobación de acceso basada en etiquetas por documento y devuelve documentos coincidentes, independientemente de los permisos de EXTRACT del usuario solicitante en cada etiqueta.

3. Para cada documento de la respuesta, Búsqueda de Azure AI emite una entrada al registro de auditoría Microsoft Purview en nombre del inquilino solicitante. Una única solicitud de búsqueda que devuelve N documentos genera N entradas de auditoría.

4. Las entradas de auditoría se cargan en Purview de forma asincrónica después de que se devuelva la respuesta de búsqueda.

Asignación de roles necesaria

El usuario desarrollador que realiza la llamada debe tener el rol Colaborador de datos de índice de búsqueda en el servicio de búsqueda o el ámbito de índice. El Lector de datos de índice de búsqueda no es suficiente. La lectura con privilegios elevados falla con 403 Forbidden si el rol no está asignado. Para obtener más información sobre los roles de Búsqueda de Azure AI, consulte Connect to Búsqueda de Azure AI using roles.

Cuando el encabezado x-ms-enable-elevated-read se establece en true, no se permite utilizar el encabezado x-ms-query-source-authorization.

Ejemplo de lectura con privilegios elevados

POST  {{endpoint}}/indexes/sensitivity-docs/docs/search?api-version=2026-05-01-preview
Authorization: Bearer {{contributor-token}}
x-ms-enable-elevated-read: true
Content-Type: application/json

{
    "search": "*",
    "select": "title,summary,sensitivityLabel",
    "orderby": "title asc"
}

Campos de auditoría enviados a Microsoft Purview

Cada entrada de auditoría sigue el esquema de la API de actividad de administración de Office 365 e incluye los siguientes campos.

Degradación correcta

Si Búsqueda de Azure AI no puede acceder a Microsoft Purview mientras procesa una consulta, por ejemplo durante una interrupción temporal de Purview, se omite la evaluación de etiquetas para esa solicitud. El comportamiento depende de si la solicitud incluye un token de identidad de usuario:

• Solicitudes de lectura con privilegios elevados (x-ms-enable-elevated-read: true): se produce un error en la solicitud con 5xx. Búsqueda de Azure AI no devuelve documentos etiquetados sin poder emitir primero registros de auditoría.

• Solicitudes estándar impuestas por etiqueta (con x-ms-query-source-authorization): La solicitud falla con 5xx. Búsqueda de Azure AI no devuelve resultados parciales o sin filtrar cuando no se pueden evaluar las directivas de etiqueta.

• Las llamadas sin x-ms-query-source-authorization emitidas por una aplicación con al menos el rol Lector de datos de índice de búsqueda: la solicitud se procesa correctamente y devuelve solo los documentos que no tienen una etiqueta de confidencialidad. Los documentos etiquetados se omiten de la respuesta.

Esta ruta de acceso degradada solo está pensada para flujos de trabajo no orientados al usuario que aceptan explícitamente resultados sin etiquetar. No confíe en ella para las experiencias de búsqueda del usuario final.

Buscar registros de auditoría de lectura con privilegios elevados en Microsoft Purview

Búsqueda de Azure AI carga entradas de auditoría en el registro de auditoría de Microsoft Purview del inquilino que realiza la llamada. Para investigar la actividad de lectura con privilegios elevados:

1. En el Microsoft Purview portal, seleccione Solutions>Audit.

2. Seleccione Audit Search y, a continuación, filtre por intervalo de fechas, usuario o el tipo de registro Búsqueda de Azure AI.

3. Abra una entrada para ver los campos de esquema estándar y los campos personalizados de Búsqueda de Azure AI, incluidos SensitivityLabelName, DocumentDataSourceType y DocumentDataSourceId.

Para obtener instrucciones paso a paso sobre cómo ejecutar búsquedas de auditoría, comportamiento de retención y roles necesarios de Purview, consulte Buscar el registro de auditoría en el portal de Microsoft Purview.

Control de etiquetas de confidencialidad en Búsqueda de Azure AI

Cuando Búsqueda de Azure AI indexa el contenido del documento con etiquetas de confidencialidad de orígenes como SharePoint, Azure Blob y otros, almacena tanto el contenido como los metadatos de la etiqueta. La consulta de búsqueda devuelve contenido indexado junto con el GUID que identifica la etiqueta de confidencialidad aplicada al documento, solo si el usuario tiene acceso a datos EXTRACT para ese documento asignado a través de la definición de etiqueta de confidencialidad. Este GUID identifica de forma única la etiqueta, pero no incluye propiedades legibles para personas, como el nombre de la etiqueta o los permisos asociados.

Tenga en cuenta que el GUID, por sí solo, es insuficiente para escenarios que incluyen la interfaz de usuario, ya que las etiquetas de sensibilidad suelen llevar otros controles de directiva aplicados por Microsoft Purview Information Protection, como permisos de impresión o restricciones de captura de pantalla y grabación de pantalla. Búsqueda de Azure AI no expone estas funcionalidades.

Para mostrar nombres de etiqueta o aplicar restricciones específicas de la interfaz de usuario, la aplicación debe llamar al punto de conexión de Microsoft Purview Information Protection para recuperar los metadatos de etiqueta completos y los permisos asociados.

Puede usar el GUID devuelto por Búsqueda de Azure AI para resolver las propiedades de etiqueta y llamar a las API de etiquetas de Purview Labels para capturar el nombre de etiqueta, la descripción y la configuración de directiva.

Configuración de pruebas de un extremo a otro

Para que le sea más fácil validar la configuración de etiquetas de confidencialidad en Búsqueda de Azure AI, consulte este modelo de configuración completo de referencia.

En este repositorio se muestra lo siguiente:

• Cómo configurar la sincronización y el respeto de etiquetas de sensibilidad en Búsqueda de Azure AI
• Cómo validar la ingesta de datos y la aplicación de directivas en tiempo de consulta en documentos con etiquetas de sensibilidad
• Cómo extraer el nombre de la etiqueta y exponerlo como parte de las fuentes de referencia usadas en las aplicaciones o agentes de RAG.