在 Azure AI 搜尋服務中啟用或停用角色型存取控制
您必須先在搜尋服務上啟用角色型存取控制，才能將角色指派給 Azure AI 搜尋服務的授權存取權。
資料平面作業的角色型存取是選用的，但建議作為更安全的選項。 替代方法是金鑰型驗證，這是預設值。
服務管理的角色 (控制平面) 是內建的，因此無法將其啟用或停用。
注意
「資料平面」是指針對搜尋服務端點的作業，例如編製索引或查詢，或搜尋 REST API 或對等 Azure SDK 用戶端程式庫中指定的任何其他作業。
必要條件
啟用資料平面作業的角色型存取
設定您的搜尋服務，以辨識提供 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 金鑰 (假設其已指定)。
限制
下一步
