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

使用角色连接到 Azure AI 搜索

项目
09/03/2024

Azure 为平台上运行的所有服务提供全局身份验证和基于角色的授权系统。在 Azure AI 搜索中，可以为以下用途分配 Azure 角色：

服务管理
对搜索服务的开发或写入访问权限
查询的只读访问权限
一定范围内对单个索引的访问权限

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

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

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

先决条件

任何区域中位于任何层的搜索服务，针对基于角色的访问而启用。
“所有者”、“用户访问权限管理员”或具有 Microsoft.Authorization/roleAssignments/write 权限的自定义角色。

Azure AI 搜索中使用的内置角色

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

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

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

注意

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

分配角色

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

服务管理

角色 ID

Owner 8e3af657-a8ff-443c-a75c-2fe8c4bcb635

Contributor b24988ac-6180-42a0-ab88-20f7382dd24c

Reader acdd72a7-3385-48ef-bd42-f606fba81ae7

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

对搜索服务的开发或写入访问权限

任务	角色	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

查询的只读访问权限

角色 ID

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

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

为服务管理分配角色

作为服务管理员，你可以创建和配置搜索服务，并执行管理 REST API 或等效客户端库中所述的所有控制平面操作。根据具体角色，你还可以执行大多数数据平面搜索 REST API 任务。

Azure 门户
PowerShell

登录 Azure 门户。
导航到你的搜索服务。
在左侧导航窗格中，选择“访问控制(IAM)”。
选择“+ 添加” > “添加角色分配”。
选择适用的角色：
- 所有者（对所有数据平面和控制平面操作拥有完整访问权限，查询权限除外）
- 参与者（与所有者相同，但分配角色的权限除外）
- 读取者（可监视和查看指标）
在成员选项卡上，选择 Microsoft Entra 用户或组标识。
在“查看 + 分配”选项卡上，选择“查看 + 分配”，以分配角色。

使用 PowerShell 分配角色时，请调用 New-AzRoleAssignment，并提供 Azure 用户或组名称以及分配范围。

此示例创建一个范围限定为搜索服务的角色分配：

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

分配用于开发的角色

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

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

重要

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

Azure 门户
PowerShell

登录 Azure 门户。
导航到你的搜索服务。
在左侧导航窗格中，选择“访问控制(IAM)”。
选择“+ 添加” > “添加角色分配”。
选择一个角色：
- 搜索服务参与者（针对索引、索引器、技能集和其他顶层对象的 create-read-update-delete 操作）
- 搜索索引数据参与者（加载文档并运行索引作业）
- 搜索索引数据读取器（查询索引）
可提供完整访问权限的另一种角色组合是参与者或所有者加上搜索索引数据读取者。
在成员选项卡上，选择 Microsoft Entra 用户或组标识。
在“查看 + 分配”选项卡上，选择“查看 + 分配”，以分配角色。
对其他角色重复此操作。大多数开发者需要同时拥有这三个角色。

使用 PowerShell 分配角色时，请调用 New-AzRoleAssignment，并提供 Azure 用户或组名称以及分配范围。

此示例创建一个范围限定为搜索服务的角色分配：

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

此示例创建一个范围限定为特定索引的角色分配：

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

为只读查询分配角色

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

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

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

Azure 门户
PowerShell

登录 Azure 门户。
导航到你的搜索服务。
在左侧导航窗格中，选择“访问控制(IAM)”。
选择“+ 添加” > “添加角色分配”。
选择“搜索索引数据读取者”角色。
在成员选项卡上，选择 Microsoft Entra 用户或组标识。如果要为另一个服务设置权限，则可能使用的是系统或用户托管标识。如果角色分配用于服务标识，请选择该选项。
在“查看 + 分配”选项卡上，选择“查看 + 分配”，以分配角色。

使用 PowerShell 分配角色时，请调用 New-AzRoleAssignment（提供 Azure 用户或组名称以及分配的范围）。

获取订阅 ID、搜索服务资源组和搜索服务名称。

获取 Azure 服务的对象标识符，例如 Azure OpenAI。

 Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>

获取角色定义并查看权限，以确保这是所需的角色。
```
Get-AzRoleDefinition -Name "Search Index Data Reader"
```

创建角色分配，替换占位符的有效值。

New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME

下面是限定为特定索引的角色分配的示例：

New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
    -RoleDefinitionName "Search Index Data Reader" `
    -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME

测试角色分配

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

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

登录 Azure 门户。
导航到你的搜索服务。
在“概述”页上，选择“索引”选项卡：
- 搜索服务参与者可以查看和创建任何对象，但无法加载文档或查询索引。若要验证权限，请创建搜索索引。
- 搜索索引数据参与者可以加载文档。在导入数据向导外部的门户中没有加载文档选项，但你可以重置并运行索引器，以确认文档加载权限。
- 搜索索引数据读取者可以查询索引。若要验证权限，请使用搜索资源管理器。你应该可以发送查询并查看结果，但无法查看或创建索引定义。

此方法假定 Visual Studio Code 具有 REST 客户端扩展。

打开 Azure CLI 的命令 shell 并登录到你的 Azure 订阅。
```
az login
```
获取租户 ID 和订阅 ID。该 ID 会在稍后的步骤中用作变量。
```
az account show
```

获取访问令牌。

az account get-access-token --query accessToken --output tsv

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

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

粘贴，然后发送使用你指定的变量的请求。对于“搜索索引数据读取者”角色，可以发送查询。可以使用任何受支持的 API 版本。

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
     }

有关如何获取特定环境的令牌的详细信息，请参阅使用 REST API 管理 Azure AI 搜索服务和 Microsoft 标识平台身份验证库。

使用 Azure.Search.Documents 包。
使用 Azure.Identity for .NET 进行令牌身份验证。对于大多数情况，Microsoft 建议使用 DefaultAzureCredential()。

下面是使用 DefaultAzureCredential() 的客户端连接的示例。

// Create a SearchIndexClient to send create/delete index commands
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());

// Create a SearchClient to load and query documents
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

下面是另一个使用客户端机密凭据的示例：

var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);

使用 azure.search.documents（用于 Java 的 Azure SDK）。
使用 Azure.Identity for Python 进行令牌身份验证。
如果 Python 客户端是在服务器端执行的应用程序，请使用 DefaultAzureCredential。如果应用在浏览器中运行，则启用交互式身份验证。

下面是一个示例：

from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
endpoint = "https://<mysearch>.search.windows.net"
index_name = "myindex"
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

作为当前用户进行测试

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

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

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

或使用 PowerShell 获取：

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

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

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

粘贴，然后发送请求以确认访问权限。下面的这个用于查询 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
     }

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

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

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

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

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

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

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

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 自定义角色。支持在搜索服务页从现有角色克隆。

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

在 Azure 门户中，导航到你的搜索服务。
在左侧导航窗格中，选择“访问控制(IAM)”。
在操作栏中，选择“角色”。
右键单击“搜索索引数据读取者”（或其他角色），然后选择“克隆”打开“创建自定义角色”向导。
在“基本信息”选项卡上，为自定义角色提供名称（例如“搜索索引数据浏览者”），然后选择“下一步”。
在“权限”选项卡上，选择“添加权限”。
在“添加权限”选项卡上，搜索并选择“Microsoft 搜索”磁贴。
为自定义角色设置权限。在页面顶部，使用默认的“操作”选项：
- 在“Microsoft.Search/operations”下，选择“读取: 列出所有可用操作”。
- 在“Microsoft.Search/searchServices/indexes”下，选择“读取: 读取索引”。

在同一页上，切换到“数据操作”，然后在“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": []
         }
     ]
   }
 }

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

该 PowerShell 示例显示了用于创建自定义角色的 JSON 语法，该角色是“搜索索引数据读取者”的克隆，但可以按名称列出所有索引。

查看原子权限列表以确定所需的权限。对于此示例，需要执行以下操作：

"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/read",
"Microsoft.Search/searchServices/indexes/read"

设置 PowerShell 会话以创建自定义角色。有关详细说明，请参阅 Azure PowerShell
以 JSON 文档的形式提供角色定义。以下示例演示了使用 PowerShell 创建自定义角色的语法。

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

注意

如果可分配的范围处于索引级别，则数据操作应是 "Microsoft.Search/searchServices/indexes/documents/read"。

条件性访问

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

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

登录 Azure 门户。
搜索 Microsoft Entra 条件访问保护。
选择“策略”。
选择“新策略” 。
在策略的“云应用或操作”部分，根据你设置策略的方式，添加“Azure AI 搜索”作为云应用。
更新策略的其余参数。例如，指定要将此策略应用于哪些用户和组。
保存策略。

重要

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

限制

基于角色的访问控制可能会增加某些请求的延迟。服务资源（索引、索引器等）和服务主体的每个唯一组合都会触发授权检查。这些授权检查可能会给每个请求最多增加 200 毫秒的延迟。
在罕见的情况下，请求源自大量不同的服务主体，而这些服务主体针对不同的服务资源（索引、索引器等），对于这种情况，授权检查可能会导致发生限制。仅当在一秒钟内使用了搜索服务资源和服务主体的数百个独特组合时，才会发生限制。

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

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

如果授权令牌来自托管标识，并且最近分配了适当的权限，则可能需要几个小时这些权限分配才能生效。
搜索服务的默认配置是基于密钥的身份验证。如果未将默认密钥设置更改为“两者”或“基于角色的访问控制”，则无论基础权限如何，所有使用基于角色的身份验证的请求都将被自动拒绝。

通过