在 Azure AI 搜尋中啟用或停用角色型訪問控制
如果您想要使用 Azure 角色型訪問控制來連線到 Azure AI 搜尋服務，本文說明如何為您的搜尋服務啟用它。
數據平面作業的角色型存取是選擇性的，但建議使用。 替代方法是 金鑰型驗證，這是預設值。
服務管理的角色（控制平面）內建，無法啟用或停用。
必要條件
啟用數據平面作業的角色型存取
當您啟用數據平面的角色時，變更會立即生效，但請稍候幾秒鐘，再指派角色。
預設失敗模式為 http401WithBearerChallenge。 或者，您可以將失敗模式設定為 http403。
啟用角色型存取之後，搜尋服務會在 提供 OAuth2 存取令牌的數據平面要求上辨識授權 標頭。
登入 Azure 入口網站，並開啟搜尋服務頁面。
選取 [ 設定] ，然後選取 左側瀏覽窗格中的 [金鑰 ]。
如果您目前使用金鑰，且需要時間將用戶端轉換為角色型訪問控制，請選擇 [角色型控件 ] 或 [兩者 ]。
| 選項 |
描述 |
| API 金鑰 |
(預設)。 要求標頭上需要 API 金鑰以進行授權。 |
| 角色型存取控制 |
需要角色指派中的成員資格才能完成工作。 它也需要要求上的授權標頭。 |
| 兩者 |
要求是有效的，使用 API 金鑰或角色型存取控制，但如果您同時在相同的要求中提供，則會使用 API 金鑰。 |
執行此文稿僅支援角色：
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 金鑰 (假設其已指定)。
限制
下一步
