Compartir a través de

Control de acceso de nivel de documento en Azure AI Search

Azure AI Search 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 de agentes de IA seguros que fundamentan los datos, aplicaciones de Generación Retrieval-Augmented (RAG) y soluciones de búsqueda empresarial que requieren comprobaciones de autorización a nivel de los documentos.

Enfoques para el control de acceso de nivel de documento

Enfoque Descripción
Filtros de seguridad Comparación de cadena La aplicación pasa una identidad de usuario o grupo como una cadena, la cual 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 Microsoft Entra detrás del token de consulta se compara con los metadatos de permisos de los documentos devueltos en los resultados de búsqueda, excepto los documentos que no coinciden con los permisos. Los permisos de listas 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 los blobs de Azure.

La compatibilidad integrada con el acceso basado en identidades en el nivel de documento se encuentra en versión preliminar, disponible en las API de REST y en los paquetes del SDK de Azure en versión preliminar que proporcionan la característica. Asegúrese de comprobar el registro de cambios del paquete del SDK para obtener pruebas de compatibilidad con características.
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 el momento de la consulta para gestionar el acceso de los usuarios en función de los tokens de Microsoft Entra y las políticas de Purview. Este enfoque alinea la autorización de Azure AI Search con el modelo de Microsoft Information Protection de su empresa.
SharePoint en ACL de Microsoft 365 (versión preliminar) Cuando se configura, los indexadores de Azure AI Search extraen permisos de documento de SharePoint directamente desde las ACL de Microsoft 365 durante la ingesta inicial. Las comprobaciones de acceso usan las membresías de usuario y de grupo de Microsoft Entra. Los tipos de grupo admitidos incluyen grupos de seguridad de Microsoft Entra, grupos de Microsoft 365 y grupos de seguridad habilitados para correo. Los grupos de SharePoint aún no se admiten en la versión preliminar.

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, se recomiendan 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 ACL 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 de modelo de inserción o extracción. Dado que este enfoque es independiente de la API, solo tiene que asegurarse de 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 de Microsoft. Para obtener más información sobre este enfoque, consulte Filtros de seguridad para recortar resultados en Azure AI Search.

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

La compatibilidad nativa se basa en usuarios y grupos de Microsoft Entra afiliados a documentos que desea indexar y consultar.

Los contenedores de Azure Data Lake Storage (ADLS) Gen2 admiten ACL en el contenedor y en los 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, se recomienda 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, Azure AI Search 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 de la solicitud, comprueba los permisos de usuario o grupo en los documentos que se devuelven en los resultados de búsqueda, excluyendo aquellos que no coinciden.

Para obtener metadatos de permisos en el índice, puede usar la API del modelo de inserción, insertando cualquier documento JSON en el índice de búsqueda, donde la carga incluye un campo de cadena que proporciona ACL similares a 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 delmodelo de inserción:

  1. Asegúrese de que el esquema de índice también se crea con un SDK de versión preliminar o preliminar y de 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 indexar documentos o la API equivalente del SDK de Azure para insertar documentos y sus metadatos de permiso 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 la API REST Create Indexer o Create Knowledge Source REST API o la API de AZURE SDK equivalente para crear el indexador, el índice y el origen de datos.

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

Para SharePoint en el contenido de Microsoft 365, Azure AI Search puede aplicar permisos de nivel de documento basados en ACL de SharePoint. Esta integración promueve que solo los usuarios o grupos con acceso al documento de origen de SharePoint pueden recuperarlo en los resultados de búsqueda, en cuanto se sincronizan los permisos en el índice. Los permisos se aplican al índice durante la ingesta inicial de documentos.

La compatibilidad con ACL de SharePoint está disponible en versión preliminar a través del indexador de SharePoint mediante la API REST 2025-11-01-preview o el SDK compatible. El indexador extrae los metadatos de permisos de archivo y elemento de lista y lo conserva en el índice de búsqueda, donde se usa para aplicar el control de acceso en el momento de la consulta.

El patrón incluye los siguientes componentes:

  • Use el indexador de SharePoint en Microsoft 365 con permisos de aplicación para leer el contenido del sitio de SharePoint y los permisos completos para leer las ACL. Siga las instrucciones de configuración de la ACL del indexador de SharePoint para habilitar y limitaciones.
  • Durante la indexación inicial, las entradas de ACL de SharePoint (usuarios y grupos) se almacenan como metadatos de permiso en el índice de búsqueda.
  • Para la indexación incremental de ACLs, revise los mecanismos disponibles de resincronización de ACLs de SharePoint durante la versión preliminar pública.
  • En el momento de la consulta, Búsqueda de Azure AI comprueba la entidad principal de Microsoft Entra en el token de consulta contra los metadatos de ACL de SharePoint almacenados en el índice. Excluye los documentos a los que el autor de la llamada no está autorizado para acceder.

Durante la vista previa, solo se admiten los siguientes tipos de principales en las ACL de SharePoint.

  • Cuentas de usuario de Microsoft Entra
  • Grupos de seguridad de Microsoft Entra
  • Grupos de Microsoft 365
  • Grupos de seguridad habilitados para correo

Los grupos de SharePoint no se admiten en la versión preliminar.

Para obtener detalles de configuración y limitaciones completas, vea Cómo indexar SharePoint en permisos de nivel de documento de Microsoft 365 (versión preliminar).

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

Azure AI Search puede ingerir y aplicar etiquetas de confidencialidad de Microsoft Purview para el control de acceso de nivel de documento, ampliando las directivas de protección de la información de Microsoft Purview a las aplicaciones de búsqueda y recuperación.

Cuando el procesamiento de etiquetas está habilitado, Búsqueda de Azure AI extrae metadatos de confidencialidad de fuentes de datos compatibles. Estos 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, Azure AI Search 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. Los documentos solo se devuelven si la identidad del usuario y los permisos basados en etiquetas permiten el acceso en las directivas de Purview configuradas.

El 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 2025-11-01-preview o un SDK correspondiente que admita la ingesta de etiquetas de Purview.
  • Habilite una identidad administrada asignada por el sistema en el servicio de búsqueda. A continuación, pida al administrador global de inquilinos o administrador de roles con privilegios que conceda el acceso necesario, por lo que el servicio de búsqueda puede acceder de forma segura a Microsoft Purview y extraer metadatos de etiqueta.
  • Aplique etiquetas de confidencialidad a los documentos antes de la indexación para que se puedan reconocer y conservar 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. Azure AI Search 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, requiere autenticación RBAC y, durante la versión preliminar pública, solo se admite a través de la API REST o el SDK. Las APIs de Autocompletar y Sugerir no están disponibles para los índices habilitados para Purview en este momento.

Para más información, consulte Uso de indexadores de Azure AI Search para incorporar etiquetas de confidencialidad de Microsoft Purview.

Aplicación de permisos de nivel de documento en tiempo de consulta

Con las consultas nativas basadas en tokens, Azure AI Search valida el token de Microsoft Entra de un usuario, recortando los conjuntos de resultados para incluir solo los documentos a los que el usuario está autorizado para acceder.

Para lograr el recorte automático, adjunte el token de Microsoft Entra del usuario a la solicitud de consulta. Para más información, consulte Aplicación de ACL y RBAC en tiempo de consulta en Azure AI Search.

Ventajas del control de acceso de nivel de documento

El control de acceso a nivel de documento es fundamental para proteger la información confidencial en aplicaciones controladas por IA. Ayuda a las organizaciones a crear sistemas que se alinean con sus directivas de acceso, lo que reduce el riesgo de exponer datos no autorizados o confidenciales. Al integrar reglas de acceso directamente en la canalización de búsqueda, los sistemas de inteligencia artificial pueden proporcionar respuestas fundamentadas en información segura y autorizada.

Al delegar el control de permisos a Azure AI Search, los desarrolladores pueden centrarse en desarrollar sistemas de recuperación y clasificación de alta calidad. Este enfoque ayuda a reducir la necesidad de controlar grupos anidados, escribir filtros personalizados o recortar manualmente los resultados de búsqueda.

Los permisos de nivel de documento en Azure AI Search proporcionan un marco estructurado para aplicar controles de acceso que se alinean con las directivas de la organización. Mediante el uso de ACL y roles RBAC basados en Microsoft Entra, las organizaciones pueden crear sistemas que admitan un cumplimiento sólido y promuevan la confianza entre los usuarios. Estas funcionalidades integradas reducen la necesidad de codificación personalizada, lo que ofrece un enfoque estandarizado para la seguridad de nivel de documento.

Tutoriales y ejemplos

Eche un vistazo más detalladamente al control de acceso de nivel de documento en Azure AI Search con más artículos y ejemplos.

Contenido relacionado

  • Last updated on