本文說明如何在 Foundry IQ(Azure AI 搜尋服務)上啟用基於角色的存取控制(RBAC)以進行資料平面作業。 啟用 RBAC 後,你可以使用 Microsoft Entra ID 認證取代 API 金鑰。
重要
當您建立 Foundry IQ 服務時,預設採用金鑰驗證,但這並非最安全的選項。 我們建議您將它取代為角色型存取,如本文所述。
僅可停用 資料平面 角色。 服務管理的角色 (控制平面) 是內建的,因此無法將其啟用或停用。
如果您在僅角色的 Foundry IQ 服務的 活動記錄 中觀察到與鍵值相關的活動,例如取得管理員金鑰,這些動作會在控制平面啟動,且不會影響您的內容或內容相關操作。
必要條件
啟用資料平面作業的角色型存取
將您的 Foundry IQ 服務設定為在提供 OAuth2 存取權杖的資料請求時識別 授權標頭 。
當您啟用資料平面的角色時,變更會立即生效,但請稍候幾秒鐘,然後再指派角色。
未經授權要求的預設失敗模式為 http401WithBearerChallenge。 或者,您可以將失敗模式設定為 http403。
前往 Azure 入口網站中的 Foundry IQ 服務。
選擇 設定 ,然後在左側窗格選擇 按鍵 。
選擇 [角色型控件]。 只有在您目前使用密鑰且需要時間將用戶端轉換為角色型訪問控制時,才選擇 [兩者 ]。
| 選項 |
描述 |
| 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 search service update
如需更多資訊,請參閱使用 Azure CLI 管理 Foundry IQ 服務。
執行此命令,將驗證類型設定為僅限角色:
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 管理您的 Foundry IQ 服務。
使用管理 REST API 建立或更新服務,以針對角色型存取控制設定您的服務。
對管理 REST API 的所有呼叫是透過 Microsoft Entra ID 進行驗證。 如需設定已驗證請求的協助,請參閱 使用 REST 管理 Foundry IQ。
取得服務設定,以便檢閱目前的組態。
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 入口網站中的 Foundry IQ 服務。
選擇 設定 ,然後在左側窗格選擇 按鍵 。
選取 [API 金鑰]。
停用 API 金鑰驗證
如果您只使用內建的角色與 Microsoft Entra 驗證,則可在服務中停用金鑰存取或本機驗證。 停用 API 金鑰會讓 Foundry IQ 服務拒絕所有在標頭中傳遞 API 金鑰的資料相關請求。
管理員 API 金鑰可以停用,但無法刪除。 可以刪除查詢 API 金鑰。
需要擁有者或參與者權限才能停用安全性功能。
前往 Azure 入口網站中的 Foundry IQ 服務。
在左導覽窗格中,選取 [金鑰]。
選取角色型存取控制。
變更會立即生效,但在測試之前請稍候幾秒鐘。 假設您有權將角色指派為擁有者、服務管理員或共同管理員的成員,您可以使用入口網站功能來測試角色型存取。
若要停用金鑰型驗證,請將 -disableLocalAuth 設定為 true。 這與上一節中呈現的「啟用僅限角色」指令碼語法相同。
az search service update \
--name YOUR-SEARCH-SERVICE-NAME \
--resource-group YOUR-RESOURCE-GROUP-NAME \
--disable-local-auth
若要重新啟用金鑰驗證,請將 -disableLocalAuth 設定為 false。 Foundry IQ 服務會自動恢復接受該要求中的 API 金鑰(假設已指定這些金鑰)。
如需更多資訊,請參閱使用 Azure CLI 管理您的 Foundry IQ 服務。
若要停用金鑰型驗證,請將 DisableLocalAuth 設定為 true。 這與上一節中呈現的「啟用僅限角色」指令碼語法相同。
Set-AzSearchService `
-Name YOUR-SEARCH-SERVICE-NAME `
-ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
-DisableLocalAuth 1
若要重新啟用金鑰驗證,請將 DisableLocalAuth 設定為 false。 Foundry IQ 服務會自動恢復接受請求中提供的 API 金鑰(前提是已指定這些金鑰)。
欲了解更多資訊,請參閱 使用 PowerShell 管理您的 Foundry IQ 服務。
若要停用金鑰型驗證,請將 "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。 Foundry IQ 服務會自動恢復接受該要求中的 API 金鑰(假設這些金鑰已被指定)。
參考:服務 - 建立或更新
下一步