在 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 建立或更新服務，以針對角色型存取控制設定您的服務。

對管理 REST API 的所有呼叫是透過 Microsoft Entra ID 進行驗證。 如需協助設定已驗證的要求，請參閱使用 REST 管理 Azure AI 搜尋服務。

1. 取得服務設定，以便檢閱目前的組態。

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

2. 使用 PATCH 以更新服務組態。 下列修改可啟用金鑰和角色型存取。 如果您想要僅限角色的設定，請參閱停用 API 金鑰。

   在 [properties] 底下，將 "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"
               }
           }
       }
   }
   

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

2. 使用 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 金鑰 (假設其已指定)。