本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Document-level 访问控制
<a name="kb-managed-ds-onedrive-acl"></a>

OneDrive 数据源可以选择支持文档级访问控制。启用后，Bedrock Managed Knowledge Base 会同步每次抓取 OneDrive 期间的访问控制列表 (ACL)，并在查询时验证每个用户的权限，因此用户只能看到他们有权访问的文档的结果。 OneDrive有关所有连接器上的 ACL 感知概述，请参阅[访问控制列表感知启用](kb-managed-acl.md)。

**ACL 感知不是授权**  
Bedrock 托管知识库提供 ACL-aware 筛选功能，而不是安全边界。Bedrock Managed Knowledge Base 不对最终用户进行身份验证——您的应用程序负责对用户进行身份验证并传递经过验证的身份上下文。Bedrock 托管知识库无法验证您提供的用户上下文的真实性。因此，此功能会根据您提供的身份筛选结果，但并不构成真正的授权。如果没有上游身份验证，则不得依赖此功能作为唯一的访问控制机制。

## 工作原理
<a name="kb-managed-ds-onedrive-acl-how"></a>

当用户查询使用 ACL-enabled OneDrive 数据源的知识库时，Bedrock 托管知识库会分两个阶段实施访问控制：
+ **Pre-retrieval 筛选** — Bedrock Managed Knowledge Base 应用上次抓取 OneDrive 时同步的访问控制列表，仅返回允许用户（或其群组）访问的候选文档。
+ **Real-time 验证** — Bedrock 托管知识库通过检查查询用户的当前访问权限来实时验证候选文档。 OneDrive响应中仅包含用户当前有权访问的文档。

这种两阶段方法提供了文档级访问控制，即使 OneDrive 权限在两次同步之间发生变化，该控制也能保持最新状态。

## 爬行了什么
<a name="kb-managed-ds-onedrive-acl-crawl"></a>

启用 ACL 后，Bedrock 托管知识库会从中抓取文件级共享权限和安全组分配。 OneDrive还解决了嵌套（可传递的）群组成员资格问题。

在查询时，您可以传递用户的电子邮件地址（不是群组）。Bedrock Managed Knowledge Base 根据其抓取的数据解析该用户的群组成员资格，并在筛选结果时应用这些成员资格。有关身份模型的更多信息，请参阅[访问控制列表感知启用](kb-managed-acl.md)。

## ACL 感知的先决条件
<a name="kb-managed-ds-onedrive-acl-prereqs"></a>

ACL-enabled OneDrive 使用两个不同的微软 API，每个 API 在你的 Microsoft Entra 应用程序上都有自己的应用程序权限集：抓取使用微软 Graph API，实时验证使用 SharePoint REST API（OneDrive 企业版由支持）。 SharePoint在启用 ACL 感知之前，在获得管理员同意后，为这两个 API 配置权限。
+ `User.Read.All`以及`GroupMember.Read.All`在 Microsoft Graph 上（用于身份爬行）。
+ `Sites.FullControl.All`开启 SharePoint （用于文档访问验证）。 `Sites.Read.All`还不够 — 只读访问权限无法执行实时验证所需的有效权限检查。

**重要**  
抓取使用 Microsoft Graph API，实时验证使用 SharePoint REST API，即具有不同应用程序权限的不同资源。Microsoft Graph 身份爬取权限是必要的，但还不够：实时验证还需要获得管理员 SharePoint `Sites.FullControl.All`同意的权限。仅授予 Microsoft Graph 权限是即使用户有权访问 ACL-enabled OneDrive 数据源也不会返回任何结果的最常见原因。

有关包括证书在内的完整设置过程，请参阅[设置 Microsoft Entra 应用程序 ID 身份验证 OneDrive](kb-managed-onedrive-entra-setup.md)。

## 启用 ACL 感知
<a name="kb-managed-ds-onedrive-acl-enable"></a>

要为 OneDrive 数据源启用 ACL 感知，`aclEnabled`请在`true`中设置为`connectorParameters`并使用`ENTRA_APP_ID`身份验证类型。此身份验证类型使用应用程序权限，允许 Bedrock Managed Knowledge Base 在查询时抓取身份信息并验证文档访问权限。

**重要**  
ACL 配置是永久性的。您无法在没有 ACL 支持的情况下创建的数据源上启用 ACL，也无法在启用 ACL 后禁用 ACL。

启用 ACL 后 OneDrive，您必须在`connectionConfiguration`指向 Amazon S3 `certificateS3Path` 中的 PKCS \#12 (`.p12`) 证书文件时包含一个。此证书用于针对 SharePoint REST API 进行实时 ACL 验证。禁用 ACL 时，不需要使用。`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`字段是可选的。如果省略它，Bedrock Managed Knowledge Base 会使用应用程序的客户端 ID 作为密码打开 PKCS \#12 (`.p12`) 文件，因此必须使用该密码创建证书。我们建议您始终设置显式的高熵，`certificatePassword`以保护证书的静态私钥。

**注意**  
 ACL-enabled OneDrive 数据源不支持`OAUTH2`身份验证类型。您必须使用 `ENTRA_APP_ID`。

## Real-time 访问验证
<a name="kb-managed-ds-onedrive-acl-realtime"></a>

Bedrock Managed Knowledge Base 使用应用程序凭据完全在服务器端实时验证每个候选文档，无需最终用户登录或委托同意。由 OneDrive 于 for Business 由提供支持 SharePoint，因此 Bedrock 托管知识库会根据租户 OneDrive 主机的 SharePoint REST API 检查查询用户的有效权限。

OneDrive 实时验证使用双凭证模型，并且需要两个凭据：
+ 您的密钥中的客户端 ID 和客户端密 AWS Secrets Manager 钥会生成一个 Microsoft Graph 令牌，用于解析租户 OneDrive 的主机（`-my.sharepoint.com`主机）。
+ 来自的证书`certificateS3Path`会铸造用于权限检查本身的 SharePoint REST 令牌。该证书是实时验证的权威凭证，仅凭客户机密令牌无法执行检查。

**重要**  
应用程序必须在获得管理员同意的情况下持有 SharePoint `Sites.FullControl.All`权限；`Sites.Read.All`这还不够，因为有效的权限检查需要 manage/full-control权限。如果没有正确的权限，实时验证就无法评估有效权限，并且无法关闭，从而拒绝每个文档进行每次查询，即使用户具有访问权限并且抓取和检索前筛选成功时也是如此。请参阅 [ACL 感知的先决条件](#kb-managed-ds-onedrive-acl-prereqs)。

**注意**  
在您授予或同意 SharePoint 应用程序权限后，由于应用程序访问凭证已被缓存，因此更改最多需要一小时才能对更改前检查的用户生效。要更快地确认更改，请使用其他尚未被查询的用户进行测试。

## 验证配置
<a name="kb-managed-ds-onedrive-acl-verify"></a>

您可以独立于检索请求来验证您的 Entra 应用程序权限。执行以下每项检查：

1. **微软 Graph（抓取）**：
   + 获取带作用域的应用程序令牌`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 调用会立即在令牌级别成功，但是对于已经测试过的用户，端到端检索仍可能因访问验证中描述的缓存 TTL 而延迟。Real-time ](#kb-managed-ds-onedrive-acl-realtime)不要根据缓存的用户得出修复失败的结论。

## 问题排查
<a name="kb-managed-ds-onedrive-acl-troubleshooting"></a>

**注意**  
ACL 配置错误不会在检索过程中产生明显的错误。检索失败关闭：受影响的文档被静默省略，因此查询返回的结果较少或为零，而不是错误。使用上面的验证检查来诊断这些问题。


**ACL-enabled OneDrive 症状、原因和解决方法**  

| 症状 | 可能的原因 | Fix | 
| --- | --- | --- | 
| 检索会返回 0 个结果，但用户可以访问 OneDrive。 | 存在 Microsoft Graph 权限，但缺少 SharePoint 应用程序权限或管理员同意，因此 SharePoint REST 调用被拒绝，每个文档都被拒绝。 | 经管理员同意后授予 SharePoint Sites.FullControl.All权限。由于这些应用程序凭证已被缓存，因此最多允许一小时使更改生效，或者与尚未查询的用户进行测试以尽快确认。 | 
| 用户的访问权限已在中更改 OneDrive，但新的结果并未立即反映出来。 | Per-user 数据源和 Bedrock Managed 知识库之间的访问结果最终保持一致（通常在大约两分钟内），因此最近的访问权限更改可能不会立即反映出来。 | 在数据源反映更改后，请等待大约两分钟，然后重试。 | 
| 所有用户在之前工作后都会被拒绝。 | 证书已过期，或者管理员的同意已被撤销。 | 在 Entra 应用程序注册和 Amazon S3 中续订证书，然后重新授予管理员同意。 | 
| 尽管配置看起来正确，但抓取或同步失败。 | 缺少所需的 Microsoft Graph 应用程序权限。 | Grant Files.Read.All Sites.Read.All User.Read.All、、和GroupMember.Read.All。 | 
| 证书密码或令牌铸造错误。 | .p12密码不匹配certificatePassword。 | 设置certificatePassword为用于创建.p12文件的密码。 |