使用 ADLS Gen2 索引器來匯入權限中繼資料

Note

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

Azure Data Lake Storage (ADLS) Gen2 透過存取控制清單 (ACL) 和角色型存取控制 (Azure RBAC),支援每個使用者對目錄和檔案的存取。 不支援基於屬性的存取控制(Azure ABAC)。

Foundry IQ(Azure AI 搜尋服務)會匯入支援的 ACL 條目與容器 RBAC 範圍,並同時包含文件內容。 擷取與查詢時權限篩選通常可在 REST API 2026-10-01中提供。 此支援子集並未與所有儲存授權政策提供完全同等級的一致性。 這是 Foundry IQ 中文件 層級存取控制 的多種策略之一。

本文說明如何配置 ADLS Gen2 索引器或 ADLS Gen2 blob 知識來源,自動將權限元資料 拉 入搜尋索引。 此內容補充從 ADLS Gen2 編製資料索引和為 ADLS Gen2 建立 Blob 知識來源,並提供權限擷取專屬資訊。 若要手動 推送 權限元資料,請參考 使用 push API 的索引文件 ACL。

架構圖顯示一個經過安全性修剪的 RAG 解決方案,其中 ADLS Gen2 索引器從 ADLS Gen2 容器擷取文件及 ACL 與 RBAC 權限元資料,儲存在 Foundry IQ 索引中,RAG 編排器則過濾查詢結果,使每位使用者只擷取其授權存取的文件。

先決條件

限制

不支援隱式 blocklists

Foundry IQ 不支援隱含的 blocklists:來源 ACL 設定可透過 Other 廣泛授予存取權限,同時排除指定的使用者或群組。 它無法將這些配置呈現為「除了這些身份之外的所有人」。

以下來源 ACL 為 不支援的配置,並非設定建議。 它將 Other 讀取授權與無權限的命名使用者及群組項目結合:

user::rw-
user:22222222-2222-2222-2222-222222222222:---
group::r--
group:bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb:---
mask::r--
other::r--

在此配置中,索引器會在 metadata_user_ids 和 metadata_group_ids 中同時記錄無存取值 none。 沒有任何使用者或群組會透過索引 ACL 獲得存取權限。 這並非全文件的拒絕:獨立且受支援的 RBAC 權限授予仍可授權存取。 這並不代表檔案內容一定未被匯入。

要修復來源原則並更新已索引權限:

  1. 識別預期允許與拒絕的身份、相關群組成員資格、祖先目錄遍歷權限,以及獨立的 RBAC 授權。
  2. 將不支援的隱含 blocklist 設計替換為支援的命名使用者與命名群組 allowlists,供預定要授與存取權限的身分使用。 不要只是刪除限制性命名條目,卻保留一個廣泛的 Other 授權,因為這會擴大原始碼存取範圍。 不要擴大 ACL 遮罩,也不要把 RBAC 授權當作權宜之計。
  3. 請使用具代表性的允許和拒絕身分驗證來源原則。 針對新子項,將現有檔案與目錄與預設 ACL 分開檢視。 變更父項目的預設 ACL 不會更新現有的子孫。
  4. 同步索引權限。 若要進行刻意的完整來源端重新比對,請在索引器閒置時請求權限重新同步,然後執行它或等待排程時間。 監看完成情況。 或者,預設啟用 的自動 ACL 更新 會在符合條件的正常執行中大致每日更新 ACL,而非立即更新或每次排程執行。
  5. 如果現有紀錄缺少所需的來源路徑或區塊對應,請 修正管線並重新處理這些紀錄。 僅重新同步權限無法修復遺失的來源內容脈絡。
  6. 確認允許與拒絕的搜尋結果,包括受影響的區塊。 分別測試僅使用 ACL 且未取得替代授權的使用者,以及獨立獲得 RBAC 授權的使用者。 僅僅成功擷取或重新整理並不證明已修復的政策保留了預期存取權。

索引器在遇到不支援的排除項目時會回報警告。 檢查 執行歷史、警告與錯誤;不要以為每個受影響的檔案都會有一個獨立的警告。 先前已建立索引的權限可能會保留到更新成功,而部分失敗則可能留下混雜的新鮮度。 在成功處理之後,對於此模式沒有任何 ACL 衍生的存取並非有意為之,這並不代表索引已過時。 不要停用權限強制或使用權限讀取作為權宜之計。

對許可模式的支持

本節比較 ADLS Gen2 與 Foundry IQ 之間的文件層級存取控制功能。 它說明了 Foundry IQ 支援或映射哪些 Azure Data Lake Storage(ADLS)第二代存取控制機制。 這有助於你了解文件層級的權限是如何被強制執行的。

ADLS 第二代功能 描述 支援 註釋
RBAC 容器層級的粗粒度存取控管 是的 Foundry IQ 遵循 RBAC,允許存取整個容器中的所有文件。
ABAC RBAC 之上的屬性型條件 不 Foundry IQ 不會評估文件層級存取的 ABAC 條件。
ACL 目錄/檔案(文件)層級的細粒度權限 是的 Foundry IQ 使用文件層級的 ACL 來 權限篩選器。
安全性群組 基於群組的權限指派 是的 若安全群組映射於文件層級的 ACL 內,則支援此系統。

在查詢時,Foundry IQ 會先評估容器層級的 RBAC,然後檢查文件層級的 ACL 條目。 只要有任何機制允許,存取權就會被授予。

流程圖與真實值表,說明 Foundry IQ 如何先檢查容器層級的 RBAC,再檢查 ACL 群組與使用者條目,若任何機制允許則授予存取,只有在所有檢查失敗時才拒絕存取。

關於 ACL 階層式權限

索引器與知識來源可依照 ADLS Gen2 階層式存取評估流程,從指定的容器及所有導向每個檔案的目錄中取得 ACL 指派。 每個檔案的最終有效存取清單會被計算出來,並將不同的存取類別索引到對應的索引欄位中。

例如,在 ADLS Gen2 中,常見的權限情境 是檔案路徑 /Oregon/Portland/Data.txt。

操作 / 俄勒岡州/ 波特蘭/ Data.txt
閱讀 Data.txt --X --X --X R--

索引器或知識來源會從每個容器和目錄收集 ACL。 接著它會判定較低層級的有效存取權限,並持續進行直到解決每個檔案的權限。

/ assigned access vs Oregon/ assigned access
  => Oregon/ effective access vs Portland/ assigned access
    => Portland/ effective access vs Data.txt assigned access
      => Data.txt effective access

設定 ADLS Gen2

索引器或知識來源於符合以下條件時可取得儲存帳戶上的存取控制清單(ACL)。 欲了解更多關於前十字韌帶(ACL)指派的資訊,請參見ADLS Gen2 ACL指派。

授權

若要進行索引,您的 Foundry IQ 服務識別必須具有 Storage Blob Data Reader 權限。

如果你在本地測試,也應該有一個 Storage Blob Data Reader 的角色指派。 欲了解更多資訊,請參閱 使用受控識別連接到 Azure 儲存體。

根容器權限

  1. 在根容器Group中指派所有User與/安全主體,並賦予 Read 和 Execute 權限。

  2. 確保 Read 和 Execute 都被加入為「預設權限」,這樣它們才能自動傳播到新建立的檔案和目錄。

將權限從檔案階層向下傳遞

雖然新的目錄和檔案會繼承權限,但現有的目錄和檔案不會自動繼承這些指派。

使用 ADLS Gen2 工具以遞迴方式套用 ACL,以便在現有內容上傳播指派。 此工具會將根容器的 ACL 指派傳播到所有底層目錄與檔案。

移除多餘權限

在遞迴套用 ACL 後,檢視每個目錄和檔案的權限。

移除任何不應該存取特定目錄或檔案的Group或User集合。 例如,將User2從資料夾Portland/中移除,並從資料夾Idaho的指派中移除Group2和User2,依此類推。

ACL 指派結構範例

以下是 ADLS Gen2 文件中 虛構目錄階層 的 ACL 指派結構示意圖。

ACL 指派結構示意圖。

隨時間更新 ACL 指派

當您新增或修改 ACL 指派時,請將它們套用到指定的目錄和檔案上。 若要在不重新處理未變更內容的情況下更新已索引權限,請依照 「同步索引內容與來源內容之間的權限」。

設定 Foundry IQ

請記得 Foundry IQ 服務必須具備:

授權

為了索引,發出 API 呼叫的用戶端必須擁有 Search Service Contributor 權限來建立物件,Search Index Data Contributor 權限以執行資料匯入,以及 Search Index Data Reader 權限以查詢索引。

如果你是在本地測試,角色分配應該是一樣的。 如需更多資訊,請參閱「使用角色連接至 Foundry IQ」。

設定知識來源

如果你使用知識來源,知識來源中的定義會用來產生完整的索引流程(索引器、資料來源和索引)。 ACL 指派會被偵測並自動包含在產生的索引中。 如果你想在索引內容中取得權限繼承,就不需要修改任何產生的物件。

關於使此設定適合此情境的關鍵點:

  • isADLSGen2 設定為 true,符合此情境的資料來源要求。
  • ingestionPermissionOptions 指定使用者及群組 ID。
# Create / Update Azure Blob Knowledge Source
###
PUT {{url}}/knowledgesources/azure-blob-ks?api-version=2026-10-01
api-key: {{key}}
Content-Type: application/json
 
{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "isADLSGen2": true,
        "ingestionParameters": {
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "{{embedding-deployment}}",
                    "modelName": "{{embedding-model}}",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": true,
            "ingestionSchedule": null,
             "ingestionPermissionOptions": [
                "userIds","groupIds"
                           ],
            "contentExtractionMode": "minimal",
            "aiServices": {
                "uri": "{{ai-endpoint}}",
                "apiKey": "{{ai-key}}"
            }
        }
    }
}
###

配置基於索引器的索引

如果你正在使用索引器,請設定索引器、資料來源和索引,以便從 ADLS Gen2 Blob 抽取權限元資料。

建立資料來源

本節補充 來自 ADLS Gen2 的索引資料,提供專門關於將權限與文件內容匯入 Foundry IQ 索引的相關資訊。

  • 資料來源類型必須是 adlsgen2。

  • 資料來源必須具有 indexerPermissionOptionsuserIds、 groupIds和/或 rbacScope。

帶有系統管理身份的 JSON 範例:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    }
}

JSON 架構範例,連接字串 中包含使用者管理身份:

{
    "name" : "my-adlsgen2-acl-datasource",
    "type": "adlsgen2",
    "indexerPermissionOptions": ["userIds", "groupIds", "rbacScope"],
    "credentials": {
    "connectionString": "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Storage/storageAccounts/<your storage account name>/;"
    },
    "container": {
    "name": "<your container name>",
    "query": "<optional-virtual-directory-name>"
    },
    "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
    }
}

在索引中建立權限欄位

在 Foundry IQ 中,請確保您的索引包含權限元資料的欄位定義。 當在資料來源定義中指定 indexerPermissionOptions 時,權限元資料可以被索引。

包含一個名稱必須完全為 metadata_storage_path、類型為 Edm.String 的欄位。 保留原始來源路徑,不使用映射函數。 此欄位為 ADLS Gen2 權限擷取(包括僅 RBAC 設定)所必需。 編碼的文件金鑰、引用網址或父 ID 並不能取代它。

建議的 ACL(UserIds、GroupIds)架構屬性和 RBAC 範圍:

  • 使用者識別碼(ID)欄位,並附有 userIds 權限篩選器值。
  • 群組 ID 欄位,並帶有 groupIds permissionFilter 值。
  • 具有 rbacScope permissionFilter 值的 RBAC 範圍欄位。
  • 在查詢時啟用篩選的屬性 permissionFilterOption 。
  • 使用字串集合來記錄使用者與群組 ID,並使用純量字串作為 RBAC 範圍。
  • 所有欄位都設 filterable 為 true。

請注意,retrievable 是錯的。 你可以在開發過程中設定為 true,以確認權限是否存在,但請記得在部署到生產環境前先將 back 設為 false。

以下完整的最低索引定義包含來源路徑與權限欄位。 視需要新增您的內容欄位。

{
  "name": "my-adlsgen2-acl-index",
  "fields": [
    { "name": "id", "type": "Edm.String", "key": true },
    { "name": "metadata_storage_path", "type": "Edm.String", "searchable": false, "filterable": true, "retrievable": true },
    { "name": "UserIds", "type": "Collection(Edm.String)", "permissionFilter": "userIds", "filterable": true, "retrievable": false },
    { "name": "GroupIds", "type": "Collection(Edm.String)", "permissionFilter": "groupIds", "filterable": true, "retrievable": false },
    { "name": "RbacScope", "type": "Edm.String", "permissionFilter": "rbacScope", "filterable": true, "retrievable": false }
  ],
  "permissionFilterOption": "enabled"
}

設定索引器

索引器內的欄位映射會設定索引中欄位的資料路徑。 目標欄位與目的地欄位若依名稱或資料型態不同,則需要明確的欄位映射。 ADLS Gen2 中,若更改欄位名稱,以下中繼資料欄位可能需要欄位映射:

  • metadata_user_ids (Collection(Edm.String)) - ACL 使用者 ID 清單。
  • metadata_group_ids (Collection(Edm.String)) - ACL 群組 ID 清單。
  • metadata_rbac_scope (Edm.String) - 容器 RBAC 範圍。

在索引器中指定 fieldMappings 在索引時將權限元資料路由到目標欄位。

以下欄位映射片段屬於索引器定義的頂層,與 parameters並列。

{
  "fieldMappings": [
    { "sourceFieldName": "metadata_storage_path", "targetFieldName": "metadata_storage_path" },
    { "sourceFieldName": "metadata_user_ids", "targetFieldName": "UserIds" },
    { "sourceFieldName": "metadata_group_ids", "targetFieldName": "GroupIds" },
    { "sourceFieldName": "metadata_rbac_scope", "targetFieldName": "RbacScope" }
  ]
}

保留投影區塊的權限

如果某個技能集使用 索引投影,請透過投影映射來填充區塊索引,而非僅僅透過索引器欄位映射。 每個可搜尋區塊都需要其來源路徑及每個已設定的權限欄位。 直接從 /document/metadata_user_ids、 /document/metadata_group_ids、 和 /document/metadata_rbac_scope對應標註欄位;不要替換技能產生的值。

例如,將以下投影配置新增至已產生 /document/pages/*的技能集。 目標 adls-chunks 索引需要:

  • 具有 keyword 分析器的 Edm.String 金鑰。
  • 一個可 parent_id 篩選的欄位,類型為 Edm.String,與鍵分開。
  • 一個可搜尋的 chunk 欄位,類型為 Edm.String。
  • 先前顯示的路徑與權限欄位,設定 permissionFilterOption 為 enabled。
{
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "adls-chunks",
        "parentKeyFieldName": "parent_id",
        "sourceContext": "/document/pages/*",
        "mappings": [
          { "name": "chunk", "source": "/document/pages/*" },
          { "name": "metadata_storage_path", "source": "/document/metadata_storage_path" },
          { "name": "UserIds", "source": "/document/metadata_user_ids" },
          { "name": "GroupIds", "source": "/document/metadata_group_ids" },
          { "name": "RbacScope", "source": "/document/metadata_rbac_scope" }
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

不要對應產生的區塊鍵或 parent_id 自己。 保持父鍵欄位可篩選,讓僅權限處理時能找到現有區塊。 如果您也為父文件建立索引,請分別填寫其路徑和權限欄位。

新增欄位或對應不會回填現有記錄。 在修正結構描述、索引器對應與投影後,重設並執行索引器,以重新填入現有文件和區塊。 這會重新處理內容與增強處理;僅重新同步權限無法取代缺少來源上下文的情況。

建議與最佳實務

  • 在建立任何資料夾前,請仔細規劃 ADLS Gen2 的資料夾結構。

  • 將身份組織成群組,並盡可能使用群組,而非直接授權個別使用者存取權限。 持續新增個別使用者而非套用群組,會增加需要追蹤與評估的存取控制條目數量。 未遵循此最佳實務可能導致由於安全元資料的變動,需要對索引更頻繁地進行更新,從而導致更新過程的延遲和效率降低。

同步索引內容與來源內容之間的權限

索引儲存有效的使用者與群組 ACL 以及容器資源範圍。 它不會儲存儲存角色指派的副本。 請使用與變更相符的重新整理路徑:

變更 更新路徑
初始擷取處理、新檔案或已變更的內容 一般索引會將內容與支援的權限元資料一起匯入。
僅限 ADLS 檔案或目錄 ACL 預設啟用 refreshAllAcls 會在符合條件的正常執行中重新整理原本未變更的檔案,大約每天一次。
隨選執行完整來源 ACL 協調 請求 權限重新同步,然後執行索引器或等待其排程並確認完成。
儲存 RBAC 角色指派 查詢時授權評估被委派使用者對儲存容器範圍的存取權。 儲存傳播與授權快取適用;ACL 重新同步並不會強制這些快取重新整理。
現有記錄中缺少欄位或對應 修正管線,然後重設並重新處理現有紀錄,包括投影區塊。
移動、重新命名或刪除 使用連接程式專屬的身分與 刪除追蹤。 權限重新整理並不會清除過時的金鑰或孤立區塊。

自動 ACL 重新整理

refreshAllAcls 是 下 parameters.configuration的索引器設定,可在 REST API 2026-10-01中使用。 預設為 true;省略以使用預設值。 若要停用它,請在更新索引器時將 parameters.configuration.refreshAllAcls 設定為 false。

自動掃描僅適用於匯入使用者或群組 ACL 的 ADLS Gen2 資料來源。 它並非標準 Blob 或 ADLS 僅 RBAC 匯入的週期性 RBAC 刷新控制。 排程或手動執行索引器:設定不會自動啟動執行。

在符合條件的正常執行中,索引器會以大致每日的頻率刷新未變更檔案的 ACL。 它不會在每次排程執行時都掃描,而且重設文件和重新同步執行也不是一般執行的掃描。 這個節奏並不是新鮮度SLA,也不是立即撤銷的保證。

僅權限項目可在不擷取內容、執行技能或重新生成嵌入的情況下更新權限欄位。 在同一正常執行中變更的內容仍可進行擷取與擴充。 現有的投影區塊會透過權威投影映射獲得權限更新。

如果您停用自動刷新,僅 ACL 的變更可能會保持過時狀態,直到您明確重新同步或重新處理受影響的內容。 若要在不等待自動掃描的情況下完成完整來源 ACL 一致化,請依照 「如何重新同步並執行索引器」。 只有在需要針對性內容重新處理時,才使用 reset-docs (preview)。

監控並驗證同步情況

使用 Get Indexer Status 來檢查執行時間、狀態、項目數量、警告與錯誤。 僅僅一般內容執行成功,並不能證明自動執行了 ACL 掃描。 請求被接受也不代表重新同步已經完成。

在失敗或取消之後,有些紀錄可能會擁有比其他紀錄更新的權限。 解決錯誤、重試支援的重新整理,並測試代表性文件與區塊,然後才將語料庫視為已完成一致性校正。 記錄請求 ID 與執行時間以供故障排除;不要將項目計數解讀為語料庫範圍的權限時間戳記。

在檔案 ACL 變更、群組授權/移除以及祖先目錄遍歷變更後,驗證允許與拒絕的使用者。 對於混合 ACL/RBAC 匯入,請使用沒有替代支援 RBAC 授權的使用者測試 ACL 撤銷。 獨立授權仍可授權存取。 分別測試 RBAC 的授與和移除,並考量授權傳播與快取。 請參閱 教學驗證步驟。

刪除追蹤

要有效管理斑點刪除,請確保索引器首次運行前已啟用 刪除追蹤 功能。 此功能讓系統能偵測來源中已刪除的斑點,並將其從索引中移除。