在Azure AI 搜索中启用或禁用基于角色的访问控制

本文介绍如何为Azure AI 搜索上的数据平面操作启用基于角色的访问控制（RBAC）。启用 RBAC 后，可以使用Microsoft Entra ID身份验证而不是 API 密钥。

重要

创建搜索服务时，基于密钥的身份验证是默认设置，但它不是最安全的选项。建议将其替换为本文中所述的基于角色的访问。

在为 Azure AI 搜索启用授权数据平面访问的角色之前，必须在您的搜索服务上启用基于角色的访问控制。服务管理（控制平面）的角色是内置的，无法启用或禁用。

如果在仅限角色的搜索服务中活动日志观察到与密钥相关的活动（例如获取管理员密钥），这些操作是在控制平面上启动的，不会影响您的内容或与内容相关的操作。

先决条件

任何区域，任何级别，包括免费级别的搜索服务。
所有者、用户访问管理员或具有 Microsoft.Authorization/roleAssignments/write 权限的自定义角色。
启用 RBAC 后，需要数据平面角色才能访问内容： 搜索服务参与者、 搜索索引数据参与者和 搜索索引数据读取者。有关详细信息，请参阅 “分配角色 ”。

为数据平面操作启用基于角色的访问

配置搜索服务，以识别提供 OAuth2 访问令牌的数据请求上的授权头。

为数据平面启用角色时，更改会立即生效，但请等待几秒钟，然后再分配角色。

未经授权的请求的默认失败模式为 http401WithBearerChallenge。或者，可以将失败模式设置为 http403。

登录到 Azure 门户并导航到搜索服务。
选择 “设置” ，然后在左窗格中选择 “密钥 ”。

选择“基于角色的控制”。如果当前使用的是密钥，并且需要时间将客户端转换到基于角色的访问控制，则仅选择“两者”。

选项	说明
API 密钥（默认）	需要用请求标头上的 API 密钥进行授权。
基于角色的访问控制（推荐）	要完成此任务，需要在角色分配中拥有成员资格。还需要请求上的授权标头。
两者	使用 API 密钥或基于角色的访问控制的请求均有效，但如果在同一请求中提供这两种方式，则使用 API 密钥。

作为管理员，如果选择仅限角色的方法，将数据平面角色分配给用户帐户，以便通过 Azure 门户中的数据平面操作还原完全管理访问权限。角色包括搜索服务参与者、搜索索引数据参与者和搜索索引数据读取者。如果需要等效的访问权限，则需要前两个角色。

有时，角色分配可能需要五到十分钟才能生效。在发生这种情况之前，以下消息将显示在用于数据平面操作的Azure门户页面中。

仅针对支持角色运行此脚本。

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

或者，运行此脚本以支持密钥和角色：

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --aad-auth-failure-mode http401WithBearerChallenge `
  --auth-options aadOrApiKey

Reference：az 搜索服务更新

有关详细信息，请参阅使用 Azure CLI 管理您的 Azure AI 搜索服务。

运行以下命令，仅将身份验证类型设置为角色：

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

或者，运行此命令以支持密钥和角色：

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -AuthOption AadOrApiKey

Reference：Set-AzSearchService

有关详细信息，请参阅使用 PowerShell 管理Azure AI 搜索服务。

使用管理 REST API 创建或更新服务为基于角色的访问控制配置服务。

对管理 REST API 的所有调用都通过Microsoft Entra ID进行身份验证。有关设置经过身份验证的请求的帮助，请参阅 Manage Azure AI 搜索 using REST。

获取服务设置，以便可以查看当前配置。

GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01

使用 PATCH 更新服务配置。以下修改启用基于密钥的访问和基于角色的访问。如果你需要仅限角色的配置，请参阅禁用 API 密钥。

在“属性”下，将“authOptions”设置为“aadOrApiKey”。 “disableLocalAuth”属性必须为 false 才能设置“authOptions”。

（可选）设置“aadAuthFailureMode”，以指定是否在身份验证失败时返回 401 而非 403。有效值为“http401WithBearerChallenge”或“http403”。
```
PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```
成功的请求返回更新的服务配置 200 OK。

Reference：Services - 创建或更新

禁用基于角色的访问控制

可以禁用数据平面操作的基于角色的访问控制，并改用基于密钥的身份验证。可以在测试工作流中执行此操作，例如排除权限问题。

若要在Azure门户中禁用基于角色的访问控制，请执行以下操作：

登录到 Azure 门户并打开搜索服务页。
选择 “设置” ，然后在左窗格中选择 “密钥 ”。
选择 API 密钥。

禁用 API 密钥身份验证

如果专门使用内置角色和Microsoft Entra身份验证，则可以在服务上禁用密钥访问或本地身份验证。禁用 API 密钥会导致搜索服务拒绝在标头中传递 API 密钥的所有与数据相关的请求。

可以禁用管理员 API 密钥，但不能删除。可以删除查询 API 密钥。

禁用安全功能需要所有者或参与者权限。

在Azure门户中，导航到搜索服务。
在左侧导航窗格中，选择“密钥”。
选择“基于角色的访问控制”。

更改会立即生效，但请等待几秒钟，然后再进行测试。假设你有权将角色分配为所有者、服务管理员或共同管理员的成员，则可以使用门户功能来测试基于角色的访问。

若要禁用基于密钥的身份验证，请将“-disableLocalAuth”设置为 true。这与上一部分中显示的“仅启用角色”脚本的语法相同。

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --disable-local-auth

若要重新启用密钥身份验证，请将“-disableLocalAuth”设置为 false。搜索服务将自动继续接受请求上的 API 密钥（假设已指定）。

有关详细信息，请参阅使用 Azure CLI 管理您的 Azure AI 搜索服务。

若要禁用基于密钥的身份验证，请将“DisableLocalAuth”设置为 true。这与上一部分中显示的“仅启用角色”脚本的语法相同。

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -DisableLocalAuth 1

若要重新启用密钥身份验证，请将“DisableLocalAuth”设置为 false。搜索服务将自动继续接受请求上的 API 密钥（假设已指定）。

有关详细信息，请参阅使用 PowerShell 管理Azure AI 搜索服务。

若要禁用基于密钥的身份验证，请将“disableLocalAuth”设置为 true。

获取服务设置，以便可以查看当前配置。

GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01

使用 PATCH 更新服务配置。以下修改将“authOptions”设置为 null。

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-05-01
{
    "properties": {
        "disableLocalAuth": true
    }
}

成功的请求返回更新的服务配置 200 OK。

若要重新启用密钥身份验证，请将“disableLocalAuth”设置为 false。搜索服务将自动继续接受请求上的 API 密钥（假设已指定）。

Reference：Services - 创建或更新

后续步骤

设置角色以访问搜索服务

Last updated on 2026-04-08

通过