Azure AI 搜尋服務 中查詢時 ACL 和 RBAC 的強制執行（預覽版）

查詢時存取控制（預覽）確保使用者僅根據其身份、群組成員、角色或屬性，取得被授權存取的搜尋結果。 此功能對於安全的企業搜尋與合規導向工作流程至關重要。

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

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

先決條件

• 權限的元資料必須在 filterable 字串欄位中。 你不會在查詢中使用過濾器，但搜尋引擎會在內部建立過濾器以排除未經授權的內容。

• 權限中繼資料必須包含 POSIX 樣式權限，用以識別存取層級以及群組或使用者 ID；如果您使用 RBAC 範圍，則必須包含 ADLS Gen2 中容器的資源 ID。

• 如果是使用自訂擷取的 ACL 型強制執行，則將 userIds 和 groupIds，以可篩選欄位方式做為 Microsoft Entra 物件識別碼 (GUID)。 在查詢時，服務會將 的 x-ms-query-source-authorization 身份與儲存的 ID 進行比對。 關於結構細節，請參閱使用推送 REST API 索引文件存取控制清單（ACL）（預覽版）。

• 視資料來源而定：

  • 對於 ADLS Gen2 資料來源，你必須在容器層級設定存取控制清單（ACL）和/或 Azure 角色基礎存取控制（RBAC）角色。
  • 對於 Azure Blob 的資料來源，你必須在容器上設定角色指派。 你可以使用 內建的索引器、 知識來源或 推送 API ，來索引索引中的權限元資料。
  • 對於 SharePoint 資料來源，您必須設定存取控制清單（ACL）。 你可以使用 內建的 SharePoint 索引器並設定為 ACL 擷取功能。 你也可以使用索引的 SharePoint 知識來源，並設定它來強制執行文件層級的權限。 以群組為基礎的權限，包括 Microsoft 365 群組，可在擷取為 Entra 物件 ID 時提供支援。 群組展開會在查詢時透過 Microsoft Graph 進行。

• 使用 latest preview REST API 或Azure SDK的預覽套件來查詢索引或知識來源。 此 API 版本支援內部查詢以過濾未授權結果。

限制

• 若 ACL 評估失敗（例如 圖形 API 無法使用），服務會回傳 5xx，不會回傳部分篩選的結果集。

• ACL 的新鮮度依擷取方式而定。 為避免授權決策陳舊，請規劃每個來源如何向索引傳遞權限變更：

  • 排程的 SharePoint 索引器會在每次執行時刷新項目層級權限變更。 若子項目繼承了父範圍（網站、函式庫、清單或資料夾）的變更，則需重新同步。
  • ADLS Gen2 索引器需要重新同步以刷新 ACL。
  • 自訂或推送擷取需要您重新擷取受影響的文件。

• 文件可見性需要以下兩項條件：

  • 呼叫應用程式的 RBAC 角色 (授權標頭)。
  • 由 x-ms-query-source-authorization 傳遞的使用者身分。

• 首次執行 ACL 型查詢時，與後續請求相比，延遲可能較高，因為快取和權限解析會帶來額外負擔。

• 對於索引的 SharePoint 內容，嵌套在 SharePoint 群組 中的 Microsoft Entra 群組不會被擴充。 Microsoft Entra 的傳遞式群組解析不支援這種混合關係。 參見 支持性團體關係。

各資料來源的 ACL 輸入限制

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

Azure AI 搜尋服務 功能支援的最大 ACL 條目數量會依資料來源類型而異：

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

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

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

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

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

1. 使用者權限輸入

終端使用者應用程式在搜尋查詢請求中包含查詢存取權杖，而該存取權杖通常是使用者的身份。 下表列出 Azure AI 搜尋服務 支援 ACL 強制執行的使用者權限來源：

2. 安全過濾器的構造

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

對於 Azure RBAC，權限是資源 ID 字串的清單。 資料來源上必須有 Azure 角色指派 (Storage Blob Data Reader)，以授與授權標頭中的安全性主體權杖存取權。 如果要求中的存取權杖背後主體沒有角色指派，篩選器會排除文件。

3. 結果篩選

安全過濾器會有效地將請求中的 userID、groupID 和 rbacScope 與搜尋索引中每個文件中的 ACL 清單比對，限制回傳的結果僅限於使用者可存取的。 重要的是要注意，每個過濾器都是獨立套用的，若有過濾器成功，文件即視為授權。 例如，如果使用者透過 userID 存取文件，但無法透過 groupID，該文件仍被視為有效並返回給使用者。

查詢時的 SharePoint 群組

自 2026-05-01-preview REST API 起，Azure AI 搜尋服務 可在查詢時承認 SharePoint 站點群組成員資格，如擁有者、成員、訪客及自訂站點群組。 為了實現此情境，指數必須包含：

• 一個sharePointConnectorAppRegistration屬性，參考用於代表使用者呼叫SharePoint的Microsoft Entra應用程式的聯邦身份憑證。
• 一個標有 sharepointSiteUrl: true 屬性的欄位，儲存每個索引項目的SharePoint網站網址（通常命名為 SharePointSiteUrl，並由 metadata_spo_site_url 來源欄位填充）。

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

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

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

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

此請求與標準 ACL 強制查詢相同。 搜尋服務會使用索引的 sharePointConnectorAppRegistration 來代表呼叫者解析 SharePoint 群組成員資格。 在 GroupIds 子句中加入 select，即可在回應中看到以 spg: 為前綴的值。

POST {{endpoint}}/indexes/{index}/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

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

查詢範例

這裡有一個來自 sample code 的查詢請求範例。 查詢權杖是 Microsoft Entra 給查詢使用者的存取權杖。

POST  {{endpoint}}/indexes/stateparks/docs/search?api-version=2026-08-01-preview
Authorization: Bearer {{query-token}}
x-ms-query-source-authorization: {{query-token}}
Content-Type: application/json

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

調查錯誤結果的權限提升（預覽）

偵錯包含權限元資料的查詢可能會有問題，因為搜尋結果針對每個使用者都是特定的。 作為開發者或管理員，你可能需要提升權限來回傳結果，無論權限元資料為何，這樣你才能調查查詢回傳未授權內容的問題。

要調查，你必須能夠：

• 查看最終使用者根據該使用者權限所能瀏覽的文件集合。

• 查看索引中的所有文件，以調查為何有些文件可能對最終使用者看不到。

你可以透過在查詢中加入自訂標頭 x-ms-enable-elevated-read: true來完成這些任務。

提高讀取請求的權限

您必須擁有 搜尋索引資料貢獻者 權限，或包含提升讀取權限的 自訂角色 。

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

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

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

POST {endpoint}/indexes('{indexName}')/search.post.search?api-version=2026-08-01-preview
Authorization: Bearer {AUTH_TOKEN}
x-ms-query-source-authorization: {TOKEN}
x-ms-enable-elevated-read: true

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

特定預覽 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 標頭。

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

相關內容

• 教學：索引來自 ADLS Gen2 的權限中繼資料，並查詢依權限篩選的結果（預覽）
• 使用推送 REST API 索引文件存取控制清單（ACL）（預覽版）
• 使用 ADLS Gen2 索引器來擷取權限元資料，並根據使用者存取權限篩選搜尋結果（預覽）
• 使用 blob 索引器或資料來源來匯入 RBAC 範圍的元資料
• 使用 SharePoint 索引器來擷取權限的元資料，並根據使用者存取權篩選搜尋結果（預覽）