排查 Azure AI 搜索 中的 SharePoint 权限筛选问题（预览版）

如果索引SharePoint内容的查询时权限筛选返回缺失或意外的结果，或者权限筛选的查询失败，请使用本文。

先决条件

• 由 Microsoft 365 中的SharePoint 索引器填充且已配置ACL 引入的索引。
• 查询时权限过滤按 查询时 ACL 和 RBAC 强制执行 中所述进行配置。
• 使用 SharePoint 站点组时，请使用 REST API 版本 2026-08-01-preview 或等效的预览版 SDK 包。
• 访问索引定义、生成或显式索引器状态，以及测试用户的SharePoint权限。
• 如果您需要比较筛选结果和未筛选结果，则需要 搜索索引数据参与者 或等效的更高级别读取权限。

遵循故障排除决策树

按顺序完成这些检查。 当观察到的结果标识需要更正的配置或权限时停止。

1. 确认故障发生在查询时

本文介绍在 SharePoint 内容和 ACL 元数据被编制索引后进行的权限筛选。

• 如果数据源创建或索引器运行报告了Invalid AAD tenant，请按照Microsoft Entra 租户修复中的说明进行修复。
• 如果需要更正TenantId、身份验证或数据源连接字符串，请参阅配置 Microsoft 365 中的 SharePoint 索引器。
• 如果在建立索引期间缺少 UserIds、GroupIds 或 SharePointSiteUrl，请使用 ACL 引入故障排查表。

仅当已存在已编入索引的权限元数据，且在查询该元数据时出现此症状时，才继续执行此处步骤。

2. 识别这三个身份

记录哪个身份对应各个角色。 不要将一个标识符替换为另一个标识符。

3.检查权限筛选器配置

将索引、索引器和生成的对象与其所有者项目进行比较。

1. 确认索引已 permissionFilterOption 设置为 enabled.
2. 确认 UserIds 并 GroupIds 具有正确的 permissionFilter 值。
3. 对于 SharePoint 站点组，请确认索引具有 sharePointConnectorAppRegistration 和一个带有 sharepointSiteUrl: true 的 SharePointSiteUrl 字段。
4. 确认每个索引的文档或区块携带适用的权限字段。 如果技能集使用索引投影，请验证 ACL 字段是否位于 indexProjections.mappings 中。

如果缺少任何值，请返回到为 ACL 引入和查询时强制实施配置搜索服务。

4. 安全地检查查询令牌

切勿记录、粘贴到支持请求中或分享完整的访问令牌。 仅在本地解码令牌载荷，并在捕获诊断输出之前对标识符进行脱敏处理。

1. 确认该请求包含 x-ms-query-source-authorization，并带有测试用户当前的委托令牌。
2. 在本地解码有效负载，并确认 oid 标明的是预期的测试用户。 记录净化后的值，例如 <test-user-object-id>。
3. 重新对用户进行身份验证，如果令牌丢失或已过期，请重试。

如果省略用户令牌，则不会返回受权限保护的内容。 仅标头 Authorization 不会替换 x-ms-query-source-authorization。

5. 检查 Microsoft Entra 权限

1. 确认已编入索引的 UserIds 或 GroupIds 中包含预期的 Microsoft Entra 对象 ID。 仅将 高权限读取查询 用于此次诊断比较。
2. 确认测试用户拥有直接分配，或者通过传递性 Microsoft Entra 组成员身份属于所分配的 Microsoft Entra 组。
3. 如果Microsoft Entra组嵌套在SharePoint 组中，请更改分配。 这种混合关系不会被扩展，并且可能导致结果缺失。 将用户直接添加到 SharePoint 组，或者通过受支持的 Microsoft Entra 组分配来授予权限。

有关确切的支持边界，请参阅 支持的组关系。

6.检查SharePoint网站组权限

当文档 ACL 依赖于所有者、成员、访问者或自定义SharePoint网站组时完成此步骤。

1. 使用高权限读取查询，确认 GroupIds 包含预期的带有 spg: 前缀的组 ID，且 SharePointSiteUrl 用于标识源站点。
2. 确认测试用户是该SharePoint 组的直接成员。
3. 确认索引的sharePointConnectorAppRegistration使用了SharePoint 组支持所需的标识符和权限。

如果索引字段为空或过时，请修复引入或在重新测试查询之前同步SharePoint权限。

7. 检查查询请求

1. 将 REST API 版本2026-08-01-preview或等效的预览版 SDK 包用于SharePoint站点组权限筛选器。
2. 确认 Authorization 对可以查询索引的主体进行身份验证。
3. 确认 x-ms-query-source-authorization 包含委派的测试用户令牌。
4. 重试同一查询，而不使用不相关的筛选器或排名更改，以便隔离权限行为。

使用 常规查询示例 作为请求形状所有者。 不要在保存的请求或日志中包含完整令牌。

8. 比较预期结果和实际结果

1. 选择测试用户可以访问的一个文档，一个用户在SharePoint中无法访问的文档。
2. 以测试用户身份运行权限筛选的查询，并仅记录文档密钥或其他非机密标识符。
3. 运行提升权限读取查询，并将存储的 UserIds、GroupIds 和 SharePointSiteUrl 值与源权限设置进行比较。
4. 如果提升权限读取返回了预期的文档，而用户查询未返回该文档，请重点检查用户令牌和组解析。 如果即便使用提权读取仍找不到该数据，则应检查数据引入、映射和 ACL 同步。

提权读取用于调查。 请勿使用它向最终用户返回不受限制的结果。

9. 捕获请求关联详细信息

如果查询仍然失败，请捕获 API 版本、UTC 时间戳、清理请求正文、HTTP 状态、响应标头以及服务返回的任何请求或关联 ID。 包括索引名称，以及同一文档是否出现在提权读取下。

在与Microsoft 支持部门共享诊断之前，请删除访问令牌、API 密钥、机密、用户名和特定于租户的 URL。

相关内容

• 查询时的 ACL 和 RBAC 执行
• 使用SharePoint索引器引入权限元数据
• 在 Microsoft 365 索引器中配置SharePoint