Solución de problemas del filtrado de permisos de SharePoint en Búsqueda de Azure AI (versión preliminar)

Use este artículo si el filtrado de permisos en tiempo de consulta del contenido indexado de SharePoint devuelve resultados incompletos o inesperados, o si se produce un error en una consulta filtrada por permisos.

Prerrequisitos

• Índice poblado por el indexador de SharePoint en Microsoft 365 con la ingesta de ACL configurada.
• Filtrado de permisos en tiempo de consulta configurado como se describe en Aplicación de ACL y RBAC en tiempo de consulta.
• Versión 2026-08-01-preview de la API REST o un paquete equivalente del SDK en versión preliminar cuando use grupos de sitios de SharePoint.
• Acceso a la definición de índice, el estado del indexador generado o explícito y los permisos de SharePoint para un usuario de prueba.
• Colaborador de datos del índice de búsqueda o un permiso de lectura elevado equivalente si necesita comparar los resultados filtrados y sin filtrar.

Siga el árbol de decisión de solución de problemas.

Complete estas comprobaciones en orden. Detenga cuando el resultado observado identifique la configuración o el permiso que necesita corrección.

1. Confirme que el error se produce en el momento de la consulta

En este artículo se trata el filtrado de permisos después de que se hayan indexado el contenido de SharePoint y los metadatos de ACL.

• Si la creación de la fuente de datos o la ejecución del indexador informan de Invalid AAD tenant, siga las medidas de corrección del inquilino de Microsoft Entra.
• Si necesita corregir TenantId, la autenticación o la cadena de conexión del origen de datos, consulte Configurar el indizador de SharePoint en Microsoft 365.
• Si faltan UserIds, GroupIds o SharePointSiteUrl durante la indexación, utilice la tabla de solución de problemas de ingesta de ACL.

Continúe aquí solo si existen metadatos indexados de permisos y el síntoma se produce al consultarlos.

2. Identificar las tres identidades

Registre qué identidad ocupa cada función. No sustituya un identificador por otro.

3. Comprobación de la configuración del filtro de permisos

Compare el índice, el indizador y los objetos generados con los artículos a los que pertenecen.

1. Confirme que el índice tiene permissionFilterOption establecido en enabled.
2. Confirme que UserIds y GroupIds tengan los valores correctos de permissionFilter.
3. Para los grupos de sitios de SharePoint, confirme que el índice tiene sharePointConnectorAppRegistration y un campo SharePointSiteUrl con sharepointSiteUrl: true.
4. Confirme que cada documento o fragmento indizado contiene los campos de permisos aplicables. Si el conjunto de aptitudes usa proyecciones de índice, compruebe que los campos de ACL están en indexProjections.mappings.

Si falta algún valor, vuelva a Configurar el servicio de búsqueda para la ingesta de ACL y el cumplimiento en tiempo de consulta.

4. Comprobación del token de consulta de forma segura

No registre, pegue en una solicitud de soporte ni comparta nunca un token de acceso completo. Descodifique solo la carga del token localmente y sane los identificadores antes de capturar la salida de diagnóstico.

1. Confirme que la solicitud incluye x-ms-query-source-authorization con un token delegado actual para el usuario de prueba.
2. Descodifique la carga localmente y confirme que oid identifica al usuario de prueba previsto. Registre un valor saneado como <test-user-object-id>.
3. Vuelva a autenticar al usuario y vuelva a intentarlo si falta el token o ha expirado.

Si se omite el token de usuario, no se devuelve el contenido protegido por permisos. El Authorization encabezado por sí solo no reemplaza x-ms-query-source-authorization.

5. Comprobar los permisos de Microsoft Entra

1. Confirme que UserIds o GroupIds contienen el identificador de objeto de Microsoft Entra esperado. Use una consulta de lectura elevada solo para esta comparación diagnóstica.
2. Confirme que el usuario de prueba tiene una asignación directa o que accede al grupo de Microsoft Entra asignado a través de una pertenencia transitiva a un grupo de Microsoft Entra.
3. Si el grupo de Microsoft Entra está anidado dentro de un grupo de SharePoint, cambie la asignación. Esta relación mixta no se amplía y puede provocar la ausencia de resultados. Agregue el usuario directamente al grupo de SharePoint o conceda permiso a través de una asignación de grupo de Microsoft Entra compatible.

Para obtener el límite de compatibilidad exacto, consulte Relaciones de grupo admitidas.

6. Comprobar los permisos del grupo del sitio de SharePoint

Complete este paso cuando la ACL del documento depende de un grupo de sitios propietarios, miembros, visitantes o SharePoint personalizados.

1. Use una consulta de lectura con privilegios elevados para confirmar que GroupIds contiene el identificador de grupo con prefijo esperado spg:e SharePointSiteUrl identifica el sitio de origen.
2. Confirme que el usuario de prueba es miembro directo de ese grupo de SharePoint.
3. Confirme que la configuración del índice sharePointConnectorAppRegistration usa los identificadores y permisos que requiere la compatibilidad con grupos de SharePoint.

Si los campos indizados están vacíos o obsoletos, corrija la ingesta o sincronice los permisos de SharePoint antes de volver a probar la consulta.

7. Comprobación de la solicitud de consulta

1. Use la versión 2026-08-01-preview de la API de REST o un paquete de SDK en versión preliminar equivalente para los filtros de permisos de grupos de sitios de SharePoint.
2. Compruebe que Authorization autentica una identidad que puede consultar el índice.
3. Confirme que x-ms-query-source-authorization contiene el token delegado del usuario de prueba.
4. Vuelva a intentar la misma consulta sin filtros no relacionados ni cambios de clasificación para que pueda aislar el comportamiento de los permisos.

Use el ejemplo de consulta general como propietario de la forma de solicitud. No incluya tokens completos en solicitudes o registros guardados.

8. Comparar los resultados esperados y reales

1. Elija un documento al que el usuario de prueba pueda acceder y un documento al que el usuario no pueda acceder en SharePoint.
2. Ejecute la consulta filtrada por permisos con el usuario de prueba y registre solo claves de documentos u otros identificadores que no sean secretos.
3. Ejecute una consulta de lectura con privilegios elevados y compare los valores almacenados UserIds, GroupIdsy SharePointSiteUrl con los permisos de origen.
4. Si la lectura con privilegios elevados devuelve el documento esperado, pero la consulta de usuario no lo hace, céntrese en el token de usuario y la resolución de grupos. Si la lectura con privilegios elevados tampoco lo detecta, céntrese en la ingesta, los mapeos y la sincronización de las ACL.

La lectura con privilegios elevados es para fines de investigación. No lo use para devolver resultados sin restricciones a los usuarios finales.

9. Capturar detalles de correlación de solicitudes

Si la consulta sigue fallando, capture la versión de la API, la marca de tiempo UTC, el cuerpo de la solicitud saneado, el estado HTTP, los encabezados de respuesta y cualquier solicitud o identificador de correlación devuelto por el servicio. Incluya el nombre del índice y si el mismo documento aparece en lectura elevada.

Elimine los tokens de acceso, las claves de API, los secretos, los nombres de usuario y las URL específicas del tenant antes de compartir los diagnósticos con Soporte técnico de Microsoft.

Contenido relacionado

• Aplicación de ACL y RBAC durante la consulta
• Uso de un indexador de SharePoint para ingerir metadatos de permisos
• Configurar el indexador de SharePoint en Microsoft 365