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

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

项目
07/08/2024

在分配角色以授权访问 Azure AI 搜索之前，请在搜索服务上启用基于角色的访问控制。

对数据平面操作的基于角色的访问是可选的，但建议将其作为更安全的选项。该选项的替代方法是基于密钥的身份验证，这是默认选项。

服务管理（控制平面）的角色是内置的，无法启用或禁用。

注意

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

先决条件

任何区域中的搜索服务，包括免费层。
“所有者”、“用户访问权限管理员”或具有 Microsoft.Authorization/roleAssignments/write 权限的自定义角色。

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

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

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

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

登录到 Azure 门户，然后打开搜索服务页面。
选择“设置”，然后在左侧导航窗格中选择“键”。

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

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

作为管理员，如果你选择仅限角色的方法，请为用户帐户分配数据平面角色，以还原对 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

有关详细信息，请参阅使用 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

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

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

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

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

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

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

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

（可选）设置“aadAuthFailureMode”，以指定是否在身份验证失败时返回 401 而非 403。有效值为“http401WithBearerChallenge”或“http403”。
```
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```

禁用基于角色的访问控制

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

倒过来完成前面执行的步骤以启用基于角色的访问。

登录到 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.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01

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

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
{
    "properties": {
        "disableLocalAuth": true
    }
}

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

限制

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

后续步骤

设置角色以访问搜索服务

通过