通过

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

使用角色连接到 Azure AI 搜索

  • 项目

Azure 通过 Microsoft Entra ID 为平台上运行的所有服务提供全局身份验证和基于角色的访问控制。 在本文中，了解哪些角色提供对 Azure AI 搜索上的搜索内容和管理的访问权限。

在 Azure AI 搜索中，可以为以下用途分配 Azure 角色：

不支持通过角色分配让每个用户访问搜索结果（有时称为“行级别安全性”或“文档级别安全性”）。 一种解决方法是创建安全筛选器，以根据用户标识来精选结果，并删除请求者不应访问的文档。 如需查看演示，请参阅此使用 RAG 的企业聊天示例。

角色分配会在所有工具和客户端库中很普遍的操作，并且会不断累计。 你可以使用 Azure 基于角色的访问控制文档中所述的任何受支持方法分配角色。

基于角色的访问是可选的，但建议使用采用该选项。 该选项的替代方法是基于密钥的身份验证，这是默认选项。

先决条件

如何在 Azure 门户中分配角色

以下步骤适用于所有角色分配。

  1. 登录到 Azure 门户。

  2. 导航到你的搜索服务。

  3. 启用基于角色的访问。

  4. 在左侧导航窗格中，选择“访问控制(IAM)”。

  5. 选择“+ 添加”>“添加角色分配”，启动“添加角色分配”向导。

    Azure 门户中“访问控制”页的屏幕截图。

  6. 选择角色。 可通过该向导一次将多个安全主体（无论是用户还是托管标识）分配给一个角色，但必须为定义的每个角色重复这些步骤。

  7. 在成员选项卡上，选择 Microsoft Entra 用户或组标识。 如果要为另一个 Azure 服务设置权限，选择系统或用户托管标识。

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

“数据平面”指针对搜索服务终结点的操作（例如索引编制或查询），或者搜索服务 REST API 或等效 Azure SDK 客户端库中指定的任何其他操作。

“控制平面”指 Azure 资源管理，例如创建或配置搜索服务。

以下角色是内置角色。 如果这些角色不足以满足要求，请创建自定义角色。

角色 平面 说明
所有者 控制平面和数据平面 对搜索资源的控制平面拥有完全访问权限，包括能够分配 Azure 角色。 只有所有者角色可以启用或禁用身份验证选项或管理其他用户的角色。 默认情况下，订阅管理员是成员。

在数据平面上，此角色具有与搜索服务参与者角色相同的访问权限。 它包括对除了查询文档或编制文档索引之外的所有数据平面操作的访问权限。
参与者 控制平面和数据平面 与所有者相同的控制平面访问权限级别，但无法分配角色或更改身份验证选项。

在数据平面上，此角色具有与搜索服务参与者角色相同的访问权限。 它包括对除了查询文档或编制文档索引之外的所有数据平面操作的访问权限。
读者 控制平面和数据平面 跨整个服务的读取访问权限，包括搜索指标、内容指标（消耗的存储、对象数量）和数据平面资源的对象定义（索引、索引器等）。 但是，它无法读取 API 密钥或读取索引中的内容。
搜索服务参与者 控制平面和数据平面 对对象定义（索引、别名、同义词映射、索引器、数据源和技能组）的读写访问权限。 此角色适用于创建对象的开发人员，以及管理搜索服务及其对象的管理员，但无权访问索引内容。 使用此角色可创建、删除和列出索引、获取索引定义、获取服务信息（统计信息和配额）、测试分析器、创建和管理同义词映射、索引器、数据源和技能集。 有关权限列表，请参阅 Microsoft.Search/searchServices/*。
搜索索引数据参与者 数据 对索引中内容的读写访问权限。 此角色适用于需要导入、刷新或查询索引文档集合的开发人员或索引所有者。 此角色不支持索引创建或管理。 默认情况下，此角色适用于搜索服务上的所有索引。 请参阅授予对单个索引的访问权限缩小范围。
搜索索引数据读取者 数据 查询搜索索引的只读访问权限。 此角色适用于运行查询的应用和用户。 此角色不支持对对象定义的读取访问。 例如，无法读取搜索索引定义或获取搜索服务统计信息。 默认情况下，此角色适用于搜索服务上的所有索引。 请参阅授予对单个索引的访问权限缩小范围。

合并这些角色以获取足够的用例权限。

注意

如果禁用 Azure 基于角色的访问权限，则控制平面的内置角色（所有者、参与者、读取者）将继续可用。 禁用基于角色的访问只会删除与这些角色关联的数据相关权限。 如果已禁用数据平面角色，搜索服务参与者等效于控制平面参与者。

总结

权限 搜索索引数据读取者 搜索索引数据参与者 搜索服务参与者 所有者/参与者 读者
在 Azure 门户中查看资源 ❌ ❌ ✅ ✅ ✅
查看资源属性/指标/终结点 ❌ ❌ ✅ ✅ ✅
列出资源上的所有对象 ❌ ❌ ✅ ✅ ✅
访问配额和服务统计信息 ❌ ❌ ✅ ✅ ❌
读取/查询索引 ✅ ✅ ❌ ❌ ❌
上传用于编制索引的数据 ❌ ✅ ❌ ❌ ❌
创建或编辑索引/别名 ❌ ❌ ✅ ✅ ❌
创建、编辑和运行索引器/数据源/技能组 ❌ ❌ ✅ ✅ ❌
创建或编辑同义词映射 ❌ ❌ ✅ ✅ ❌
创建或编辑调试会话 ❌ ❌ ✅ ✅ ❌
创建或管理部署 ❌ ❌ ✅ ✅ ❌
创建或配置 Azure AI 搜索资源 ❌ ❌ ✅ ✅ ❌
在“密钥”下查看/复制/再生成密钥 ❌ ❌ ✅ ✅ ❌
查看角色/策略/定义 ❌ ❌ ✅ ✅ ❌
设置身份验证选项 ❌ ❌ ✅ ✅ ❌
配置专用连接 ❌ ❌ ✅ ✅ ❌
配置网络安全 ❌ ❌ ✅ ✅ ❌

所有者和参与者授予相同的权限，但只有所有者可分配角色。

如果启用了 API 密钥，所有者和参与者可在 Azure 门户中创建、读取、更新和删除对象。 Azure 门户在对数据平面 API 的内部调用上使用密钥。 如果你随后将 Azure AI 搜索配置为使用“仅角色”，则所有者和参与者将无法仅使用这些角色分配来管理 Azure 门户中的对象。 解决方案是分配更多角色，例如“搜索索引数据读取者”、“搜索索引数据参与者”和“搜索服务参与者”。

分配角色

在本部分中，为以下用途分配角色：

  • 服务管理
  • 对搜索服务的开发或写入访问权限
  • 查询的只读访问权限

为服务管理分配角色

作为服务管理员，你可以创建和配置搜索服务，并执行管理 REST API 或等效客户端库中所述的所有控制平面操作。 如果你是所有者或参与者，还可在 Azure 门户中执行大多数数据平面“搜索 REST API”任务。

角色 ID
Owner 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor b24988ac-6180-42a0-ab88-20f7382dd24c
Reader acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. 登录到 Azure 门户。

  2. 分配以下角色：

    • 所有者（对所有数据平面和控制平面操作拥有完整访问权限，查询权限除外）
    • 参与者（与所有者相同，但分配角色的权限除外）
    • 读取者（可监视和查看指标）

分配用于开发的角色

角色分配是跨搜索服务的全局分配。 若要将权限限定为单个索引，请使用 PowerShell 或 Azure CLI 创建自定义角色。

任务 角色 ID
CRUD 操作 Search Service Contributor 7ca78c08-252a-4471-8644-bb5ff32d4ba0
加载文档，运行索引作业 Search Index Data Contributor 8ebe5a00-799e-43f5-93ac-243d3dce84a7
查询索引 Search Index Data Reader 1407120a-92aa-4202-b7e9-c0e197c71c8f

可提供完整访问权限的另一种角色组合是参与者或所有者加上搜索索引数据读取者。

重要

如果为服务或索引配置基于角色的访问，并且还在请求中提供 API 密钥，则搜索服务将使用 API 密钥进行身份验证。

  1. 登录到 Azure 门户。

  2. 分配以下角色：

    • 搜索服务参与者（针对索引、索引器、技能集和其他顶层对象的 create-read-update-delete 操作）
    • 搜索索引数据参与者（加载文档并运行索引作业）
    • 搜索索引数据读取器（查询索引）

为只读查询分配角色

对只需要对索引具有读取访问权限的应用和进程，使用“搜索索引数据读取者”角色。

角色 ID
Search Index Data Reader 使用 PowerShell 1407120a-92aa-4202-b7e9-c0e197c71c8f

这是一个非常具体的角色。 它对搜索索引的文档集合授予 GET 或 POST 访问权限，用于搜索、自动完成和建议。 它不支持对索引或其他顶层对象或 GET 服务统计信息执行 GET 或 LIST 操作。

本部分提供了设置角色分配的基本步骤，并为了达到完整性目的存在于此处，但我们推荐使用 Azure AI 搜索而不使用密钥以获取关于配置应用以实现基于角色的访问的全面说明。

  1. 登录到 Azure 门户。

  2. 分配“搜索索引数据读取者”角色。

测试角色分配

使用客户端测试角色分配。 请记住，角色是累积性的，并且在资源（搜索服务）级别无法删除或拒绝范围限定为订阅或资源组级别的继承角色。

为应用程序配置无密钥连接，并在测试之前设置好角色分配。

  1. 登录 Azure 门户。

  2. 导航到你的搜索服务。

  3. 在“概述”页上，选择“索引”选项卡：

    • 搜索服务参与者可以查看和创建任何对象，但无法加载文档或查询索引。 若要验证权限，请创建搜索索引。

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

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

作为当前用户进行测试

如果你已经是搜索服务的参与者或所有者，则可为用户标识提供持有者令牌，以便向 Azure AI 搜索进行身份验证。

  1. 使用 Azure CLI 获取当前用户的持有者令牌：

    az account get-access-token --scope https://search.azure.com/.default

    或使用 PowerShell 获取：

    Get-AzAccessToken -ResourceUrl https://search.azure.com

  2. 在 Visual Studio Code 中，将这些变量粘贴到新文本文件中。

    @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

  3. 粘贴，然后发送请求以确认访问权限。 下面的这个用于查询 hotels-quickstart 索引

    POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2024-07-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }

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

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

Azure 门户目前不支持此粒度级别的角色分配，但可以使用 PowerShell 或 Azure CLI 实现此操作。

在 PowerShell 中，使用 New-AzRoleAssignment，并提供 Azure 用户或组名称以及分配范围。

  1. 加载 Azure 和 AzureAD 模块并连接到 Azure 帐户：

    Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount

  2. 添加范围限定为单个索引的角色分配：

    New-AzRoleAssignment -ObjectId <objectId> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

创建自定义角色

如果内置角色未提供适当的权限组合，你可以创建一个自定义角色来支持所需的操作。

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

这些步骤源自使用 Azure 门户创建或更新 Azure 自定义角色。 支持在搜索服务页从现有角色克隆。

这些步骤将创建一个自定义角色来补充搜索查询权限，以包括按名称列出索引的权限。 通常，列出索引被视为一项管理功能。

  1. 在 Azure 门户中，导航到你的搜索服务。

  2. 在左侧导航窗格中，选择“访问控制(IAM)”。

  3. 在操作栏中，选择“角色”。

  4. 右键单击“搜索索引数据读取者”（或其他角色），然后选择“克隆”打开“创建自定义角色”向导。

  5. 在“基本信息”选项卡上，为自定义角色提供名称（例如“搜索索引数据浏览者”），然后选择“下一步”。

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

  7. 在“添加权限”选项卡上，搜索并选择“Microsoft 搜索”磁贴。

  8. 为自定义角色设置权限。 在页面顶部，使用默认的“操作”选项：

    • 在“Microsoft.Search/operations”下，选择“读取: 列出所有可用操作”。
    • 在“Microsoft.Search/searchServices/indexes”下，选择“读取: 读取索引”。

  9. 在同一页上，切换到“数据操作”，然后在“Microsoft.Search/searchServices/indexes/documents”下选择“读取: 读取文档”。

    JSON 定义如以下示例所示：

    {
 "properties": {
     "roleName": "search index data explorer",
     "description": "",
     "assignableScopes": [
         "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
     ],
     "permissions": [
         {
             "actions": [
                 "Microsoft.Search/operations/read",
                 "Microsoft.Search/searchServices/indexes/read"
             ],
             "notActions": [],
             "dataActions": [
                 "Microsoft.Search/searchServices/indexes/documents/read"
             ],
             "notDataActions": []
         }
     ]
   }
 }

  10. 选择“查看 + 创建”以创建角色。 现在可将用户和组分配到该角色。

条件性访问

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

若要为 Azure AI 搜索启用条件访问策略，请执行以下步骤：

  1. 登录 Azure 门户。

  2. 搜索 Microsoft Entra 条件访问保护。

  3. 选择“策略”。

  4. 选择“新策略” 。

  5. 在策略的“云应用或操作”部分，根据你设置策略的方式，添加“Azure AI 搜索”作为云应用。

  6. 更新策略的其余参数。 例如，指定要将此策略应用于哪些用户和组。

  7. 保存策略。

重要

如果为搜索服务分配了托管标识，则特定的搜索服务将显示为可在条件访问策略中包含或排除的云应用。 无法对特定的搜索服务强制实施条件访问策略。 应确保选择常规的“Azure AI 搜索”云应用。

限制

  • 基于角色的访问控制可能会增加某些请求的延迟。 服务资源（索引、索引器等）和服务主体的每个唯一组合都会触发授权检查。 这些授权检查可能会给每个请求最多增加 200 毫秒的延迟。

  • 在罕见的情况下，请求源自大量不同的服务主体，而这些服务主体针对不同的服务资源（索引、索引器等），对于这种情况，授权检查可能会导致发生限制。 仅当在一秒钟内使用了搜索服务资源和服务主体的数百个独特组合时，才会发生限制。

排查基于角色的访问控制问题

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

  • 如果授权令牌来自托管标识，并且最近分配了适当的权限，则可能需要几个小时这些权限分配才能生效。

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