使用 ADLS Gen2 索引器根据用户访问权限引入权限元数据并筛选搜索结果（预览版）

Azure Data Lake Storage（ADLS）Gen2通过访问控制列表（ACL）和基于角色的访问控制（Azure RBAC）支持按用户访问目录和文件。 不支持基于属性的访问控制（Azure ABAC）。

Azure AI 搜索可以使用预览 REST API 将此权限元数据（预览版）与文档内容一起引入。 在存储中无法访问目录或文件的用户在搜索结果中看不到相应的文档。 这是Azure AI 搜索中文档级访问控制的几种策略之一。

本文介绍如何配置 ADLS Gen2 索引器或 ADLS Gen2 Blob 知识源，以自动将权限元数据拉入搜索索引。 它补充 ADLS Gen2 中的索引数据 ，并为 ADLS Gen2 创建 Blob 知识源 ，其中包含特定于权限引入的信息。 若要手动 推送 权限元数据，请参阅 使用推送 API 为文档 ACL 编制索引。

先决条件

• Microsoft Entra ID身份验证和授权。 服务和应用必须位于同一租户中。 只要所有租户都使用Microsoft Entra ID，用户就可以位于不同的租户中。 角色分配用于每个经过身份验证的连接。

• 可计费层（任何区域中的“基本”层或更高层）上的 Azure AI 搜索。 搜索服务必须 启用基于角色的访问 ，并启用 系统分配的托管标识或用户分配的托管标识。

• ADLS Gen2 Blob 位于分层命名空间，具有通过 ACL 或角色授予的用户权限。

• REST API 版本 2025-05-01-preview 或更高版本，用于索引器权限引入。 要支持知识源，需要使用 REST API 版本 2025-11-01-preview 或更高版本。 使用支持 权限筛选器的最新预览版 REST API 或预览版 SDK 包。

限制

• Azure门户不支持此功能。

• 角色分配和 ACL 条目的 ADLS Gen2 限制 适用。

• owning users、owning groups和Other（all）ACL 标识类别在预览期间不支持。 请改用 named users 和 named groups 赋值。

• 以下索引器功能不支持源自 ADLS Gen2 的索引文档中的权限继承。 如果在技能集或索引器中使用这些功能中的任何一项，则索引内容中不包含文档级权限。

  • 自定义 Web API 技能

  • 知识存储，包括 图像服务（预览版） 在代理检索中所需的资产存储。 因此，引入 ACL 或 RBAC 范围的知识源不支持图像服务。

  • 索引器扩充缓存

  • 调试会话

支持权限模型

本部分比较 ADLS Gen2 与 Azure AI 搜索 之间的文档级访问控制功能。 本文介绍 AI 搜索支持或映射哪些 Azure Data Lake Storage (ADLS) Gen2 访问控制机制。 这有助于了解如何在文档级别强制实施权限。

在查询时，Azure AI 搜索先评估容器级 RBAC，然后检查文档级 ACL 条目。 如果任何机制允许访问，则授予访问权限。

关于 ACL 分层权限

索引器和知识源可以通过遵循 ADLS Gen2 分层访问评估流，从指定容器以及通向每个文件的所有目录中检索 ACL 分配。 计算每个文件的最终有效访问列表，并将不同的访问类别编入相应的索引字段。

例如，ADLS Gen2 中与权限相关的常见场景是使用文件路径 /Oregon/Portland/Data.txt。

索引器或知识源从每个容器和目录中收集 ACL。 然后，它会确定较低级别的有效访问，并继续，直到它解析每个文件的权限。

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

配置 ADLS Gen2

如果满足以下条件，索引器或知识源可以在存储帐户上检索 ACL。 有关 ACL 分配的详细信息，请参阅 ADLS Gen2 ACL 分配。

授权

对于索引编制，搜索服务标识必须具有“存储 Blob 数据读者”权限。

如果在本地进行测试，则还应该有一个存储 Blob 数据读取者角色分配。 有关详细信息，请参阅使用托管标识连接到Azure存储。

根容器权限：

1. 在具有Group和User权限的根容器/上分配所有Read和Execute设置（安全主体）。

2. 确保将Read和Execute都添加为“默认权限”，以便它们自动传播到新创建的文件和目录。

将权限向下传递到文件层次结构中

虽然新目录和文件继承权限，但现有目录和文件不会自动继承这些分配。

使用 ADLS Gen2 工具 以递归方式应用 ACL 来对现有内容的分配进行传播。 此工具将根容器的 ACL 分配传播到所有基础目录和文件。

删除多余的权限

以递归方式应用 ACL 后，查看每个目录和文件的权限。

删除不应有权访问特定目录或文件的任何 Group 或 User 集。 例如，从文件夹User2中删除Portland/，并且对于文件夹Idaho，从其分配中移除Group2和User2，依此类推。

示例 ACL 分配结构

下面是 ADLS Gen2 文档中 虚构目录层次结构 的 ACL 分配结构图。

随着时间推移更新 ACL 分配

随着有新 ACL 分配被添加或修改，重复上述步骤，以确保正确的传播和权限一致性。 使用索引器或知识源重新引入内容时，ADLS Gen2 中的更新权限在搜索索引中更新。

配置Azure AI 搜索

回想一下，搜索服务必须具有：

• 已启用基于角色的访问
• 配置的托管标识

授权

对于索引编制，发出 API 调用的客户端必须具有 搜索服务参与者 权限才能创建对象、执行数据导入的 搜索索引数据参与者 权限，以及 搜索索引数据读取器 来查询索引。

如果在本地进行测试，则应具有相同的角色分配。 有关详细信息，请参阅 使用角色连接到 Azure AI 搜索。

配置知识源

如果使用知识源，则知识源中的定义用于生成完整的索引管道（索引器、数据源和索引）。 检测到 ACL 分配并将其自动包含在生成的索引中。 如果希望在索引内容中继承权限，则无需修改任何生成的对象。

有关使它适用于此方案的配置的要点：

• isADLSGen2 设置为 true，满足此方案的数据源要求。
• ingestionPermissionOptions 指定用户和组 ID。

# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-08-01-preview
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

配置基于索引器的索引编制

如果使用索引器，请对其进行配置、数据源和索引，以便从 ADLS Gen2 Blob 拉取权限元数据。

创建数据源

本部分补充了来自ADLS Gen2的索引数据，提供了将权限与文档内容一起引入Azure AI 搜索索引的特定信息。

• 数据源类型必须是 adlsgen2。

• 数据源必须具有indexerPermissionOptions、userIds、groupIds 或 rbacScope。

  • 对于 rbacScope，请使用托管标识格式配置 连接字符串。

  • 对于使用用户分配的托管标识的连接字符串，还必须指定属性。

带有系统托管标识的 JSON 示例：

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

在连接字符串中具有用户托管标识的 JSON 架构示例：

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

在索引中创建权限字段

在Azure AI 搜索中，请确保索引包含权限元数据的字段定义。 在数据源定义中指定indexerPermissionOptions时，可以对权限元数据进行索引。

ACL（UserIds、GroupIds）和 RBAC 作用域的建议架构属性：

• 具有 userIds permissionFilter 值的用户标识符（ID）字段。
• 具有 groupIds permissionFilter 值的组 ID 字段。
• 具有 rbacScope permissionFilter 值的 RBAC 范围字段。
• 用于在查询时启用筛选的属性 permissionFilterOption 。
• 对权限元数据使用字符串字段
• 在所有字段上都将 filterable 设置为 true。

请注意，retrievable 是 false。 可以在开发过程中设为 true，以验证权限是否存在，但请记住在部署到生产环境之前改为 false。

JSON 架构示例：

{
  ...
  "fields": [
    ...
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

配置索引器

索引器中的字段映射将数据路径设置为索引中的字段。 按名称或数据类型变化的目标字段和目的字段需要显式的字段映射。 如果更改字段名称，ADLS Gen2 中的以下元数据字段可能需要字段映射：

• metadata_user_ids （Collection(Edm.String)） - ACL 用户 ID 列表。
• metadata_group_ids （Collection(Edm.String)） - ACL 组 ID 列表。
• metadata_rbac_scope （Edm.String） - 容器 RBAC 范围。

在索引器中指定 fieldMappings ，以便在编制索引期间将权限元数据路由到目标字段。

JSON 架构示例：

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

建议和最佳做法

• 在创建任何文件夹之前，请仔细规划 ADLS Gen2 文件夹结构。

• 尽可能将用户身份组织到组中，并使用这些组，而不是直接向单个用户授予访问权限。 持续添加单个用户而不是应用用户组会增加需要跟踪和评估的访问控制项的数量。 不遵循此最佳做法可能会导致索引所需的更频繁的安全元数据更新，因为此元数据发生更改，从而导致刷新过程中延迟和效率低下。

在索引内容和源内容之间同步权限

在索引器上启用 ACL 或 RBAC 增强只有在两种情况下才能自动实现：

• 第一次完整索引器运行/数据抓取： 捕获每个文档当时存在的所有权限元数据。

• 启用 ACL/RBAC 支持后添加的全新文档：其 ACL/RBAC 信息将与内容一起被引入。

如果更改文档权限（例如将用户添加到 ACL 或更新角色分配），则更改不会显示在搜索索引中，除非告知索引器再次爬网文档的权限元数据。

根据更改的项数，选择以下机制之一：

Resetdocs （预览版） API 示例：

POST https://{service}.search.windows.net/indexers/{indexer}/resetdocs?api-version=2026-08-01-preview
{ 
  "documentKeys": [ 
    "1001", 
    "4452" 
  ]
}

重新同步（预览版）API 示例：

POST https://{service}.search.windows.net/indexers/{indexer}/resync?api-version=2026-08-01-preview
{ 
  "options": [ 
    "permissions" 
  ] 
} 

删除跟踪

若要有效管理 Blob 删除，请确保在索引器首次运行时启用 删除跟踪 。 此功能允许系统检测源中已删除的 Blob，并将其从索引中删除。

相关内容

• 使用角色连接到Azure AI 搜索
• 查询时的 ACL 和 RBAC 执行
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API