使用角色连接到Azure AI 搜索

注意

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。

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

如果将多个角色分配给安全主体，则会合并权限。角色分配适用于所有工具和客户端库。可以使用任何受支持的方法分配角色。

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

小窍门

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

先决条件

启用了基于角色的访问的 Azure AI 搜索服务（任何区域和任何层）。
分配Azure角色的权限。以下任一角色都起作用：
- Owner
- 用户访问管理员
- 基于角色的访问控制管理员
- 具有 Microsoft.Authorization/roleAssignments/write 权限的自定义角色

内置角色

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

控制平面： 服务预配、配置和管理的操作。控制平面操作包括创建或删除搜索服务、列出 API 密钥以及管理网络和身份验证设置。可通过 Azure 资源管理器 REST API、Search Management REST API 和等效Azure SDK客户端库获得。
数据平面： 针对搜索服务终结点的操作。数据平面操作分为两类：对象管理和内容访问。可通过 Search Service REST API 和等效Azure SDK客户端库获得。

角色说明

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

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

重要

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

权限摘要

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

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

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

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

分配内置角色

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

服务管理
发展
只读访问权限

为服务管理分配角色

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

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

Azure 门户
PowerShell

请在 Azure 门户中打开您的搜索服务。
在左窗格中，选择“访问控制”（IAM）。
选择+ 添加>添加角色分配。
选择角色： 所有者、 参与者或读者。
在 Members 选项卡上，选择Microsoft Entra用户或组标识。如果要为另一个Azure服务设置权限，请选择系统分配的或用户分配的托管标识。
在“查看 + 分配”选项卡上，选择该选项以分配角色。

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

示例中在搜索服务范围内创建了一个角色指派。

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

Reference：New-AzRoleAssignment

分配用于开发的角色

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

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

Azure 门户
PowerShell

请在 Azure 门户中打开您的搜索服务。
在左窗格中，选择“访问控制”（IAM）。
选择+ 添加>添加角色分配。
选择 “搜索服务参与者”。
在 Members 选项卡上，选择Microsoft Entra用户或组标识。如果要为另一个Azure服务设置权限，请选择系统分配的或用户分配的托管标识。
在“查看 + 分配”选项卡上，选择该选项以分配角色。
重复这些步骤以分配 搜索索引数据参与者 和 搜索索引数据读取器。

使用 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>"

Reference：New-AzRoleAssignment

为只读访问权限分配角色

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

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

Azure 门户
PowerShell

请在 Azure 门户中打开您的搜索服务。
在左窗格中，选择“访问控制”（IAM）。
选择+ 添加>添加角色分配。
选择 “搜索索引数据读取者 ”角色。
在 Members 选项卡上，选择Microsoft Entra用户或组标识。如果要为另一个Azure服务设置权限，请选择系统分配的或用户分配的托管标识。
在“查看 + 分配”选项卡上，选择该选项以分配角色。

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

获取订阅 ID、搜索服务资源组和搜索服务名称。
获取Azure服务的对象标识符。
```
 Get-AzADServicePrincipal -SearchString <your-azure-aiservice-resource-name>
```
输出包括一个属性，其中包含分配角色所需的对象 ID。
获取角色定义并查看权限，以确保这是所需的角色。
```
Get-AzRoleDefinition -Name "Search Index Data Reader"
```

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

New-AzRoleAssignment -ObjectId <your-azure-aiservice-object-id> -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group>/providers/Microsoft.Search/searchServices/<your-search-service-name>

成功的分配返回角色分配详细信息，包括 RoleAssignmentId。

以下是一个关于特定索引的角色分配的示例：

New-AzRoleAssignment -ObjectId <your-azure-aiservice-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>

Reference：New-AzRoleAssignment

测试角色分配

使用客户端测试角色分配。请记住，角色是可以叠加的。不能在资源（搜索服务）级别删除或拒绝那些在订阅或资源组级别上已限定作用域的继承角色。

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

请在 Azure 门户中打开您的搜索服务。
在左窗格中，选择 “搜索管理>索引 ”以测试与索引相关的权限：
- 搜索服务参与者可以创建、修改和删除搜索对象，但无法加载文档或运行查询。若要验证权限，请创建搜索索引。
- 搜索索引数据参与者可以加载文档。在 导入数据 向导外部的 Azure 门户中没有加载文档选项，但可以重置并运行索引器以确认文档加载权限。
- 搜索索引数据读取器可以查询索引。若要验证权限，请使用搜索资源管理器。应能够发送查询和查看结果，但不应能够查看索引定义或创建索引。

此方法假定使用 Visual Studio Code 的 REST 客户端扩展。

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

获取Azure AI 搜索数据平面的访问令牌。

az account get-access-token --scope https://search.azure.cn/.default --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=2026-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

    {
         "queryType": "simple",
         "search": "motel",
         "filter": "",
         "select": "HotelName,Description,Category,Tags",
         "count": true
     }
```
参考：搜索文档

成功的查询返回具有匹配文档的搜索结果。如果索引为空或没有匹配项， value 则包含空数组。

小窍门

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

安装所需的包：

dotnet add package Azure.Search.Documents
dotnet add package Azure.Identity

使用 Azure.Identity for .NET 进行令牌身份验证。对于大多数方案，Azure建议使用 DefaultAzureCredential()。

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

// Create a SearchIndexClient to send create/delete index commands
// Requires Search Service Contributor role
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());

// Create a SearchClient to load and query documents
// Requires Search Index Data Contributor (load) or Search Index Data Reader (query)
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

Reference：SearchClient、SearchIndexClient、DefaultAzureCredential

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

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

下面是运行查询的示例：

SearchResults<SearchDocument> response = srchclient.Search<SearchDocument>("motel");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    Console.WriteLine(result.Document["HotelName"]);
}

成功的查询返回搜索结果。如果没有文档匹配，则结果集合为空。

安装所需的包：

pip install azure-search-documents azure-identity

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

下面是一个示例：

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

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

Reference：SearchClient、 DefaultAzureCredential

安装所需的包：

npm install @azure/search-documents @azure/identity

使用 Azure.Identity for JavaScript 进行令牌身份验证。
如果使用 React，请使用 InteractiveBrowserCredential 进行 Microsoft Entra 身份验证到 Azure AI 搜索。有关详细信息，请参阅何时使用 @azure/identity。

Reference：SearchClient、 DefaultAzureCredential

将所需的依赖项添加到pom.xml：

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-search-documents</artifactId>
  <version>11.7.4</version>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
  <version>1.15.0</version>
</dependency>

使用 Azure.Identity for Java 进行令牌身份验证。
对在 Azure 上运行的应用使用 DefaultAzureCredential。

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

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

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

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

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

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

将角色分配作用域限定为单个索引

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

Reference：New-AzRoleAssignment

创建自定义角色

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

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

登录到 Azure 门户并导航到搜索服务。
在左窗格中，选择“访问控制”（IAM）。
在“ 角色 ”选项卡上，找到 “搜索索引数据读取者 ”或其他角色，选择省略号（...），然后选择“ 克隆”。
在Basics选项卡上，输入自定义角色的名称，例如“搜索索引数据资源管理器”，然后选择Next。
在“ 权限 ”选项卡上，选择“ 添加权限”。
在 Add permissions 窗格中，选择Microsoft 搜索磁贴。
在顶部选择 “操作” 后，设置以下权限：
- 在 Microsoft.Search/operations 下，选择 Read ：列出所有可用操作。
- 在 Microsoft.Search/searchServices/indexes 下，选择 Read ： Read Index。

切换到顶部的 Data Actions，然后在 Microsoft.Search/searchServices/indexes/documents 下，选择 Read： Read 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": []
         }
     ]
   }
 }

选择 “添加” 关闭窗格。
选择“查看 + 创建”以创建角色。

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

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 条件访问。
在“ 概述 ”页上，选择“ 创建新策略”。
在 Cloud 应用或操作下，添加 Azure AI 搜索 作为云应用，具体取决于设置策略的方式。
更新策略的剩余参数。例如，指定策略应用到的用户和组。
保存策略。

重要

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

故障排除

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

搜索服务的默认配置是基于密钥的身份验证。如果不将此设置更改为 “两者 ”或 “基于角色的访问控制”，则无论基础权限如何，使用基于角色的身份验证的所有请求都会自动被拒绝。
如果请求包含 API 密钥以及基于角色的凭据，服务将使用密钥进行身份验证。从请求标头中删除 API 密钥，以使用基于角色的身份验证。
如果授权令牌来自托管标识，而且你最近分配了相应的权限，可能需要几个小时权限分配才会生效。
如果具有文档级权限的查询未返回预期结果，请使用搜索索引数据参与者，或者创建具有提升权限的自定义角色进行调查。

后续步骤

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

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

Last updated on 2026-07-27

使用角色连接到Azure AI 搜索

先决条件

内置角色

角色说明

权限摘要

分配内置角色

为服务管理分配角色

分配用于开发的角色

为只读访问权限分配角色

测试角色分配

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

创建自定义角色

创建条件访问策略

故障排除

后续步骤

その他のリソース