Control de acceso de nivel de documento en Búsqueda de Azure AI

Note

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Importante

Estas características y funcionalidades forman parte de la API REST 2026-08-01-preview. El 2026-08-01-preview tiene licencia para usted como parte de su suscripción de Azure y está sujeto a los términos aplicables a "versiones preliminares" en los términos del producto de Microsoft, el complemento de protección de datos de productos y servicios de Microsoft ("DPA") y los términos de uso complementarios para las versiones preliminares de Microsoft Azure.

La 2026-08-01-preview admite conexiones a otros servicios de Microsoft y de terceros. El uso de estos servicios está sujeto a sus respectivos términos y podría dar lugar a procesamiento o almacenamiento de datos fuera del límite de cumplimiento de Azure, así como a los datos que fluyen a los límites de cumplimiento de Azure.

2026-08-01-preview no puede modificar los permisos de acceso establecidos fuera de la versión 2026-08-01-preview. Si usa la versión preliminar 2026-08-01-preview con contenido con restricciones de acceso o permisos, se produce un retraso antes de que la versión preliminar 2026-08-01-preview reconozca los cambios en esas restricciones de acceso o permisos.

Es su responsabilidad gestionar si sus datos se transfieren fuera de los límites de cumplimiento normativo y geográficos de su organización, así como cualquier implicación asociada, y garantizar que se establezcan los permisos, límites y aprobaciones adecuados.

Es responsable de revisar y probar cuidadosamente las aplicaciones que compile en el contexto de sus casos de uso específicos y de tomar todas las decisiones y personalizaciones adecuadas. Esta responsabilidad incluye la implementación de sus propias mitigaciones de inteligencia artificial responsable, como metaprompts, filtros de contenido u otros sistemas de seguridad, y garantizar que las aplicaciones cumplan los estándares de calidad, confiabilidad, seguridad y confiabilidad adecuados. Para obtener más información, consulte la nota de transparencia Búsqueda de Azure AI.

Búsqueda de Azure AI admite el control de acceso de nivel de documento, lo que permite a las organizaciones aplicar permisos específicos en el nivel de documento, desde la ingesta de datos a través de la ejecución de consultas. Esta funcionalidad es esencial para crear sistemas agente de IA seguros que basen datos, aplicaciones de generación aumentada por recuperación (RAG) y soluciones de búsqueda empresarial que requieren comprobaciones de autorización en el nivel de documento.

Enfoques para el control de acceso de nivel de documento

Búsqueda de Azure AI proporciona cuatro enfoques principales para aplicar permisos de nivel de documento, cada uno adecuado para diferentes orígenes de datos y modelos de identidad.

Enfoque Descripción
Filtros de seguridad Comparación de cadenas. La aplicación utiliza una identidad de usuario o grupo en forma de cadena, que se utiliza para aplicar un filtro en una consulta, excluyendo cualquier documento que no coincida con la cadena.

Los filtros de seguridad son una técnica para lograr el control de acceso de nivel de documento. Este enfoque no está enlazado a una API para que pueda usar cualquier versión o paquete.
Ámbitos de ACL o RBAC similares a POSIX (versión preliminar) La entidad de seguridad de Microsoft Entra asociada al token de consulta se compara con los metadatos de permisos de los documentos devueltos en los resultados de búsqueda, excluidos los documentos que no coincidan con los permisos. Los permisos de lista de control de acceso (ACL) se aplican a directorios y archivos de Azure Data Lake Storage (ADLS) Gen2. Los ámbitos de control de acceso basado en rol (RBAC) se aplican al contenido de ADLS Gen2 y a Azure blobs.

La compatibilidad integrada con el acceso basado en identidades a nivel de documento está en versión preliminar, disponible en las API REST y en los paquetes de la versión preliminar del SDK de Azure que proporcionan esta función. Para obtener evidencia de compatibilidad con características, consulte los detalles de compatibilidad de la versión del SDK.
etiquetas de confidencialidad de Microsoft Purview (versión preliminar) Indexador extrae etiquetas de confidencialidad definidas en Microsoft Purview de orígenes de datos admitidos (Azure Blob Storage, ADLS Gen2, SharePoint en Microsoft 365, OneLake). Estas etiquetas se almacenan como metadatos y se evalúan en tiempo de consulta para controlar el acceso de los usuarios en función de los tokens de Microsoft Entra y las asignaciones de directivas de Purview. Las etiquetas también se exponen a través de fuentes de conocimiento y de la respuesta de recuperación agéntica, lo que permite que los agentes de IA y las aplicaciones de chat que consumen una base de conocimiento reciban el mismo filtrado en función de las etiquetas. Este enfoque alinea la autorización de Búsqueda de Azure AI con el modelo de Microsoft Information Protection de su empresa.
SharePoint en ACL de Microsoft 365 (versión preliminar) Los indexadores de Búsqueda de Azure AI extraen metadatos de permisos del contenido de SharePoint compatible y los usan para realizar comprobaciones de acceso en tiempo de consulta. Para obtener información sobre el contenido compatible, los sujetos, las relaciones entre grupos, el comportamiento de sincronización y los permisos, consulta Utilizar un indexador de SharePoint para incorporar metadatos de permisos.

En el caso de los orígenes de conocimiento indexados, ingestionPermissionOptions no se puede combinar con assetStore. Por lo tanto, el servicio de imágenes (versión preliminar) no está disponible cuando está habilitada la ingesta de permisos de nivel de documento nativo.

Elección de un enfoque

Use los criterios siguientes para identificar el enfoque que mejor se adapte a los requisitos de origen de datos, modelo de identidad y cumplimiento.

Escenario Enfoque recomendado Por qué
Sistema de identidad personalizado, marco de seguridad que no sea de Microsoft o cualquier índice de tipo push. Filtros de seguridad Independiente de la API, disponible con carácter general y basado en coincidencias de cadenas simples.
Contenido en ADLS Gen2 o Azure Blob Storage con asignaciones de ACL o RBAC existentes. Ámbitos de ACL y RBAC similares a POSIX Integración nativa de Microsoft Entra; la aplicación de permisos en tiempo de consulta se basa en metadatos de permisos escritos en el índice por el mecanismo de sincronización documentado.
El contenido empresarial ya está sujeto a las directivas de protección de la información de Microsoft Purview. Etiquetas de confidencialidad de Microsoft Purview Reutiliza las asignaciones centralizadas de clasificación y directiva en Búsqueda de Azure AI.
Contenido procedente de SharePoint en Microsoft 365 (bibliotecas, listas, páginas de sitio ASPX). SharePoint en ACL de Microsoft 365 Respeta los permisos de SharePoint nativos, incluidos los grupos de sitios de SharePoint.

Patrón para el recorte de seguridad mediante filtros

En escenarios en los que la integración de ámbitos de ACL/RBAC nativos no es viable, use filtros de cadena de seguridad para recortar los resultados en función de los criterios de exclusión. El patrón incluye los siguientes componentes:

  • Para almacenar identidades de usuario o grupo, cree un campo de cadena en el índice.
  • Cargue el índice usando documentos de origen que incluyan listas de control de acceso (ACLs) asociadas.
  • Incluya una expresión de filtro en la lógica de consulta para buscar coincidencias en la cadena.
  • En el momento de la consulta, obtenga la identidad del autor de la llamada.
  • Pase la identidad del autor de la llamada como cadena de filtro.
  • Los resultados se recortan para excluir cualquier coincidencia que no incluya la cadena de identidad de usuario o grupo.

Puede usar API del modelo de inserción o extracción. Dado que este enfoque es independiente de la API, solo tiene que confirmar que el índice y la consulta tienen cadenas válidas (identidades) para el paso de filtración.

Este enfoque es útil para los sistemas con modelos de acceso personalizados o marcos de seguridad que no son Microsoft. Para obtener más información sobre este enfoque, consulte Filtros de seguridad para recortar los resultados en Búsqueda de Azure AI.

Patrón para la compatibilidad nativa con permisos de ámbito de ACL y RBAC similares a POSIX (versión preliminar)

El soporte nativo se basa en usuarios y grupos de Microsoft Entra asociados con documentos que desea indexar y consultar.

los contenedores de Azure Data Lake Storage (ADLS) Gen2 admiten ACL en el contenedor y en archivos. Para ADLS Gen2, la conservación del ámbito de RBAC en el nivel de documento se admite de forma nativa cuando se usa un indexador de ADLS Gen2 o un origen de conocimiento de blobs (admite ADLS Gen2) y una API en versión preliminar para ingerir contenido. En el caso de los blobs de Azure que usan el Indexador de blobs de Azure o la fuente de conocimiento, la conservación del ámbito de RBAC se preserva a nivel de contenedor.

En el caso del contenido protegido por ACL, use el acceso de grupo a través del acceso de usuario individual para facilitar la administración. El patrón incluye los siguientes componentes:

La aplicación cliente recibe permisos de lectura para el índice a través del rol Lector de datos de índice de búsqueda o Colaborador de datos de índice de búsqueda . El acceso en el momento de la consulta viene determinado por los metadatos de permisos de usuario o grupo en el contenido indexado. Las consultas que incluyen un filtro de permisos pasan un token de usuario o grupo como x-ms-query-source-authorization en el encabezado de solicitud. Al usar filtros de permisos en el momento de la consulta, Búsqueda de Azure AI comprueba dos cosas:

  • En primer lugar, comprueba si hay permiso lector de datos de índice de búsqueda que permite que la aplicación cliente acceda al índice.

  • En segundo lugar, dado el token adicional en la solicitud, comprueba si hay permisos de usuario o grupo en los documentos que se devuelven en los resultados de búsqueda, excluyendo aquellos que no coinciden.

Para incluir los metadatos de permisos en el índice, utiliza la API del modelo push, enviando cualquier documento JSON al índice de búsqueda, donde la carga útil incluye un campo de cadena que proporciona listas de control de acceso (ACL) de tipo POSIX para cada documento. La diferencia importante entre este enfoque y el recorte de seguridad es que los metadatos del filtro de permisos en el índice y la consulta se reconocen como autenticación de Microsoft Entra ID, mientras que la solución alternativa de recorte de seguridad es una comparación de cadenas sencilla. Además, puede usar el SDK de Graph para recuperar las identidades.

También puede usar las API del modelo de extracción (indexador) si el origen de datos es Azure Data Lake Storage (ADLS) Gen2 y el código llama a una API en versión preliminar para la indexación.

Recuperación de metadatos de permisos de ACL durante el proceso de ingesta de datos (versión preliminar)

La forma de recuperar los permisos de ACL varía en función de si se inserta una carga de documentos o se usa el indexador ADLS Gen2.

Comience con una API en versión preliminar que proporcione la característica:

Para el enfoque del modelo de inserción:

  1. Confirme que el esquema de índice se crea con un SDK de versión preliminar o preliminar y que el esquema tiene filtros de permisos.
  2. Considere la posibilidad de usar el SDK de Microsoft Graph para obtener identidades de grupo o usuario.
  3. Use la API Index Documents o SDK de Azure equivalente para insertar documentos y sus metadatos de permisos asociados en el índice de búsqueda.

Para el enfoque del indexador de ADLS Gen2 del modelo de incorporación de cambios o fuente de conocimiento de Blob (ADLS Gen2):

  1. Compruebe que los archivos del directorio están protegidos mediante el modelo de control de acceso de ADLS Gen2.
  2. Use Indexers- Create (API REST), Knowledge Sources - Create (API REST) o una API de SDK de Azure equivalente para crear el indexador, el índice y el origen de datos.

Si el conjunto de aptitudes fragmenta documentos, como con la aptitud División de texto para vectorización integrada, los campos de metadatos de permisos pasan de las asignaciones de campos del indexador a las proyecciones de índice. Consulte Elegir dónde rellenar los campos de ACL.

Patrón de SharePoint en Microsoft 365 para la ingestión básica de permisos ACL (versión preliminar)

En el caso del contenido SharePoint indexado, Búsqueda de Azure AI puede almacenar los permisos de origen como metadatos y usarlos para filtrar los resultados de la consulta. Puede acceder a esta funcionalidad en versión preliminar a través del SharePoint en Microsoft 365 indexador y la API REST más reciente o un paquete de SDK de versión preliminar equivalente.

Para conocer los requisitos de permisos, las relaciones de grupo admitidas, la sincronización de permisos y las limitaciones, consulte Uso de un indexador de SharePoint para ingerir metadatos de permisos.

Si el conjunto de habilidades divide los documentos en fragmentos (por ejemplo, con la habilidad de división de texto para la vectorización integrada), los campos ACL se trasladan de las asignaciones de campos del indexador a las proyecciones de índice. Consulte Elegir dónde rellenar los campos de ACL.

Patrón para etiquetas de confidencialidad de Microsoft Purview (versión preliminar)

Al habilitar la ingesta de etiquetas, Búsqueda de Azure AI extrae metadatos de confidencialidad de los orígenes de datos admitidos. Estos orígenes de datos incluyen Azure Blob Storage, Azure Data Lake Storage Gen2 (ADLS Gen2), SharePoint en Microsoft 365 y Microsoft OneLake. Las etiquetas extraídas se almacenan en el índice junto con el contenido del documento.

En el momento de la consulta, Búsqueda de Azure AI comprueba la etiqueta de confidencialidad de cada documento, el token de Microsoft Entra del usuario y las directivas de Purview de la organización para determinar el acceso. El sistema devuelve documentos solo si la identidad del usuario y los permisos basados en etiquetas permiten el acceso en las directivas de Purview configuradas.

Este patrón incluye los siguientes componentes:

  • Configure el índice, el origen de datos y el indexador (con fines de programación) mediante la API REST de versión preliminar más reciente o un SDK de versión preliminar que admita la ingesta de etiquetas de Purview.
  • Habilite una identidad administrada asignada por el sistema en el servicio de búsqueda. Las identidades administradas asignadas por el usuario no son compatibles con la extracción de etiquetas de Purview; la propia identidad del servicio debe tener los permisos elevados de Purview. A continuación, haga que el administrador global de inquilinos o el administrador de roles con privilegios conceda el acceso necesario para permitir que el servicio de búsqueda se autentique con Microsoft Purview y extraiga metadatos de etiqueta.
  • Aplique etiquetas de confidencialidad a documentos antes de la indexación para que el sistema pueda reconocerlas y conservarlas durante la ingesta.
  • En el momento de la consulta, adjunte un token de Microsoft Entra válido a través del encabezado x-ms-query-source-authorization a cada solicitud de consulta. Búsqueda de Azure AI evalúa el token y los metadatos de etiqueta asociados para aplicar el control de acceso basado en etiquetas.

La aplicación de etiquetas de confidencialidad de Purview se limita a escenarios de inquilino único y requiere autenticación RBAC. Durante la versión preliminar, solo se admite a través de la API REST y SDK de Azure. Las API de Autocomplete y Suggest no están disponibles actualmente para los índices con Purview habilitado.

Dónde se muestran las etiquetas de confidencialidad

Para que el sistema pueda aplicar etiquetas en el momento de la consulta o devolverlas en las respuestas de recuperación, primero debe sincronizar los metadatos de la etiqueta en el índice. Ambas vías de consumo descritas en esta sección dependen de este paso de sincronización. Puede sincronizar etiquetas configurando un indexador de Búsqueda de Azure AI directamente en un origen de datos compatible o habilitando la opción de ingesta equivalente al crear un origen de conocimiento. En ambos casos, su entorno debe cumplir los requisitos previos de configuración de sincronización de metadatos de etiquetas de confidencialidad (identidad administrada, RBAC en el servicio de búsqueda y los permisos necesarios de Microsoft Purview y origen de datos). Para obtener la configuración integral del indexador, consulte Usar indexadores de Búsqueda de Azure AI para ingerir etiquetas de confidencialidad de Microsoft Purview. Para la ingesta basada en el origen de conocimiento, configure ingestionPermissionOptions para incluir sensitivityLabel durante la creación del origen de conocimiento.

Después de sincronizar las etiquetas, dos rutas de consulta utilizan los mismos metadatos indexados de las etiquetas. Elija la ruta de acceso que coincida con la forma en que la aplicación llama Búsqueda de Azure AI:

Si la fuente de conocimiento apunta a un índice fragmentado, como uno creado mediante vectorización integrada o una habilidad personalizada de división de texto, el conjunto de habilidades también debe proyectar la etiqueta de confidencialidad en cada fila del fragmento. Sin esta proyección, no se filtran las referencias de nivel de fragmento.

Para obtener más información, consulte Indexadores de Búsqueda de Azure AI para ingerir etiquetas de confidencialidad de Microsoft Purview.

Aplicar permisos a nivel de documento en tiempo de consulta

La aplicación de consultas basadas en tokens es una capacidad transversal que se aplica a los ámbitos de las ACL de tipo POSIX y del modelo RBAC, a las etiquetas de confidencialidad de Microsoft Purview y a los patrones de ACL de SharePoint en Microsoft 365. Mediante la consulta nativa basada en tokens, Búsqueda de Azure AI valida el token de Microsoft Entra del autor de la llamada en cada solicitud y recorta los conjuntos de resultados en solo los documentos que el autor de la llamada tiene autorización para leer según las ACL del documento, siempre y cuando los metadatos de la ACL del documento se sincronicen con el índice.

Al adjuntar el token del usuario a una solicitud de consulta a través del encabezado x-ms-query-source-authorization, Búsqueda de Azure AI:

  1. Extrae las declaraciones de usuario, grupo y alcance del token.
  2. Compara esas reclamaciones con los metadatos de permisos almacenados junto a los documentos indexados (entradas de ACL, ámbitos de RBAC, asignaciones de etiquetas de Purview o ACL de SharePoint).
  3. Devuelve solo los documentos cuyos metadatos de permisos sincronizados conceden acceso al autor de la llamada.

La aplicación de permisos en tiempo de consulta compara las solicitudes de Microsoft Entra del autor de la llamada con los metadatos de permisos que ya están almacenados en el índice. Los cambios de permisos en el sistema de origen (Microsoft Entra pertenencia a grupos, ADLS Gen2 ACL, asignaciones de etiquetas de Purview o ACL de SharePoint) solo se reflejan en los resultados de búsqueda después de que los metadatos se sincronicen con el índice a través del mecanismo específico del origen, por ejemplo, una ejecución posterior del indexador, una actualización push-API o una actualización controlada por Purview. Para SharePoint, los cambios de ACL en los elementos con permisos únicos se detectan de forma incremental en cada ejecución correcta del indizador a partir de la API REST en versión preliminar 2026-05-01-preview, mientras que los cambios heredados de ámbitos superiores (sitio, biblioteca, lista o carpeta) requieren una actualización explícita. Para obtener más información, vea Sincronizar permisos entre contenido indexado y de origen.

Para conocer los pasos para la implementación integral de consultas, consulte Aplicación de ACL y RBAC en tiempo de consulta en Búsqueda de Azure AI.

Ventajas del control de acceso de nivel de documento

El control de acceso de nivel de documento nativo en Búsqueda de Azure AI ofrece ventajas concretas sobre el filtrado del lado de la aplicación:

  • Elimina el código de permisos personalizado: No es necesario implementar la resolución de grupos anidados, el recorrido de ACL multinivel ni el recorte posterior a la consulta en la aplicación. Búsqueda de Azure AI controla la comparación y el filtrado durante la ejecución de consultas.
  • Se alinea con los controles de cumplimiento existentes: La reutilización de los metadatos de permisos de Microsoft Entra, Microsoft Purview y SharePoint ayuda a mantener los resultados de búsqueda alineados con el sistema de identidad de origen. Revise el modelo de sincronización de permisos para cada origen para comprender sus limitaciones.
  • Respeta los permisos de origen tras cada sincronización de ACL: En los enfoques basados en tokens (ámbitos de ACL y RBAC, etiquetas de Purview y ACL de SharePoint), la aplicación en tiempo de consulta utiliza los metadatos de permisos que el mecanismo de sincronización específico del origen documentado (ejecución del indexador, actualización mediante la API de envío o actualización de Purview) ya ha escrito en el índice.
  • Mejora el rendimiento frente al recorte posterior a la consulta: El filtrado dentro de la canalización de búsqueda es más rápido que cargar conjuntos de resultados más grandes en la aplicación y recortar allí, especialmente en grandes volúmenes de consultas.
  • Reutiliza su infraestructura de identidad existente: las identidades de Microsoft Entra y SharePoint siguen siendo la fuente de verdad para las decisiones de acceso, lo que reduce la duplicación de identidades y la carga operativa que supone mantener un almacén de permisos paralelo.

Tutoriales y ejemplos

Explore el control de acceso de nivel de documento en Búsqueda de Azure AI con más artículos y ejemplos.

Contenido relacionado

  • Last updated on