在 Foundry IQ(Azure AI 搜尋服務)中啟用或停用基於角色的存取控制

Note

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

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

重要

當您建立 Foundry IQ 服務時,預設採用金鑰驗證,但這並非最安全的選項。 我們建議您將它取代為角色型存取,如本文所述。

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

如果您在僅角色的 Foundry IQ 服務的 活動記錄 中觀察到與鍵值相關的活動,例如取得管理員金鑰,這些動作會在控制平面啟動,且不會影響您的內容或內容相關操作。

必要條件

  • Foundry IQ 服務適用於任何地區、任何等級,包括免費層級。
  • 擁有者、使用者存取管理員,或具有 Microsoft.Authorization/roleAssignments/write 權限的自訂角色,以啟用 RBAC。
  • 啟用 RBAC 後,您需要資料平面角色來存取內容: 搜尋服務貢獻者、 搜尋索引資料貢獻者,以及 搜尋索引資料閱讀器。 詳情請參見 「指派角色 」。

啟用資料平面作業的角色型存取

將您的 Foundry IQ 服務設定為在提供 OAuth2 存取權杖的資料請求時識別 授權標頭 。

當您啟用資料平面的角色時,變更會立即生效,但請稍候幾秒鐘,然後再指派角色。

未經授權要求的預設失敗模式為 http401WithBearerChallenge。 或者,您可以將失敗模式設定為 http403。

  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 選擇 設定 ,然後在左側窗格選擇 按鍵 。

    金鑰頁面的螢幕截圖,包含驗證選項。

  3. 選擇 [角色型控件]。 只有在您目前使用密鑰且需要時間將用戶端轉換為角色型訪問控制時,才選擇 [兩者 ]。

    選項 描述
    API 金鑰 (預設值) 需要要求標頭上的 API 金鑰,才能進行授權。
    角色型存取控制(建議 ) 需要具備角色指派成員資格,才能完成此工作。 這個要求還需要授權標頭。
    兩者 使用 API 金鑰或角色型存取控制,要求是有效的,但如果您在相同的要求中提供這兩者,則會使用 API 金鑰。
  4. 身為系統管理員,如果您選擇僅使用角色的方法,請將資料平面角色指派給您的使用者帳戶,以在 Azure 入口網站中恢復完整的資料平面操作系統管理權限。 角色包括搜尋服務參與者、搜尋索引資料參與者和搜尋索引資料讀者。 如果您想要對等的存取權,則需要前兩個角色。

    有時可能需要五到十分鐘的時間,角色指派才會生效。 在發生這種情況之前,下列訊息會出現在用於數據平面作業的 Azure 入口網站 頁面中。

    顯示權限不足的入口網站訊息截圖。

停用角色型存取控制

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

若要停用 Azure 入口網站 中的角色型訪問控制:

  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 選擇 設定 ,然後在左側窗格選擇 按鍵 。

  3. 選取 [API 金鑰]。

停用 API 金鑰驗證

如果您只使用內建的角色與 Microsoft Entra 驗證,則可在服務中停用金鑰存取或本機驗證。 停用 API 金鑰會讓 Foundry IQ 服務拒絕所有在標頭中傳遞 API 金鑰的資料相關請求。

管理員 API 金鑰可以停用,但無法刪除。 可以刪除查詢 API 金鑰。

需要擁有者或參與者權限才能停用安全性功能。

  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 在左導覽窗格中,選取 [金鑰]。

  3. 選取角色型存取控制。

變更會立即生效,但在測試之前請稍候幾秒鐘。 假設您有權將角色指派為擁有者、服務管理員或共同管理員的成員,您可以使用入口網站功能來測試角色型存取。

下一步