在 Azure AI 搜尋服務中啟用或停用角色型存取控制

Note

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

本文說明如何在 Azure AI 搜尋服務上啟用基於角色的存取控制（RBAC）來進行資料平面操作。啟用 RBAC 後，你可以使用 Microsoft Entra ID 認證取代 API 金鑰。

重要

當您建立搜尋服務時，金鑰型驗證是預設值，但不是最安全的選項。我們建議您將它取代為角色型存取，如本文所述。

僅可停用資料平面角色。服務管理的角色 (控制平面) 是內建的，因此無法將其啟用或停用。

如果你在僅限角色搜尋服務的 活動日誌 中觀察到與金鑰相關的活動，例如「取得管理員金鑰」，這些動作是在控制平面中發起的，不會影響你的內容或內容相關的操作。

必要條件

任何區域、任何層級上的搜尋服務，包括免費。
擁有者、 使用者存取管理員，或是自訂角色，使用 Microsoft.Authorization/roleAssignments/write 權限來啟用 RBAC。
啟用 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

參考資料：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

參考資料：Set-AzSearchService

如需詳細資訊，請參閱使用 PowerShell 管理 Azure AI 搜尋服務。

使用管理 REST API 建立或更新服務，以針對角色型存取控制設定您的服務。

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

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

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

使用 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=2025-05-01
{
    "properties": {
        "disableLocalAuth": false,
        "authOptions": {
            "aadOrApiKey": {
                "aadAuthFailureMode": "http401WithBearerChallenge"
            }
        }
    }
}
```
成功的請求會回傳更新的服務設定 200 OK 。

參考資料：服務 - 建立或更新

停用角色型存取控制

可以停用資料平面作業的角色型存取控制，並改用金鑰型驗證。您可能會執行此動作，作為測試工作流程的一部分，例如排除權限問題。

若要停用 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.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01

使用 PATCH 以更新服務組態。下列修改會將 "authOptions" 設定為 null。

PATCH https://management.azure.com/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 金鑰 (假設其已指定)。

參考資料：服務 - 建立或更新

下一步

設定角色以存取搜尋服務

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-03