你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用角色连接到Azure AI 搜索

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。 它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

Azure AI 搜索 通过 Microsoft Entra ID 支持基于角色的访问控制。 基于角色的访问是可选的，但建议使用。 该选项的替代方法是基于密钥的身份验证，这是默认选项。

如果将多个角色分配给安全主体，则会合并权限。 角色分配适用于所有工具和客户端库。

本文介绍如何为服务管理、开发和只读查询和检索访问分配内置角色。 它还提供创建自定义角色和测试角色分配的步骤。

小窍门

  • 想要快速了解一下内置角色吗？ 请参阅 权限摘要。
  • 若要在文档级别控制对搜索结果的访问，也称为行级别安全性，请参阅 Azure AI 搜索 中的文档级访问控制。

Prerequisites

内置角色

角色是影响控制平面或数据平面的权限集合：

  • 控制平面： 服务预配、配置和管理的操作。 控制平面操作包括创建或删除搜索服务、列出 API 密钥以及管理网络和身份验证设置。 可通过 Azure 资源管理器 REST API、Search Management REST API 和等效Azure SDK客户端库获得。

  • 数据平面： 针对搜索服务终结点的操作。 数据平面操作分为两类：对象管理和内容访问。 可通过 Search Service REST API 和等效Azure SDK客户端库获得。

角色说明

以下这些内置角色授予了对 Azure AI 搜索 的权限。 控制平面角色始终可用，而数据平面角色需要在搜索服务上 启用基于角色的访问 。 可以将内置角色合并为更广泛的访问权限，也可以创建具有所需特定权限的 自定义角色 。

角色 平面 说明
所有者 控制
  • 完全控制平面访问，包括分配角色和更改身份验证设置的功能。
  • 默认情况下，订阅管理员具有此角色。
  • 可以管理 API 密钥。
  • 无法创建搜索对象、加载文档、查询索引或从知识库检索。
参与者 控制
  • 与拥有者相同的控制平面访问级别，但无法分配角色。
读取者 控制
  • 只读控制平面访问。
  • 可以查看服务指标和对象定义。
  • 无法查看或管理 API 密钥、加载文档、查询索引或从知识库检索。
搜索服务参与者 控制与数据
  • 完全控制平面访问。 数据平面访问仅限于对象管理。
  • 可以创建索引、索引器、技能集、知识库和其他搜索对象。
  • 可以通过控制平面操作获取管理员 API 密钥和查询 API 密钥。
  • 无法通过基于角色的访问直接从知识库加载文档、查询索引或检索。
  • 有关完整权限列表，请参阅 Microsoft.Search/searchServices/*。
搜索索引数据参与者 数据
  • 读写内容访问。
  • 可以加载文档、查询索引以及从知识库检索。
  • 无法修改对象定义或检索管理密钥。
搜索索引数据读者 数据
  • 只读内容访问。
  • 可以查询索引并从知识库中检索。
  • 无法加载文档、修改对象定义或检索管理密钥。

重要说明

  • 所有者、参与者和搜索服务参与者可以检索管理密钥，这些密钥提供对数据平面的完整读写访问权限。 仅向受信任的用户授予这些角色。
  • 默认情况下，数据平面角色适用于搜索服务上的所有索引。 若要将搜索索引数据参与者或搜索索引数据读取者的范围限定为单个索引，请参阅 授予对单个索引的访问权限。

权限摘要

使用下表快速查找提供所需权限的角色。

权限 所有者/参与者 读者 搜索服务参与者 搜索索引数据参与者 搜索索引数据读取者
创建和配置Azure AI 搜索服务 ✅ ❌ ✅ ❌ ❌
访问 Azure 门户中的服务 ✅ ✅ ✅ ❌ ❌
查看服务属性、指标和终结点 ✅ ✅ ✅ ❌ ❌
列出服务上的所有对象 ✅ ✅ ✅ ❌ ❌
访问配额和服务统计信息 ✅ ❌ ✅ ❌ ❌
查看、复制和重新生成密钥 ✅ ❌ ✅ ❌ ❌
设置身份验证选项 ✅ ❌ ✅ ❌ ❌
查看角色、策略和定义 ✅ ✅ ✅ ❌ ❌
配置网络安全和专用连接 ✅ ❌ ✅ ❌ ❌
创建、运行和管理搜索对象 1 ❌ ❌ ✅ ❌ ❌
上传用于编制索引 2 的数据 ❌ ❌ ❌ ✅ ❌
查询索引 ❌ ❌ ❌ ✅ ✅
从知识库中检索 ❌ ❌ ❌ ✅ ✅
使用提升读取（预览版）绕过权限过滤器 ❌ ❌ ❌ ✅ ❌

1 包括索引、索引器、数据源、技能集、别名、同义词映射、调试会话、知识库和知识源。 索引器还支持运行和重置操作。

2 所有者或参与者可以运行 导入数据 向导 来创建和加载索引，即使它们不能在其他客户端中上传文档。 同样，无论 每个索引角色分配如何，索引器都可以写入搜索服务的任何索引。 在这两种情况下，搜索服务（而不是用户）使用其Microsoft.Search/searchServices/indexes/documents/*权限执行数据平面操作。

分配内置角色

在本部分中，你将为以下项分配角色：

为服务管理分配角色

通过以下角色，可以创建、配置和管理搜索服务。 这些角色是分层角色，因此请根据所需的访问级别选择一个角色。

角色 ID
所有者 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
参与者 b24988ac-6180-42a0-ab88-20f7382dd24c
读取者 acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. 在 Azure 门户中访问你的搜索服务。

  2. 在左窗格中，选择Access control （IAM）。

  3. 选择+ 添加>添加角色分配。

    用于分配服务管理角色的访问控制（IAM）页的屏幕截图。

  4. 选择角色： 所有者、 参与者或 读者。

  5. 在 Members 选项卡上，选择Microsoft Entra用户或组标识。 如果要为另一个Azure服务设置权限，请选择系统分配的或用户分配的托管标识。

  6. 在“查看 + 分配”选项卡上，选择“查看 + 分配”，以分配角色。

分配用于开发的角色

通过以下角色，可以创建搜索对象、加载文档、查询索引以及从知识库检索。 分配所有三个角色以涵盖整个开发任务。

角色 ID
搜索服务参与者 7ca78c08-252a-4471-8644-bb5ff32d4ba0
搜索索引数据参与者 8ebe5a00-799e-43f5-93ac-243d3dce84a7
搜索索引数据读者 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. 在 Azure 门户中访问你的搜索服务。

  2. 在左窗格中，选择Access control （IAM）。

  3. 选择+ 添加>添加角色分配。

    用于分配开发角色的访问控制（IAM）页的屏幕截图。

  4. 选择 “搜索服务参与者”。

  5. 在 Members 选项卡上，选择Microsoft Entra用户或组标识。 如果要为另一个Azure服务设置权限，请选择系统分配的或用户分配的托管标识。

  6. 在“查看 + 分配”选项卡上，选择“查看 + 分配”，以分配角色。

  7. 重复这些步骤以分配 搜索索引数据参与者 和 搜索索引数据读取器。

为只读访问权限分配角色

对于只需要对索引和知识库具有读取访问权限的应用和进程，请使用以下角色。 支持的操作包括 搜索、 查找、 自动完成以及索引 建议 以及知识库 检索 。

角色 ID
搜索索引数据读者 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. 在 Azure 门户中访问你的搜索服务。

  2. 在左窗格中，选择Access control （IAM）。

  3. 选择+ 添加>添加角色分配。

    用于分配只读数据访问角色的访问控制（IAM）页的屏幕截图。

  4. 选择 “搜索索引数据读取者 ”角色。

  5. 在 Members 选项卡上，选择Microsoft Entra用户或组标识。 如果要为另一个Azure服务设置权限，请选择系统分配的或用户分配的托管标识。

  6. 在“查看 + 分配”选项卡上，选择“查看 + 分配”，以分配角色。

测试角色分配

使用客户端测试角色分配。 请记住，角色是可以叠加的。 你无法在资源（搜索服务）级别删除或拒绝作用域为订阅或资源组级别的继承角色。

在继续操作之前， 请为应用程序配置无密钥连接 ，并就地分配角色。

  1. 在 Azure 门户中访问你的搜索服务。

  2. 在左窗格中，选择 “搜索管理>索引 ”以测试与索引相关的权限：

    • 搜索服务参与者可以创建、修改和删除搜索对象，但无法加载文档或运行查询。 若要验证权限，请创建搜索索引。

    • 搜索索引数据参与者可以加载文档。 Azure门户中导入数据向导之外没有“加载文档”选项，但可以重置并运行索引器以确认文档加载权限。

    • 搜索索引数据读取器可以查询索引。 若要验证权限，请使用搜索资源管理器。 应能够发送查询和查看结果，但不应能够查看索引定义或创建索引。

授予对单个索引的访问权限

在某些情况下，你可能希望限制应用程序对单个资源（如索引）的访问权限。

目前，Azure门户不支持在索引级别分配角色。 使用 Azure CLI、PowerShell 或 REST API 分配限定为单个索引的角色。

每个索引的范围和索引器操作

按索引角色分配仅适用于直接 API 操作，例如从用户或应用程序上传查询或文档。 索引器不受每个索引权限的限制，因为它们使用服务级别凭据运行。

具有 搜索服务贡献者 角色的用户可以创建索引器，这些索引器可以将数据写入搜索服务中的任何索引，即使用户在这些索引上没有单独的角色分配。

对于索引之间的严格数据隔离，请考虑以下方法：

  • 对需要索引级隔离的团队或用户使用单独的搜索服务。
  • 仅向管理索引器的管理员分配 搜索服务参与者 。
  • 通过安全筛选器使用 文档级访问控制 来限制共享索引中的查询结果。

创建自定义角色

如果内置角色不提供正确的权限组合，则可以创建自定义 角色 来支持所需的操作。

以下示例克隆 搜索索引数据读取器 ，然后添加按名称列出索引的功能。 通常，在搜索服务中列出索引被视为一种管理权限。

  1. 登录到 Azure 门户并导航到搜索服务。

  2. 在左窗格中，选择Access control （IAM）。

  3. 在“ 角色 ”选项卡上，找到 “搜索索引数据读取者 ”或其他角色，选择省略号（...），然后选择“ 克隆”。

  4. 在Basics选项卡上，输入自定义角色的名称，例如“搜索索引数据资源管理器”，然后选择Next。

  5. 在“ 权限 ”选项卡上，选择“ 添加权限”。

  6. 在 Add permissions 窗格中，选择Microsoft 搜索磁贴。

  7. 在顶部选择 “操作” 后，设置以下权限：

    • 在 Microsoft.Search/operations 下，选择 Read ： 列出所有可用操作。
    • 在 Microsoft.Search/searchServices/indexes 下，选择 Read ： Read Index。

  8. 切换到顶部的 Data Actions，然后在 Microsoft.Search/searchServices/indexes/documents 下，选择 Read： Read Documents。

    JSON 定义如以下示例所示：

    {
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
    }
}

  9. 选择 “添加” 关闭窗格。

  10. 选择“查看 + 创建”以创建角色。

    现在可将用户和组分配到该角色。 有关这些步骤的详细信息，请参阅 使用 Azure 门户创建或更新Azure自定义角色。

创建条件访问策略

如果需要强制实施组织策略（如多重身份验证），请使用 Microsoft Entra 条件访问。

若要为Azure AI 搜索创建条件访问策略，请执行以下操作：

  1. 登录到 Azure 门户。

  2. 搜索 Microsoft Entra 条件访问。

  3. 在“ 概述 ”页上，选择“ 创建新策略”。

  4. 在 Cloud 应用或操作下，添加 Azure AI 搜索 作为云应用，具体取决于设置策略的方式。

  5. 更新策略的剩余参数。 例如，指定策略适用的用户和组。

  6. 保存策略。

重要说明

如果搜索服务分配有托管标识，则特定搜索服务将显示为云应用。 但是，选择该特定搜索服务不会强制实施策略。 而是选择常规 Azure AI 搜索 云应用，将条件访问策略应用于搜索服务。

故障排除

开发使用基于角色的访问控制进行身份验证的应用程序时，可能会遇到一些常见问题：

  • 搜索服务的默认配置是基于密钥的身份验证。 如果不将此设置更改为 “两者 ”或 “基于角色的访问控制”，则无论基础权限如何，使用基于角色的身份验证的所有请求都会自动被拒绝。

  • 如果请求包含 API 密钥以及基于角色的凭据，服务将使用密钥进行身份验证。 从请求标头中删除 API 密钥，以使用基于角色的身份验证。

  • 如果授权令牌来自 托管标识，而且你最近分配了相应的权限，可能需要几个小时 权限分配才会生效。

  • 如果具有文档级权限的查询未返回预期结果，请使用“搜索索引数据参与者”或 创建 具有 提升权限的自定义角色（预览版） 进行调查。

后续步骤

本文介绍如何为Azure AI 搜索上的控制和数据平面操作分配角色。 有关向应用程序代码添加基于角色的访问的综合说明：

使用标识将应用连接到 Azure AI 搜索

  • Last updated on