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

1. 登录到 Azure 门户，然后打开搜索服务页面。

2. 选择“设置”，然后在左侧导航窗格中选择“键”。

   

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

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

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

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

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

2. 使用 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=2024-07-01
   {
       "properties": {
           "disableLocalAuth": false,
           "authOptions": {
               "aadOrApiKey": {
                   "aadAuthFailureMode": "http401WithBearerChallenge"
               }
           }
       }
   }
   

1. 在 Azure 门户中，导航到你的搜索服务。

2. 在左侧导航窗格中，选择“密钥”。

3. 选择“基于角色的访问控制”。

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

若要禁用基于密钥的身份验证，请将“-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。

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

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

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

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

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