通过

使用 Blob 索引器引入 RBAC 范围元数据

注释

此功能目前处于公开预览状态。 此预览版未随附服务级别协议，建议不要用于生产工作负载。 某些功能可能不受支持或者受限。 有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

Azure 存储允许对 Blob 存储中的容器进行基于角色的访问，其中 存储 Blob 数据读取者 或 存储 Blob 数据参与者 等角色确定是否有权访问内容。 从 2025-05-01-preview 开始，现在可以在 Azure AI 搜索中包含 RBAC 范围以及文档引入，并使用这些权限来控制对搜索结果的访问。 如果你有权访问内容，则你可以在搜索结果中看到该内容。 如果没有权限（或者更具体地说，没有 Blob 容器上的角色分配），那么即使你个人在索引上具有“搜索索引数据读取者”分配，也看不到这些结果。

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

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

索引器方法基于以下基础构建：

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

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

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

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

先决条件

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

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

  • Azure 存储，标准性能（常规用途 v2），支持热、冷和寒访问层，提供受 RBAC 保护的容器或 Blob。

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

  • Azure 门户中当前不支持此功能，这包括通过 导入向导创建的权限筛选器。 使用编程方法创建或修改现有对象以实现文档级访问。

配置 Blob 存储

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

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

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

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

Authorization

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

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

Authorization

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

配置索引

在 Azure AI 搜索中，配置索引器、数据源和索引，以便从 Blob 拉取权限元数据。

创建数据源

  • 数据源类型必须是 azureblob。

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

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

系统托管标识的 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，并从索引中删除相应内容。

另请参阅

  • Last updated on