Foundry IQ(Azure AI 搜尋服務)中的查詢時 ACL 與 RBAC 強制執行

註

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

重要

本文中標示為(預覽)的功能或特性目前處於公開預覽狀態,並受 Microsoft Azure 預覽版補充使用條款的約束。

有關 Foundry IQ(Azure AI 搜尋服務)專屬的預覽條款,請參閱預覽功能。

SharePoint ACL 權限篩選、ADLS Gen2 ACL/RBAC 篩選、標準 Blob 容器 RBAC 篩選及提升讀取功能一般可透過 2026-10-01 資料平面 REST API 提供。

查詢時存取控制會利用被委派使用者的身分以及索引所支援的權限元資料來篩選搜尋結果。 推送 ACL 匯入功能普遍可用。 Microsoft Purview 敏感度標籤強制執行仍處於預覽階段。

授權存取取決於索引過程中所擷取的權限元資料。 對於內建存取模式的索引器資料來源,例如 Azure Data Lake Storage(ADLS)Gen2 和 Microsoft 365 中的 SharePoint,索引器可以自動拉取每份文件的權限元資料。 對於其他資料來源,你必須自己組合文件載荷,且載荷必須包含內容及相關的權限元資料。 接著你用 推送 API 載入索引。

本文說明如何設定使用權限元資料來篩選結果的查詢。

OneLake 來源權限會重用 x-ms-query-source-authorization 呼叫者權杖流程。 關於其來源位置中繼資料需求和授權模型,請參閱 保留 OneLake 權限,而非下文所述的複寫 ACL/RBAC 模型。

先決條件

  • 在索引上啟用 permissionFilterOption ,並使用頂層可篩選的權限欄位。 您不會在查詢中加入權限篩選器;搜尋引擎會自行建立它。

  • 請使用適合您來源的權限元資料:SharePoint 的使用者與群組 ID、ADLS Gen2 的 POSIX 風格 ACL,或 ADLS Gen2 或標準 Blob 儲存體 RBAC 範圍的容器資源 ID。

  • 針對以 ACL 為基礎的強制執行並進行自訂擷取時,請將 userIds 和 groupIds 儲存為 Microsoft Entra 物件 ID(GUID),而非電子郵件地址或 UPN。 在查詢時,Foundry IQ(Azure AI 搜尋服務)會使用委派的使用者令牌x-ms-query-source-authorization來評估文件權限。 有關欄位類型與結構細節,請參閱 「使用 push REST API 索引文件 ACL」。

  • 視資料來源而定:

    • 對於 ADLS Gen2 資料來源,你必須在容器層級設定存取控制清單(ACL)和/或 Azure 角色基礎存取控制(RBAC)角色。
    • 對於 Azure Blob 資料來源,您必須具備受支援的容器存取權限。 您可以使用 Blob 索引器、知識來源或 推送 API,來為您索引中的權限元資料建立索引。
    • 對於 SharePoint 資料來源,您必須設定存取控制清單(ACL)。 你可以使用 內建的 SharePoint 索引器並設定為 ACL 擷取功能。 你也可以使用索引的 SharePoint 知識來源,並設定它來強制執行文件層級的權限。 以群組為基礎的權限,包括 Microsoft 365 群組,可在擷取為 Entra 物件 ID 時提供支援。 群組展開會在查詢時透過 Microsoft Graph 進行。
  • 使用 REST API 2026-10-01 來處理 SharePoint 及 ADLS/Blob 權限篩選查詢,或在套件變更記錄中確認是否具備等效的 SDK 支援。 對於獨立預覽情境,請使用其文件化的 API 版本。

限制

  • 未解決的群組成員資格不會授予存取權限。 對於 SharePoint,當群組查詢失敗時,獨立解析的授權仍可套用。 如果請求回傳授權錯誤,請不要以未篩選或提升權限重試。

  • 對於複製的 ACL 和 RBAC 元資料,新鮮度取決於每種擷取方式如何將權限變更傳遞到索引:

    • SharePoint 索引器會在成功增量處理期間重新整理偵測到的項目層級變更及支援的非根資料夾權限變更。 設定 一個短週期的權限更新排程。 這個間隔並不是完成期限或撤銷SLA。 連結的指引也涵蓋其他範圍及明確的刷新選項。
    • 一個 ADLS Gen2 索引器 預設大約每天會在符合條件的正常執行期間重新整理 ACL,或透過明確的權限重新同步來重新整理 ACL。
    • Blob 與 ADLS RBAC 範圍檢查會在查詢時評估被委派使用者的容器授權。 角色指派傳播和授權快取與已編製索引的 ACL 時效性彼此獨立。
    • 自訂或推送擷取需要您重新擷取受影響的文件。
  • 有關 OneLake 來源位置中繼資料及查詢時存取資訊,請參閱 權限與路徑時效性。

  • 沒有 提高權限的讀取 的查詢需要同時滿足以下兩項條件:

    • 呼叫者的搜尋 RBAC 授權(Authorization 標頭)。
    • 由 x-ms-query-source-authorization 攜帶、用於存取受權限保護內容的委派使用者身分。
  • 首次執行 ACL 型查詢時,與後續請求相比,延遲可能較高,因為快取和權限解析會帶來額外負擔。

  • 對於索引化的 SharePoint 內容,嵌套於 SharePoint 群組中的 Microsoft Entra 群組在五個層級內受到支援,但須遵守獨立的站台層級主體限制。 參見 支持性團體關係。

各資料來源的 ACL 輸入限制

存取控制清單(ACL)條目限制定義了在連接的資料來源中,一個檔案、資料夾或項目可關聯多少個不同的權限紀錄。 每個項目代表單一使用者或群組身份及其所獲得的存取權限(例如讀取、寫入或執行)。

Foundry IQ 功能支援的最大 ACL 項目數會依資料來源類型而異:

Azure Data Lake Storage Gen2(ADLS Gen2):每個檔案或目錄最多可有32個 ACL 條目權限。 在此語境中,條目指的是擁有特定權限集的單一主體(使用者或群組)。 舉例來說:將「Everyone」讀取權限和「Azure 使用者」執行權限分配,會算作兩個 ACL 條目。

Microsoft 365 中的 SharePoint:搜尋中的 SharePoint 資料來源支援每個檔案最多 1,000 個權限條目。 每個項目代表該項目權限列表中獨特的使用者或群組指派。 這與每個列表或函式庫整體 的唯一權限範圍限制 不同,後者決定了有多少項目可以擁有唯一權限。

這些限制決定了 Foundry IQ 在索引或篩選搜尋結果時,能多細緻地尊重項目層級權限。 若項目超過這些 ACL 條目限制,超出限制的權限可能在查詢時不會被強制執行。

查詢時強制執行的運作方式

本節列出查詢時 ACL 強制執行的操作順序。 操作會依你使用 Azure RBAC 範圍或 Microsoft Entra ID 群組或使用者 ID 而有所不同。

1. 使用者權限輸入

對於原生權限過濾查詢,這兩個權杖位置具有不同的角色:

  • Authorization 透過 Search RBAC 驗證呼叫者並授權搜尋資料平面操作。 呼叫者可以是使用者、應用程式服務主體,或具有所需搜尋角色與資源範圍的受管理身份。
  • x-ms-query-source-authorization 攜帶委派使用者存取權杖。 Foundry IQ 評估的是該使用者的文件存取權限,而不是 Authorization 中應用程式的文件存取權限。

被授權呼叫搜尋的應用程式或受管理身份不會自動成為受支援的文件權限主體。 索引器用來讀取來源的身份,也與查詢呼叫者及被評估權限的使用者分開。

下表說明了受支援的委派使用者流程。 每個流程保留其來源專屬權限與 API 限制。

許可流程 支援的委派使用者行為
userIds ACL 將來自 x-ms-query-source-authorization 的被委派使用者 Microsoft Entra 物件 ID(oid)與已建立索引的使用者 ACL 進行比對。
groupIds ACL 清單 透過 Microsoft Graph 解析使用者在 Microsoft Entra 中的群組成員資格,包括受支援的安全性群組和 Microsoft 365 群組,並將這些群組的物件 ID 與已建立索引的群組 ACL 進行比對。
SharePoint 網站群組 透過索引上已註冊的應用程式,解析受委派使用者的網站群組成員資格。 匹配 groupIds 中帶有 spg: 前綴的 ID。 需要 SharePoint 群組配置。 使用 REST API 2026-10-01 進行 SharePoint 權限篩選。
rbacScope 評估委派使用者在已建立索引的 ADLS Gen2 或標準 Blob 容器範圍內所支援的 Blob-read 授權。
Purview 敏感度標籤(預覽) 評估被委派使用者在 獨立 Purview 要求下的標籤權限。

Microsoft Entra 群組擴充會在使用者代表使用者 (OBO) 流程中使用查詢來源使用者令牌。 群組並不是帶有權杖的身分。 Authorization 中的應用程式權杖並不會取代此群組解析流程所需的委派使用者聲明。 有關支援的群組關係,請參閱來源專屬限制。

應用程式權杖邊界

選擇操作與權限模型的權杖流程,而非僅為應用程式驗證搜尋的能力。

Flow 應用程式權杖邊界
搜尋呼叫者驗證 應用程式服務主體或系統指派或使用者指派的受控識別可以使用所需的搜尋角色來驗證呼叫者。 這並不代表它是文件權限主體。
userIds、groupIds 以及 SharePoint 網站群組 請使用上述委派查詢來源使用者流程。 在 token 或 ACL 中的應用程式物件 ID 並不會建立支援的僅應用程式查詢來源流程。 群組擴展仍需其有文件的使用者聲明與同意。
全組織權限值 廣泛適用的授權不會改變權杖規約。 不要僅因為內容具有全組織授權而省略必要的使用者令牌,或以應用程式令牌替代它。
容器 rbacScope 使用支援的委派使用者流程。 為索引器或應用程式指派儲存角色並不等同於查詢使用者的授權。
OneLake 來源權限 依照來源專屬的預覽合約,傳遞請求使用者的權杖。 搜尋對 OneLake 進行認證的管理身份與該使用者是分開的。
Purview 標籤 請遵守各自的委派使用者要求,包括在啟用 Purview 的索引上提升讀取權限的委派使用者要求。
無需 Purview 即可提升的讀取權限 授權應用程式可使用僅應用程式的呼叫者驗證來執行 直接索引的管理操作。 這可繞過文件權限篩選;它不評估應用程式的 ACL 成員資格。
應用程式管理的 安全字串篩選器 應用程式會自行驗證其使用者,並自行建立可信任的篩選條件。 這不是原生的應用程式權杖權限評估。

請勿從oidtid聲明、工作負載身份聯盟、代理程式身份或應用程式間 OBO 設定推斷額外的權限主體支援。 請使用文件中針對特定功能所記載的身分取得流程、同意、API 版本和操作。

直接搜尋查詢與取得文件、知識庫檢索,以及 MCP/代理存取有各自獨立的介面契約。 在一個介面上的支援,並不會在另一個介面建立相同的標頭、身分類型或管理員繞過。 對於知識庫與 MCP 存取,請依 照查詢時檢索授權;引用並不提供獨立的授權路徑。

如果請求拒絕所提供的權杖或行為主體,請安全地讓該應用程式的請求失敗。 不要透過省略使用者權杖、切換主體、回傳未過濾或僅限公開的結果,或啟用提升的讀取權限來重試。

2. 安全過濾器的構造

在內部,Foundry IQ 會根據使用者所提供的權限動態建構安全篩選器。 如果索引啟用權限篩選選項,這些安全過濾器會自動附加到查詢時可能出現的任何過濾器。

對於 Azure RBAC,索引儲存容器資源 ID,而非複製的角色指派。 Foundry IQ 會評估 x-ms-query-source-authorization 中的委派使用者在這些範圍內是否具有受支援的 Blob 讀取授權。 此使用者不一定是 Authorization 中可獨立授權存取搜尋資料平面的應用程式主體。 授權解析使用快取;重新編製索引不會強制重新整理這些快取。

3. 結果篩選

ACL/RBAC 安全性篩選器會將使用者權限與已建立索引的 userIds、groupIds 和 rbacScope 欄位進行比對。 這些授權會獨立評估:任何相符的受支援授權都符合此篩選條件。 例如,相符的 userIds 授權不代表也需要相符的 groupIds 授權。 Purview 標籤強制執行 另有不同的要求。

這種 any-grant 行為需要成功進行權限評估。 若在解析群組或其他已設定的權限流程時失敗,即使直接使用者的 ACL 或 RBAC 授權可能相符,請求也可能失敗。

在測試撤銷時,請排除其他受支援的授權方式。 如果容器 RBAC 授權仍授權使用者,移除 ACL 授權也不會拒絕其存取。 如果權限評估失敗,應以安全方式使應用程式要求失敗;不要在沒有委派權杖的情況下重試,也不要啟用提高權限的讀取作為備用。

對於 ADLS Gen2,未支援的隱含 blocklists不會授予任何源自 ACL 的存取權,但獨立支援的 RBAC 授權仍可授權存取。

這些原生權限檢查同樣適用於 moreLikeThis:原始文件必須在相似度檢索執行前可讀,且候選文件會獨立篩選。 如果來源文件無法讀取或遺失,請求會回傳空白的搜尋結果,而非操作授權失敗。 啟用 Purview 的索引會分別拒絕 moreLikeThis。

查詢時的 SharePoint 群組

Foundry IQ 可透過 REST API 2026-10-01在查詢時評估 SharePoint 網站群組權限,例如擁有者、成員、訪客及自訂網站群組。 為了實現此情境,指數必須包含:

  • sharePointConnectorAppRegistration一個屬性,用來指定匯入應用程式的用戶端 ID 以及受管理身份的應用程式 ID,用於聯邦驗證。
  • 一個標有 sharepointSiteUrl: true 屬性的欄位,儲存每個索引項目的SharePoint網站網址(通常命名為 SharePointSiteUrl,並由 metadata_spo_site_url 來源欄位填充)。

在查詢時,Foundry IQ 會使用每個候選文件上的已註冊應用程式及網站 URL,來解析該網站呼叫使用者的 SharePoint 群組 成員資格。 解析後的群組會與儲存在 spg: 權限篩選欄位中、帶有 groupIds 前綴的值進行比對。 spg: 前綴區分SharePoint站點群組與Microsoft Entra群組物件 ID ,後者儲存時沒有前綴。

關於設定細節與限制,請參見 Configure SharePoint groups support。

如果 SharePoint 權限過濾會回傳缺失或意外結果,請參見「故障排除 SharePoint 權限過濾」。

範例:使用 SharePoint 網站群組強制執行進行查詢

此請求與標準 ACL 強制查詢相同。 Foundry IQ 服務會使用索引的 sharePointConnectorAppRegistration,代表呼叫者解析 SharePoint 群組 成員資格。 請以您的端點替換 <INDEX_NAME>、以索引名稱替換 <USER_ACCESS_TOKEN>,並以原始委派使用者令牌替換 <SEARCH_SERVICE_ENDPOINT>。 若要檢查儲存的權限元資料,請依照 ACL 擷取驗證步驟 操作,而非在一般使用者查詢中公開 ACL 欄位。

POST <SEARCH_SERVICE_ENDPOINT>/indexes('<INDEX_NAME>')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: <USER_ACCESS_TOKEN>
Content-Type: application/json

{
    "search": "*",
    "select": "name,description",
    "orderby": "name asc"
}

查詢範例

使用來自推送索引工作流程的2026-10-01索引和四份文件酬載。 等到文件可供搜尋為止。 請用您的端點及<USER_ACCESS_TOKEN>上傳時使用的原始委派使用者令牌<USER_OBJECT_ID>替換<SEARCH_SERVICE_ENDPOINT>。 使用授權查詢索引的呼叫者令牌。

POST <SEARCH_SERVICE_ENDPOINT>/indexes('secured-content-index')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: <USER_ACCESS_TOKEN>
Content-Type: application/json

{
    "search": "*",
    "select": "id,content",
    "top": 4,
    "count": true,
    "orderby": "id asc"
}

參考資料: 搜尋文件。

為調查錯誤結果而提升的權限

提升讀取已普遍可用於 REST API 2026-10-01。 僅用於授權的行政調查,勿作為終端用戶查詢的備用方案。

提升讀取請求會回傳符合條件的文件,不論文件層級的權限篩選條件如何。 設定 x-ms-enable-elevated-read: true 為在調查遺失或非預期結果時檢查已索引內容。

對於未啟用 Purview 的索引,應用程式服務主體可以在 Authorization 中使用僅限應用程式的存取權杖,以取得提升的讀取權限。 將所需的較高讀取權限指派給呼叫者。 這可繞過文件權限篩選;它不會將應用程式視為文件權限主體來評估。

不要在提升讀取要求中包含 x-ms-query-source-authorization。 若要將結果與最終使用者的檢視進行比較,請以該使用者的令牌且不使用提升讀取標頭發出獨立的普通查詢。

對於啟用 Purview 的索引,提升讀取需要在 Authorization 中使用委派使用者權杖;該流程不支援僅限應用程式的權杖。 請參閱 Purview 高階讀取需求。

提高讀取請求的權限

呼叫者 Authorization 必須具備 搜尋索引資料貢獻 者權限,或具有包含「提升讀取」權限的 自訂角色 。

查詢屬於資料平面操作,因此自訂角色只能包含原子資料平面權限。 對於自訂角色,新增 Microsoft.Search/searchServices/indexes/contentSecurity/elevatedOperations/read 權限。

在查詢中加入高階讀取標頭

設定好權限後,你就可以執行查詢。 以下範例是對搜尋索引的查詢請求。

POST {endpoint}/indexes('{indexName}')/docs/search.post.search?api-version=2026-10-01
Authorization: Bearer {AUTH_TOKEN}
x-ms-enable-elevated-read: true
Content-Type: application/json

{
    "search": "prototype tests",
    "select": "filename, author, date",
    "count": true
}

重要

2026-10-01 REST API 支援x-ms-enable-elevated-read搜尋 GET、搜尋 POST 和取得文件動作。 對於知識庫查詢,請直接將請求傳送至底層的搜尋索引。 知識庫擷取 REST API 並未宣告此標頭。 敏感度標籤強制執行仍保留 其獨立的預覽需求。

特定預覽 API 版本中重要的 ACL 功能行為變更

在 REST API 版本 2025-11-01-preview之前,較早的預覽版本 2025-05-01-preview 和 2025-08-01-preview,使用服務 API 金鑰或授權的 Entra 角色時,即使未提供使用者令牌,也會回傳所有文件。 未驗證使用者令牌存在的應用程式,若未正確實作或未遵循最佳實務,可能會無意間暴露結果給最終使用者。

從 2025 年 11 月開始,這種行為有所改變:

  • 即使僅使用服務 API 金鑰或 Entra 認證,所有支援 ACL 的版本都適用 ACL 權限過濾器。
  • 若未包含使用者令牌,ACL 保護的內容將不會回傳。
  • 若要為了疑難排解而檢視所有文件,使用 REST API 版本 2026-05-01-preview 或後續版本時,您必須明確加入 elevated-read 標頭。

此更新有助於在應用程式未強制執行令牌驗證最佳實務時,保持內容的保護。