本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 文件層級存取控制
<a name="kb-managed-ds-onedrive-acl"></a>

OneDrive 資料來源可選擇性支援文件層級存取控制。啟用時，Bedrock 受管知識庫會在每個網路爬取期間同步 OneDrive 的存取控制清單 (ACLs)，並在查詢時驗證每個使用者的許可，因此使用者只會看到他們獲授權在 OneDrive 中存取的文件結果。如需所有連接器的 ACL 意識概觀，請參閱 [存取控制清單意識啟用](kb-managed-acl.md)。

**ACL 意識不是授權**  
Bedrock 受管知識庫提供 ACL 感知篩選，而不是安全界限。Bedrock 受管知識庫不會驗證最終使用者 — 您的應用程式負責驗證使用者並傳遞已驗證的身分內容。Bedrock 受管知識庫無法驗證您提供的使用者內容的真實性。因此，此功能會根據您提供的身分篩選結果，但不會構成真正的授權。在沒有上游身分驗證的情況下，您不得依賴此功能做為唯一存取控制機制。

## 運作方式
<a name="kb-managed-ds-onedrive-acl-how"></a>

當使用者查詢使用啟用 ACL 的 OneDrive 資料來源的知識庫時，Bedrock 受管知識庫會分兩個階段強制執行存取控制：
+ **擷取前篩選** — Bedrock 受管知識庫會套用上次網路爬取期間從 OneDrive 同步的存取控制清單，只傳回允許使用者 （或其群組） 存取的候選文件。
+ **即時驗證** — Bedrock 受管知識庫會檢查使用者在 OneDrive 中的目前存取權，以即時驗證候選文件。回應中僅包含使用者目前獲授權存取的文件。

這種兩階段方法提供文件層級的存取控制，即使 OneDrive 許可在同步之間變更，也能保持最新狀態。

## 爬取的內容
<a name="kb-managed-ds-onedrive-acl-crawl"></a>

啟用 ACLs時，Bedrock 受管知識庫會從 OneDrive 爬取檔案層級共用許可和安全群組指派。巢狀 （暫時性） 群組成員資格也會獲得解決。

在查詢時，您傳遞使用者的電子郵件地址 （非群組）。Bedrock 受管知識庫會從其編目的資料解析該使用者的群組成員資格，並在篩選結果時套用。如需身分模型的詳細資訊，請參閱 [存取控制清單意識啟用](kb-managed-acl.md)。

## ACL 意識的先決條件
<a name="kb-managed-ds-onedrive-acl-prereqs"></a>

啟用 ACL 的 OneDrive 使用兩種不同的 Microsoft APIs，每個 API 都有自己的應用程式許可設定在您的 Microsoft Entra 應用程式中：爬蟲程式使用 Microsoft Graph API，而即時驗證使用 SharePoint REST API (OneDrive for Business 由 SharePoint 支援）。在啟用 ACL 意識之前，在管理員同意的情況下設定兩個 APIs 的許可。
+ `User.Read.All` Microsoft Graph `GroupMember.Read.All`上的 和 （用於身分爬取）。
+ `Sites.FullControl.All` SharePoint 上的 （用於文件存取驗證）。 `Sites.Read.All`不足 — 唯讀存取無法執行即時驗證所需的有效許可檢查。

**重要**  
爬蟲程式使用 Microsoft Graph API，而即時驗證使用 SharePoint REST API — 具有不同應用程式許可的不同資源。Microsoft Graph 身分抓取許可是必要的，但還不夠：即時驗證還需要獲得管理員同意的 SharePoint `Sites.FullControl.All`許可。僅授予 Microsoft Graph 許可是啟用 ACL 的 OneDrive 資料來源即使使用者可以存取也不會傳回任何結果的最常見原因。

如需完整的設定程序，包括憑證，請參閱 [設定 OneDrive 的 Microsoft Entra App ID 身分驗證](kb-managed-onedrive-entra-setup.md)。

## 啟用 ACL 意識
<a name="kb-managed-ds-onedrive-acl-enable"></a>

若要啟用 OneDrive 資料來源的 ACL 意識，請在 `true`中`aclEnabled`將 設定為 `ENTRA_APP_ID` `connectorParameters`，並使用 驗證類型。此身分驗證類型使用應用程式許可，允許 Bedrock 受管知識庫在查詢時間爬取身分資訊並驗證文件存取。

**重要**  
ACL 組態是永久的。您無法在無 ACLs 支援的情況下建立的資料來源上啟用 ACL，而且一旦啟用，就無法停用 ACLs。

為 OneDrive 啟用 ACLs 時，您必須在`connectionConfiguration`指向 Amazon S3 `certificateS3Path`中 PKCS\#12 (`.p12`) 憑證檔案的 中包含 。此憑證用於針對 SharePoint REST API 進行即時 ACL 驗證。停用 ACLs時，`certificateS3Path`不需要 。

```
"connectorParameters": {
    "type": "ONEDRIVE",
    "version": "1",
    "aclEnabled": true,
    "connectionConfiguration": {
        "tenantId": "{{your-tenant-id}}",
        "authType": "ENTRA_APP_ID",
        "secretArn": "{{arn:aws:secretsmanager:region:account-id:secret:secret-name}}",
        "certificateS3Path": {
            "s3BucketName": "{{your-certificate-bucket}}",
            "s3KeyName": "{{certs/certificate.p12}}"
        }
    },
    "dataEntityConfiguration": {
        "crawlPersonalDrives": true
    }
}
```

**注意**  
秘密中的 `certificatePassword` 欄位是選用的。如果您省略它，Boodrock 受管知識庫會使用應用程式的用戶端 ID 做為密碼來開啟 PKCS\#12 (`.p12`) 檔案，因此必須使用該密碼建立憑證。我們建議您一律設定明確的高`certificatePassword`熵，以保護憑證的靜態私有金鑰。

**注意**  
啟用 ACL `OAUTH2` 的 OneDrive 資料來源不支援身分驗證類型。您必須使用 `ENTRA_APP_ID`。

## 即時存取驗證
<a name="kb-managed-ds-onedrive-acl-realtime"></a>

Bedrock 受管知識庫使用應用程式憑證，即時驗證每個候選文件，沒有最終使用者登入或委派的同意。由於商務用 OneDrive 由 SharePoint 提供支援，因此 Bedrock 受管知識庫會針對租戶 OneDrive 主機的 SharePoint REST API 檢查查詢使用者的有效許可。

OneDrive 即時驗證使用雙憑證模型，且需要兩個登入資料：
+  AWS Secrets Manager 秘密中的用戶端 ID 和用戶端秘密，會截取用來解析租戶 OneDrive 主機 (`-my.sharepoint.com`主機） 的 Microsoft Graph 字符。
+ 來自 的憑證會`certificateS3Path`刪除用於許可檢查本身的 SharePoint REST 字符。憑證是即時驗證的授權憑證 – 用戶端秘密字符無法單獨執行檢查。

**重要**  
應用程式必須持有具有管理員同意的 SharePoint `Sites.FullControl.All`許可；`Sites.Read.All`因為有效許可檢查需要管理/完整控制權限，所以不足。如果沒有正確的許可，即時驗證就無法評估有效許可，也無法關閉，即使使用者可以存取且爬蟲和擷取前篩選成功，也會拒絕每個查詢的每個文件。請參閱 [ACL 意識的先決條件](#kb-managed-ds-onedrive-acl-prereqs)。

**注意**  
在您授予或同意 SharePoint 應用程式許可後，最多需要一小時的時間，變更才會在變更之前檢查的使用者生效，因為應用程式存取登入資料會快取。若要更快確認變更，請使用尚未查詢的不同使用者進行測試。

## 驗證您的組態
<a name="kb-managed-ds-onedrive-acl-verify"></a>

您可以獨立於擷取請求來驗證您的 Entra 應用程式許可。執行下列各項檢查：

1. **Microsoft 圖形 （爬蟲）**：
   + 取得範圍為 的應用程式字符`https://graph.microsoft.com/.default`。
   + 解碼字符並確認`roles`宣告包含必要的 Microsoft Graph 許可 (`User.Read.All`、 `GroupMember.Read.All`和 `Files.Read.All`)。
   + 呼叫 `GET https://graph.microsoft.com/v1.0/users/{user}/drive/root/children` 並確認它列出使用者的磁碟機項目。

1. **SharePoint REST （即時驗證）**：
   + 使用範圍為 的憑證用戶端聲明來取得權杖`https://{tenant}-my.sharepoint.com/.default`。
   + 確認字符的`roles`宣告包含 SharePoint `Sites.FullControl.All`許可。`roles: null` 值表示缺少許可或管理員同意。
   + 呼叫`GET https://{tenant}-my.sharepoint.com/_api/web`並確認成功 (HTTP 200)。失敗或未經授權的回應表示缺少 SharePoint 許可或管理員同意，這會導致所有文件被拒絕。

**注意**  
修正許可後，SharePoint 呼叫會立即在權杖層級成功，但已測試使用者的end-to-end擷取仍可延遲[即時存取驗證](#kb-managed-ds-onedrive-acl-realtime)中所述的快取 TTL。請勿根據快取的使用者來結束修正失敗。

## 疑難排解
<a name="kb-managed-ds-onedrive-acl-troubleshooting"></a>

**注意**  
ACL 設定錯誤不會在擷取期間產生明確的錯誤。擷取關閉失敗：會無提示地省略受影響的文件，因此查詢會傳回較少或零的結果，而不是錯誤。使用上述驗證檢查來診斷這些問題。


**啟用 ACL 的 OneDrive 症狀、原因和修正**  

| 徵狀 | 可能原因 | 修正 | 
| --- | --- | --- | 
| 擷取會傳回 0 個結果，但使用者可以在 OneDrive 中存取 。 | Microsoft Graph 許可存在，但缺少 SharePoint 應用程式許可或管理員同意，因此 SharePoint REST 呼叫會遭到拒絕，且每個文件都會遭到拒絕。 | 授予具有管理員同意的 SharePoint Sites.FullControl.All許可。由於這些應用程式登入資料會快取，因此最多需要一小時的時間，變更才會生效，或是與not-yet-queried的使用者進行測試，以便更快確認。 | 
| 使用者在 OneDrive 中的存取已變更，但新結果不會立即反映。 | 每個使用者存取結果在資料來源和 Bedrock 受管知識庫 （通常在大約兩分鐘內） 之間最終一致，因此最近的存取變更可能不會立即反映。 | 在資料來源反映變更之後，請等待約兩分鐘，然後重試。 | 
| 所有使用者在先前運作後都會遭到拒絕。 | 憑證已過期，或管理員同意已撤銷。 | 在 Entra 應用程式註冊和 Amazon S3 中續約憑證，並重新授予管理員同意。 | 
| 雖然組態看起來正確，網路爬取或同步會失敗。 | 缺少必要的 Microsoft Graph 應用程式許可。 | 授予 Files.Read.All、User.Read.All、 Sites.Read.All和 GroupMember.Read.All。 | 
| 憑證密碼或字符挖掘錯誤。 | .p12 密碼不符合 certificatePassword。 | 將 certificatePassword設定為用來建立 .p12 檔案的密碼。 |