Aplicación de ACL y RBAC en tiempo de consulta en Búsqueda de Azure AI (versión preliminar)

El control de acceso en tiempo de consulta (versión preliminar) garantiza que los usuarios solo recuperen los resultados de búsqueda a los que están autorizados para acceder, en función de su identidad, pertenencia a grupos, roles o atributos. Esta funcionalidad es esencial para la búsqueda empresarial segura y los flujos de trabajo controlados por el cumplimiento.

El acceso autorizado depende de los metadatos de permisos que se ingieren durante la indexación. En el caso de los orígenes de datos del indexador que tienen modelos de acceso integrados, como Azure Data Lake Storage (ADLS) Gen2 y SharePoint en Microsoft 365, un indexador puede extraer automáticamente los metadatos de permiso para cada documento. Para otros orígenes de datos, debe ensamblar la carga del documento usted mismo y la carga debe incluir tanto el contenido como los metadatos de permisos asociados. Después, use las APIs push para cargar el índice.

En este artículo se explica cómo configurar consultas que usan metadatos de permiso para filtrar los resultados.

Requisitos previos

• Los metadatos de permiso deben estar en filterable campos tipo cadena. No usará el filtro en las consultas, pero el motor de búsqueda crea un filtro internamente para excluir contenido no autorizado.

• Los metadatos de permisos deben constar de permisos de estilo POSIX que identifiquen el nivel de acceso y el identificador de usuario o grupo, o el identificador de recurso del contenedor en ADLS Gen2 si usa el ámbito RBAC.

• Para la aplicación basada en ACL con importación personalizada, almacena userIds y groupIds como ID de objeto de Microsoft Entra (GUID) en campos filtrables. En el momento de la consulta, el servicio hace coincidir las identidades de x-ms-query-source-authorization con los identificadores almacenados. Para obtener más información sobre el esquema, consulte Indexación de listas de control de acceso a documentos (ACL) mediante las API REST de inserción (versión preliminar).

• Dependiendo del origen de datos:

  • Para los orígenes de datos de ADLS Gen2, se deben haber configurado listas de control de accesos (ACLs) y/o control de acceso basado en roles de Azure (RBAC) a nivel de contenedor.
  • En el caso de los orígenes de datos de Azure Blob, debe contar con asignaciones de roles en el contenedor. Puede usar un indexador integrado, un origen de conocimiento o API Push para indexar los metadatos de permisos en el índice.
  • Para los orígenes de datos de SharePoint, debe configurar listas de control de acceso (ACL). Puede usar un indizador integrado de SharePoint y configurarlo con capacidades de ingesta de ACL. También puede usar un origen de conocimiento de SharePoint indexado y configurarlo para aplicar permisos de nivel de documento. Los permisos basados en grupos, incluidos los Grupos de Microsoft 365, se admiten cuando se incorporan como identificadores de objeto de Entra. La expansión del grupo se produce en el momento de la consulta a través de Microsoft Graph.

• Use la API REST de latest preview o un paquete de versión preliminar de un SDK de Azure para consultar el índice o el origen de conocimiento. Esta versión de API admite consultas internas que filtran los resultados no autorizados.

Limitaciones

• Si se produce un error en la evaluación de ACL (por ejemplo, el Graph API no está disponible), el servicio devuelve 5xx y not devuelve un conjunto de resultados filtrado parcialmente.

• La vigencia de las ACL depende del método de importación. Para evitar decisiones de autorización obsoletas, planee cómo cada origen propaga los cambios de permisos en el índice:

  • Un indexador de SharePoint programado actualiza los cambios de permisos de nivel de elemento en cada ejecución. Los cambios en un ámbito principal (sitio, biblioteca, lista o carpeta) que heredan los elementos secundarios requieren una resincronización.
  • Un indexador de ADLS Gen2 requiere una resincronización para actualizar las ACL.
  • La importación personalizada o por push requiere que vuelvas a importar los documentos afectados.

• La visibilidad del documento requiere lo siguiente:

  • El rol RBAC de la aplicación que llama (encabezado de autorización).
  • La identidad del usuario llevada por x-ms-query-source-authorization.

• Las consultas basadas en ACL iniciales pueden experimentar una mayor latencia en comparación con las solicitudes posteriores, debido a la sobrecarga de almacenamiento en caché y resolución de permisos.

• En el contenido indexado de SharePoint, no se expande un grupo de Microsoft Entra anidado en un grupo de SharePoint. La resolución transitiva de grupos de Microsoft Entra no admite esta relación mixta. Consulte Relaciones de grupo admitidas.

Límites de entrada de ACL por origen de datos

Los límites de entrada de la lista de control de acceso (ACL) definen cuántos registros de permisos distintos se pueden asociar a un archivo, carpeta o elemento dentro de un origen de datos conectado. Cada entrada representa una identidad de usuario o grupo única y los derechos de acceso concedidos a esa identidad (por ejemplo, Lectura, Escritura o Ejecución).

El número máximo de entradas de ACL admitidas por Búsqueda de Azure AI funcionalidad varía en función del tipo de origen de datos:

Azure Data Lake Storage Gen2 (ADLS Gen2): cada archivo o directorio puede tener hasta 32 permisos de entradas de ACL. En este contexto, una entrada significa un único principal (usuario o grupo) con un conjunto de permisos específico. Ejemplo: asignar el acceso de lectura a "Todos" y el acceso de ejecución a "usuarios de Azure" contaría como dos entradas de ACL.

SharePoint en Microsoft 365: La fuente de datos de SharePoint en las búsquedas admite hasta 1.000 entradas de permisos por archivo. Cada entrada representa una asignación de grupo o usuario única en la lista de permisos del elemento. Esto es distinto de los límites generales de los ámbitos de permisos únicos por lista o biblioteca, que rige el número de elementos que pueden tener permisos únicos.

Estos límites determinan cómo Búsqueda de Azure AI pormenorizadamente puede respetar los permisos de nivel de elemento al indexar o filtrar los resultados de la búsqueda. Si un elemento supera estos límites de entrada de ACL, es posible que no se apliquen permisos más allá del límite en el momento de la consulta.

Funcionamiento de la aplicación en tiempo de consulta

En esta sección se muestra el orden de las operaciones para la aplicación de ACL en el momento de la consulta. Las operaciones varían en función de si usa el ámbito de Azure RBAC o el grupo o identificadores de usuario de Microsoft Entra ID.

1. Entrada de permisos de usuario

La aplicación de usuario final incluye un token de acceso de consulta como parte de la solicitud de consulta de búsqueda y ese token de acceso suele ser la identidad del usuario. En la tabla siguiente se muestra el origen de los permisos de usuario admitidos por Búsqueda de Azure AI para la aplicación de ACL:

2. Construcción de filtro de seguridad

Internamente, Búsqueda de Azure AI crea dinámicamente filtros de seguridad en función de los permisos de usuario proporcionados. Estos filtros de seguridad se anexan automáticamente a los filtros que pueden aparecer con la consulta si el índice tiene habilitada la opción de filtro de permisos.

Para Azure RBAC, los permisos son listas de cadenas de identificador de recurso. Debe haber una asignación de roles de Azure (Lector de datos de Storage Blob) en el origen de datos que conceda acceso al token de entidad de seguridad en el encabezado de autorización. El filtro excluye los documentos si no hay ninguna asignación de roles para el principal detrás del token de acceso en la solicitud.

3. Filtrado de resultados

El filtro de seguridad compara de forma eficaz los identificadores de usuario (userIds), los identificadores de grupo (groupIds) y el ámbito de RBAC (rbacScope) de la solicitud con cada una de las listas de ACL de todos los documentos del índice de búsqueda, con el fin de limitar los resultados devueltos a aquellos a los que el usuario tiene acceso. Es importante tener en cuenta que cada filtro se aplica de forma independiente y un documento se considera autorizado si algún filtro se realiza correctamente. Por ejemplo, si un usuario tiene acceso a un documento a través de userIds, pero no a través de groupIds, el documento se considera válido y se devuelve al usuario.

grupos de SharePoint en el momento de la consulta

A partir de la versión preliminar 2026-05-01 de la API REST, Búsqueda de Azure AI puede tener en cuenta las pertenencias a grupos de sitios de SharePoint, como Owners, Members, Visitors y grupos de sitios personalizados, en tiempo de consulta. Para habilitar este escenario, el índice debe incluir:

• Propiedad sharePointConnectorAppRegistration que hace referencia a la credencial de identidad federada de la aplicación Microsoft Entra usada para llamar a SharePoint en nombre del usuario.
• Campo marcado con el atributo /> y rellenado desde el campo de origen ).

Cuando se realiza la consulta, Búsqueda de Azure AI usa la aplicación registrada y la dirección URL del sitio de cada documento candidato para resolver las pertenencias a grupos de SharePoint del usuario que realiza la solicitud en ese sitio. Los grupos resueltos se cotejan con los valores con el prefijo spg: almacenados en el campo groupIds de filtro de permisos. El prefijo spg: distingue los grupos de sitios de SharePoint de los identificadores de objeto de grupo de Microsoft Entra, que se almacenan sin prefijo.

Para obtener detalles y limitaciones de configuración, consulte Configure SharePoint groups support.

Si el filtrado de permisos de SharePoint devuelve resultados incompletos o inesperados, consulte Solucionar problemas del filtrado de permisos de SharePoint.

Ejemplo: Consulta con el aplicación de grupos de sitios de SharePoint

La solicitud es idéntica a la consulta estándar impuesta por ACL. El servicio de búsqueda usa el sharePointConnectorAppRegistration del índice para resolver la pertenencia a grupos de SharePoint en nombre del llamante. Incluya GroupIds en la cláusula select para ver los valores con el prefijo spg: en la respuesta.

POST {{endpoint}}/indexes/{index}/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,SharePointSiteUrl,GroupIds",
    "orderby": "name asc"
}

Ejemplo de consulta

Este es un ejemplo de una solicitud de consulta de sample code. El token de consulta es un token de acceso Microsoft Entra para el usuario que realiza la consulta.

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

{
    "search": "*",
    "select": "name,description,location,GroupIds",
    "orderby": "name asc"
}

Permisos elevados para investigar resultados incorrectos (versión preliminar)

Las consultas de depuración que incluyen metadatos de permisos pueden ser problemáticas porque los resultados de búsqueda son específicos de cada usuario. Como desarrollador o administrador, es posible que necesite permisos elevados para devolver resultados independientemente de los metadatos de permisos para poder investigar problemas con las consultas que devuelven contenido no autorizado.

Para investigar, debe ser capaz de:

• Vea el conjunto de documentos que el usuario final puede ver en función de los permisos de ese usuario.

• Vea todos los documentos del índice para investigar por qué es posible que algunos no sean visibles para el usuario final.

Puede realizar estas tareas agregando un encabezado personalizado, x-ms-enable-elevated-read: true, a una consulta.

Permisos para solicitudes de lectura elevada

Debe tener permisos de colaborador de datos de índice de búsqueda o un rol personalizado que incluya el permiso de lectura con privilegios elevados.

Las consultas son una operación de plano de datos, por lo que el rol personalizado solo puede constar de permisos de plano de datos atómicos. Para un rol personalizado, agregue el permiso Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read.

Agregar un encabezado de lectura elevada a una consulta

Después de configurar los permisos, puede ejecutar la consulta. El ejemplo siguiente es una solicitud de consulta en un índice de búsqueda.

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2026-08-01-preview
Authorization: Bearer {AUTH_TOKEN}
x-ms-query-source-authorization: {TOKEN}
x-ms-enable-elevated-read: true

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

Cambio importante del comportamiento de la funcionalidad de ACL en versiones específicas de la API en versión preliminar

Antes de la versión de la API REST 2025-11-01-preview, las versiones preliminares anteriores 2025-05-01-preview y 2025-08-01-preview devolvieron todos los documentos al usar una clave de API de servicio o roles autorizados de Entra, incluso si no se proporcionó ningún token de usuario. Las aplicaciones que no validan la presencia de un token de usuario podrían exponer accidentalmente resultados a los usuarios finales si no se implementan correctamente o siguen los procedimientos recomendados.

A partir de noviembre de 2025, este comportamiento cambió:

• Los filtros de permisos de ACL ahora se aplican incluso cuando solo se usan claves de API de servicio o autenticación Entra en todas las versiones que admiten ACL.
• Si se omite el token de usuario, no se devuelve el contenido protegido por ACL.
• Para ver todos los documentos con fines de resolución de problemas, debe incluir explícitamente el encabezado con privilegios elevados cuando utilice la versión 2026-05-01-preview o posterior de la API REST.

Esta actualización ayuda a mantener el contenido protegido cuando las aplicaciones no aplican procedimientos recomendados para la validación de tokens.

Contenido relacionado

• Tutorial: Indexación de metadatos de permisos de ADLS Gen2 y consulta con resultados filtrados por permisos (versión preliminar)
• Indexación de listas de control de acceso de documentos (ACL) mediante las API REST de inserción (versión preliminar)
• Uso de un indexador de ADLS Gen2 para ingerir metadatos de permisos y filtrar los resultados de búsqueda en función de los derechos de acceso de los usuarios (versión preliminar)
• Utilice un indexador de blobs o una fuente de conocimiento para ingerir metadatos de ámbitos de RBAC
• Use un indexador de SharePoint para ingerir metadatos de permisos y filtrar los resultados de búsqueda en función de los derechos de acceso de los usuarios (versión preliminar)