使用角色連接 Foundry IQ(Azure AI 搜尋服務)

附註

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

Foundry IQ(Azure AI 搜尋服務)支援透過 Microsoft Entra ID 進行角色導向存取控制。 基於角色的存取是可選的,但建議使用。 替代方法是金鑰型驗證,這是預設值。

如果你為一個安全主體指派多個角色,權限會合併。 角色分配適用於所有工具和客戶庫。

本文說明如何指派服務管理、開發,以及唯讀查詢與檢索存取的內建角色。 它也提供建立自訂角色及測試角色指派的步驟。

小提示

應用程式服務主體或受控識別可以在具備適當角色指派的情況下,以 Search 呼叫者身分進行驗證。 此呼叫者授權與用於原生文件權限篩選的委派使用者身份是分開的。 請參閱 查詢時令牌角色與權限流程。

先決條件

內建角色

角色是一組影響控制平面或資料平面的權限:

  • 控制平面: 服務佈建、設定與管理的操作。 控制平面操作包括建立或刪除 Foundry IQ 服務、列出 API 金鑰,以及管理網路與驗證設定。 可透過 Azure Resource Manager REST API、Search Management REST API 及等效的 Azure SDK 用戶端函式庫取得。

  • 資料平面: 針對 Foundry IQ 服務端點的操作。 資料平面操作分為兩大類:物件管理與內容存取。 可透過 Search Service REST API 及等效的 Azure SDK 用戶端函式庫取得。

角色描述

下列內建角色授予 Foundry IQ 權限。 控制平面角色隨時可用,而資料平面角色則需要在您的 Foundry IQ 服務上啟用角色型存取控制。 你可以結合內建角色以擴大存取範圍,或建立一個擁有特定權限的 自訂角色 。

角色 平面 描述
Owner 管理
  • 完整的控制平面存取權,包括指派角色及更改認證設定的能力。
  • 訂閱管理員預設擁有此角色。
  • 可以管理 API 金鑰。
  • 無法建立搜尋物件、載入文件、查詢索引,或從知識庫擷取資料。
Contributor 管理
  • 控制平面存取權限與擁有者相同,但無法分配角色。
Reader 管理
  • 唯讀控制平面存取。
  • 可以查看服務指標和物件定義。
  • 無法查看或管理 API 金鑰、載入文件、查詢索引,或從知識庫檢索。
搜尋服務貢獻者 控制與資料
  • 完整的控制平面存取權。 資料平面存取僅限於物件管理。
  • 能建立索引、索引器、技能集、知識庫及其他搜尋物件。
  • 可透過控制平面操作取得管理員及查詢 API 金鑰。
  • 無法透過角色導向存取直接載入文件、查詢索引或從知識庫檢索。
  • 完整權限清單請參見 Microsoft.Search/searchServices/*。
搜尋索引資料貢獻者 資料
  • 讀寫內容存取權。
  • 能載入文件、查詢索引,並從知識庫檢索。
  • 無法修改物件定義或取得管理員金鑰。
搜尋索引資料讀取器 資料
  • 唯讀內容存取。
  • 可以查詢索引並從知識庫檢索。
  • 無法載入文件、修改物件定義或取得管理金鑰。

重要事項

  • 擁有者、貢獻者與搜尋服務貢獻者可取得管理員金鑰,提供資料平面的完整讀寫權限。 這些角色只授予受信任的使用者。
  • 預設情況下,資料平面角色會套用於 Foundry IQ 服務上的所有索引。 若要將搜尋索引資料貢獻者或搜尋索引資料讀取器範圍至單一索引,請參見 授權存取單一索引。

權限摘要

請使用以下表格快速找出哪個角色提供所需的權限。

權限 擁有者/參與者 讀取者 搜尋服務參與者 搜尋索引資料參與者 搜尋索引資料讀取者
建立並設定 Foundry IQ 服務 ✅ ❌ ✅ ❌ ❌
在 Azure 入口網站中存取服務 ✅ ✅ ✅ ❌ ❌
檢視服務屬性、指標與端點 ✅ ✅ ✅ ❌ ❌
列出服務中的所有物件 ✅ ✅ ✅ ❌ ❌
存取配額和服務統計資料 ✅ ❌ ✅ ❌ ❌
檢視、複製及重新產生金鑰 ✅ ❌ ✅ ❌ ❌
設定驗證選項 ✅ ❌ ✅ ❌ ❌
查看角色、政策與定義 ✅ ✅ ✅ ❌ ❌
配置網路安全與私人連線 ✅ ❌ ✅ ❌ ❌
建立、執行及管理搜尋物件 1 ❌ ❌ ✅ ❌ ❌
上傳索引資料 2 ❌ ❌ ❌ ✅ ❌
查詢索引 ❌ ❌ ❌ ✅ ✅
從知識庫檢索 ❌ ❌ ❌ ✅ ✅
使用提高權限讀取略過權限篩選 ❌ ❌ ❌ ✅ ❌

1 包含索引、索引器、資料來源、技能集、別名、同義詞映射、除錯工作階段、知識庫與知識來源。 索引器也支援執行與重置操作。

2 擁有者或貢獻者可以執行 匯入資料 精靈 來建立並載入索引,儘管他們無法在其他用戶端上傳文件。 同樣地,索引器可以寫入 Foundry IQ 服務上的任何索引,不論 每個索引的角色指派為何。 在這兩種情況下,Foundry IQ 服務(而非使用者)會依其 Microsoft.Search/searchServices/indexes/documents/* 權限執行資料平面操作。

指派內建角色

在本節中,你指派以下角色:

指派服務管理的角色

以下角色可讓您建立、設定及管理 Foundry IQ 服務。 這些角色是階層式的,請根據你需要的存取權限選擇一個。

角色 ID
Owner 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Contributor b24988ac-6180-42a0-ab88-20f7382dd24c
Reader acdd72a7-3385-48ef-bd42-f606fba81ae7
  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 從左側窗格選擇 Access control (IAM)。

  3. 選擇 [] + [新增>] 新增角色指派 []。

    用於指派服務管理角色的存取控制(IAM)頁面螢幕截圖。

  4. 選擇角色: 擁有者、 貢獻者或 讀者。

  5. 在 Members 標籤中,選擇Microsoft Entra使用者或群組身份。 如果你正在為其他 Azure 服務設定權限,請選擇系統指派或使用者指派的管理身份。

  6. 在 [檢閱 + 指派] 索引標籤上,選取 [檢閱 + 指派] 以指派角色。

指派用於開發的角色

以下角色讓你能建立搜尋物件、載入文件、查詢索引,以及從知識庫檢索。 將所有三個角色分配,以涵蓋完整的開發任務範圍。

角色 ID
搜尋服務貢獻者 7ca78c08-252a-4471-8644-bb5ff32d4ba0
搜尋索引資料貢獻者 8ebe5a00-799e-43f5-93ac-243d3dce84a7
搜尋索引資料讀取器 1407120a-92aa-4202-b7e9-c0e197c71c8f
  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 從左側窗格選擇 Access control (IAM)。

  3. 選擇 [] + [新增>] 新增角色指派 []。

    用於指派開發角色的存取控制(IAM)頁面螢幕截圖。

  4. 選擇 搜尋服務貢獻者。

  5. 在 Members 標籤中,選擇Microsoft Entra使用者或群組身份。 如果你正在為其他 Azure 服務設定權限,請選擇系統指派或使用者指派的管理身份。

  6. 在 [檢閱 + 指派] 索引標籤上,選取 [檢閱 + 指派] 以指派角色。

  7. 重複這些步驟以指派 搜尋索引資料貢獻 者與 搜尋索引資料閱讀器。

指派唯讀存取的角色

請使用以下角色來處理只需要讀取索引和知識庫的應用程式和流程。 支援的操作包括 搜尋、 查找、 自動補全,以及 索引建議 ,以及知識庫的 檢索 。

角色 ID
搜尋索引資料讀取器 1407120a-92aa-4202-b7e9-c0e197c71c8f
  1. 前往 Azure 入口網站中的 Foundry IQ 服務。

  2. 從左側窗格選擇 Access control (IAM)。

  3. 選擇 [] + [新增>] 新增角色指派 []。

    用於指派唯讀資料存取角色的存取控制(IAM)頁面螢幕截圖。

  4. 選擇 搜尋索引資料閱讀器 角色。

  5. 在 Members 標籤中,選擇Microsoft Entra使用者或群組身份。 如果你正在為其他 Azure 服務設定權限,請選擇系統指派或使用者指派的管理身份。

  6. 在 [檢閱 + 指派] 索引標籤上,選取 [檢閱 + 指派] 以指派角色。

測試角色指派

使用用戶端來測試角色指派。 記住角色是累積的。 您無法刪除或拒絕在資源(Foundry IQ 服務)層級下,範圍為訂閱或資源群組層級的繼承角色。

在進行之前,先 設定應用程式為無鑰匙連接 ,並設定好角色分配。

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

  2. 從左側窗格選擇 搜尋管理>索引 以測試與索引相關的權限:

    • 搜尋服務貢獻者可以建立、修改和刪除搜尋物件,但無法載入文件或執行查詢。 若要驗證權限,請建立搜尋索引。

    • 搜尋索引資料參與者可以載入文件。 Azure入口網站中除了Import datawizard外,沒有載入文件的選項,但你可以重置並執行索引器來確認文件載入權限。

    • 搜尋索引資料閱讀器可以查詢索引。 若要驗證權限,請使用搜尋總管。 你應該能發送查詢並查看結果,但不應該能查看索引定義或建立索引。

授與單一索引的存取權

在某些情況下,您可能想要限制應用程式對單一資源 (例如索引) 的存取權。

目前,Azure 入口網站不支援索引層級的角色指派。 使用 Azure CLI、PowerShell 或 REST API 來指派範圍限定於單一索引的角色。

每個索引的範圍和索引器的操作

依索引分配的角色指派僅適用於直接的 API 操作,例如使用者或應用程式的查詢或文件上傳。 索引器不受單一索引的權限限制,因為它們使用服務層級的憑證進行操作。

具有 搜尋服務貢獻者 角色的使用者可以建立索引器,寫入 Foundry IQ 服務上的任何索引,即使是該使用者沒有每個索引角色指派的索引。

對可變更資料來源、索引器、映射、技能組或投影的文件撰寫者與管理員套用最小權限。 索引層級的寫入存取並不會建立每份文件的擁有權:鍵值選擇要寫入的記錄,而不是該寫入者是否擁有其內容或是否授權。 關於 Blob 的擷取,請依照 「檢視您的擷取設定」。

當服務層級索引器、共用憑證或管理員可以跨過這些索引寫入時,獨立索引並不算完全隔離。 在分離具有不同信任需求的資料集時,檢視這些共用權限以及直接索引存取。

為了嚴格確保索引間的資料隔離,請考慮以下技術方法:

  • 為需要索引層級隔離的團隊或使用者使用獨立的 Foundry IQ 服務。
  • 僅將 搜尋服務協作者 指派給管理索引器的管理員。
  • 使用文件 層級的存取控制 搭配安全過濾器,限制共享索引內的查詢結果。

建立自訂角色

如果內建角色無法提供正確的權限組合,你可以建立 自訂角色 來支援所需的操作。

以下範例是複製 Search Index Data Reader ,並新增依名稱列出索引的功能。 通常,在 Foundry IQ 服務上列出索引被視為一項行政權利。

  1. 登入 Azure 入口網站,並前往您的 Foundry IQ 服務。

  2. 從左側窗格選擇 Access control (IAM)。

  3. 在角色索引標籤上,找到 Search Index Data Reader 或其他角色,選取省略符號 (...),然後選取複製。

  4. 在 Basics 標籤中,輸入自訂角色名稱,例如「Search Index Data Explorer」,然後選擇 Next。

  5. 在 [許可權] 索引標籤上,選取 [新增許可權]。

  6. 在 Add 權限面板中,選擇 Microsoft 搜尋 圖塊。

  7. 在頂部選擇 「行動 」後,請設定以下權限:

    • 在 Microsoft.Search/operations 下,選擇 Read: 列出所有可用的操作。
    • 在Microsoft.Search/searchServices/indexes下,選擇Read : Read Index。
  8. 切換到頂部的 Data Actions,在 Microsoft.Search/searchServices/indexes/documents 下,選擇 Read : Read Documents。

    JSON 定義看起來像下列範例:

    {
        "properties": {
            "roleName": "Search Index Data Explorer",
            "description": "List all indexes on the service and query them.",
            "assignableScopes": [
                "/subscriptions/<subscription>/resourceGroups/<resource-group>"
            ],
            "permissions": [
                {
                    "actions": [
                        "Microsoft.Search/operations/read",
                        "Microsoft.Search/searchServices/indexes/read"
                    ],
                    "notActions": [],
                    "dataActions": [
                        "Microsoft.Search/searchServices/indexes/documents/read"
                    ],
                    "notDataActions": []
                }
            ]
        }
    }
    
  9. 選擇 新增 以關閉窗格。

  10. 選取 [檢閱 + 建立] 以建立角色。

    您現在可以將使用者和群組指派給角色。 如需瞭解這些步驟的詳細資訊,請參閱 使用 Azure 入口網站建立或更新自訂角色。

建立條件式存取原則

如果你需要執行組織政策,例如多重驗證,請使用 Microsoft Entra 條件式存取。

為 Foundry IQ 建立條件存取政策的方法:

  1. 登入 Azure 入口網站。

  2. 搜尋Microsoft Entra 條件式存取。

  3. 在 「概覽 」頁面,選擇 建立新政策。

  4. 在雲端 應用程式或動作下,依照您想要設定政策的方式,將 Foundry IQ 新增為雲端應用程式。

  5. 更新保單剩餘的參數。 例如,指定該政策適用於哪些使用者和群組。

  6. 儲存原則。

重要事項

如果您的 Foundry IQ 服務已指派管理身份,該特定 Foundry IQ 服務會以雲端應用程式的形式出現。 然而,選擇該特定 Foundry IQ 服務並不會強制執行該政策。 請選擇一般的 Foundry IQ 雲端應用程式,將您的條件存取政策套用到您的 Foundry IQ 服務上。

Troubleshooting

當你開發使用基於角色的存取控制來進行驗證的應用程式時,可能會遇到一些常見問題:

  • Foundry IQ 服務的預設設定是 基於金鑰的驗證。 如果你不將此設定改為 「兩者 」或 「基於角色的存取控制」,所有使用基於角色驗證的請求都會自動被拒絕,不論底層權限為何。

  • 如果你的請求包含 API 金鑰與基於角色的憑證,服務會使用該金鑰進行認證。 從請求標頭移除 API 金鑰,以使用基於角色的認證。

  • 如果授權憑證來自 受管理身份 ,且你最近才分配了適當的權限, 權限分配可能需要好幾個小時 才能生效。

  • 如果帶有文件層級權限的查詢無法回傳預期結果,可以使用搜尋索引資料貢獻者,或建立一個權限提升的自訂角色來調查。

下一個步驟

本文說明如何在 Foundry IQ 上為控制平面及資料平面操作指派角色。 新增角色基礎存取權至你的應用程式碼的完整說明如下: