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

發行項
11/09/2024

Azure AI 搜尋預設會使用密鑰型驗證，但它完全支援透過 Azure 角色型存取控制（RBAC）的所有控制平面和數據平面作業Microsoft Entra ID 驗證和數據平面作業。

您必須先在搜尋服務上啟用角色型訪問控制，才能為授權的數據平面存取指派角色給 Azure AI 搜尋服務。服務管理的角色 (控制平面) 是內建的，因此無法將其啟用或停用。

注意

數據平面是指針對搜尋服務端點的作業，例如編製索引或查詢，或搜尋服務 REST API 或對等的 Azure SDK 用戶端連結庫中指定的任何其他作業。 控制平面 是指 Azure 資源管理，例如建立或設定搜尋服務。

必要條件

在任何階層上，任何區域中的搜尋服務，包括免費。
擁有者、使用者存取管理員或具有 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 建立或更新服務，以針對角色型存取控制設定您的服務。

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

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

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-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=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 毫秒的延遲。
在少數情況下，要求源自大量不同的服務主體，所有目標都是不同的服務資源（索引、索引器等等），授權檢查可能會導致節流。只有在一秒內使用了數百個唯一的搜尋服務資源和服務主體的組合時，才會發生節流。

下一步

設定角色以存取搜尋服務

共用方式為