使用 Blob 索引器或知识源来引入 RBAC 范围的元数据。

Azure 存储允许对 blob 存储中的容器进行基于角色的访问，其中角色（如 Storage Blob 数据读取者或 Storage Blob 数据参与者确定某人是否有权访问内容。 Azure AI 搜索中的预览 API 现在支持引入用户权限以及文档引入，以便你可以使用这些权限来控制对搜索结果的访问。 如果用户对Azure 存储中的特定目录或文件缺乏权限，则即使你个人拥有 Azure AI 搜索 Search Index Data Reader 分配索引，该用户也无权访问相应的文档。

• 从 2025-05-01-preview 开始及更高版本，可以使用 Blob 索引器引入 RBAC 范围元数据。
• 2025-11-01-preview 及更高版本为 Azure 存储中的 Blob 知识源 提供同等支持。

RBAC 作用域在容器级别设置，并通过权限继承流向所有 Blob（文档）。 在索引期间，RBAC 范围会作为权限元数据被捕获。 可以使用推送 API 手动上传和索引内容和权限元数据（请参阅 使用推送 REST API 的索引权限），也可以使用索引器或知识源自动执行数据引入。 本文重点介绍索引自动化。

在查询时，调用方的身份通过 x-ms-query-source-authorization 参数包含在请求标头中。 如果用户要查看搜索结果，则标识必须与文档的权限元数据匹配。

本文重点介绍基于以下基础构建的索引自动化方法：

• 使用基于角色的访问控制（Azure RBAC）保护的 Azure 存储 blob。 不支持基于属性的访问控制（Azure ABAC）。

• Azure Blob 索引器或用于检索和引入数据和元数据（包括权限筛选器）的 Blob 知识源。 若要获取权限筛选器支持，请使用支持该功能的Azure SDK的最新预览版 REST API 或预览包。

• 包含引入的文档和相应权限的 Azure AI 搜索 中的索引。 权限元数据作为字段存储在索引中。

• 使用权限筛选器的查询。 若要设置遵循权限筛选器的查询，请使用支持该功能的Azure SDK的最新预览 REST API 或预览包。

先决条件

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

• Azure AI 搜索，任何区域，但必须有一个计费层（基本层和更高层），才能获得托管标识支持。 搜索服务必须配置为基于角色的访问，并且必须具有托管标识（系统或用户）。

• 使用受 RBAC 保护的容器或 blob 在热、冷访问层上Azure 存储标准性能（常规用途 v2）。

• 你应该了解索引器和知识源的工作原理以及如何创建索引。 本文介绍数据源和索引器的配置设置，但不提供创建索引的步骤。 若要详细了解专为权限筛选器设计的索引，请参阅创建具有权限筛选器字段的索引。

局限性

• Azure 门户不支持此功能。

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

  • 自定义 Web API 技能

  • 知识存储

  • 索引器扩充缓存

  • 调试会话

配置Blob 存储

验证 Blob 容器是否使用基于角色的访问。

1. 登录到Azure门户并找到存储帐户。

2. 展开容器，然后选择要编制索引的 blob 所在的容器。

3. 选择 访问控制 （IAM）以检查角色分配。 对容器编制索引后，具有 存储 Blob 数据读取者 或 存储 Blob 数据参与者 的用户和组有权在索引中搜索文档。

Authorization

对于索引器执行，搜索服务标识必须具有“存储 Blob 数据读者”权限。 有关详细信息，请参阅 使用托管标识连接到 Azure 存储。

配置Azure AI 搜索

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

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

Authorization

对于索引器的执行，发出 API 调用的客户端必须具有 Search Service 贡献者 权限以创建对象，Search 索引数据贡献者 权限以执行数据导入，以及 Search 索引数据读取器 权限以查询索引。请参阅 使用角色连接到 Azure AI 搜索。

配置知识源

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

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

• isADLSGen2设置为 false，这意味着数据源为 Azure Blob 存储。
• ingestionPermissionOptions 指定 rbacScope。

参考：创建或更新知识源 （REST API）

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

如果您正在使用索引器，请配置索引器、数据源和索引，以便从 Blob 对象中提取权限元数据。

创建数据源

• 数据源类型必须是 azureblob。

• 数据源分析模式必须是默认值。

• 数据源必须具有 indexerPermissionOptions 和 rbacScope。

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

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

系统托管标识的 JSON 示例和 indexerPermissionOptions：

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    }
}

连接字符串中包含用户托管标识的 JSON 架构示例：

{
    "name" : "my-blob-datasource",
    "type": "azureblob",
    "indexerPermissionOptions": ["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-query-used-for-selecting-specific-blobs>"
    },
    "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时对权限元数据进行索引。

建议的 RBAC 范围架构属性

• 具有 rbacScope permissionFilter 值的 RBAC 范围字段。
• 用于在查询时启用筛选的属性 permissionFilterOption 。
• 使用字符串字段作为权限元数据
• 在所有字段上将 filterable 设置为 true。

请注意，retrievable 是 false。 可以在开发过程中将其设置为 true 以验证权限是否存在，但请记住在部署到生产环境之前将其设置为 false，以便安全主体标识在结果中不可见。

JSON 架构示例：

{
  ...
  "fields": [
    ...
    { 
        "name": "RbacScope", 
        "type": "Edm.String", 
        "permissionFilter": "rbacScope", 
        "filterable": true, 
        "retrievable": false 
    }
  ],
  "permissionFilterOption": "enabled"
}

配置索引器

索引器中的字段映射将数据路径设置为索引中的字段。 名称或数据类型不同的目标字段和目的地字段需要显式字段映射。 如果更改字段名称，Azure Blob 存储中的以下元数据字段可能需要字段映射：

• metadata_rbac_scope （Edm.String） - 容器 RBAC 范围。

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

JSON 架构示例：

{
  ...
  "fieldMappings": [
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

运行索引器

配置索引器、数据源和索引后，运行索引器以动态设置进程。 如果配置或权限出现问题，则此步骤中会出现这些问题。

默认情况下，索引器会在发布到搜索服务后立即运行，但如果索引器配置将 disabled 设置为 true，则索引器会以禁用状态发布，以便你可手动运行索引器。

建议从 Azure 门户运行索引器以便监视状态和消息。

假设没有错误，索引现在已填充完成，你可以继续执行查询和测试。

删除跟踪

若要有效管理 Blob 删除，请确保在索引器首次运行时已启用 删除跟踪 。 借助此功能，系统可检测源中已删除的 Blob，并从索引中删除相应内容。

另请参阅

• 使用角色连接到Azure AI 搜索

• 查询时实施 ACL（访问控制列表）和 RBAC（基于角色的访问控制）
• azure-search-python-samples/Quickstart-Document-Permissions-Push-API

• 搜索Azure Blob 存储内容
• 配置 Blob 索引器