在 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 创建或更新服务为基于角色的访问控制配置服务。

将会通过 Microsoft Entra ID 对管理 REST API 的所有调用进行身份验证。如果在设置经过身份验证的请求时需要帮助，请参阅使用 REST 管理 Azure AI 搜索。

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

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-02-10

通过