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

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

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

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

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

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

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

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

启用 ACL 后，Bedrock 托管知识库会从以下来源抓取以下权限结构： SharePoint
+ Site-level 成员资格和角色分配
+ 文档库级别的权限
+ Item-level （文件和页面）权限，包括破坏继承的唯一权限
+ 安全组成员资格，包括 Microsoft Entra ID (Azure AD) 安全组、支持邮件的安全组和通讯组。还解决了嵌套（可传递的）群组成员资格问题。

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

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

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

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

您的 Entra ID 应用程序注册必须具有以下应用程序权限：
+ `User.Read.All`还有`GroupMember.Read.All`在 Microsoft Graph 上（用于身份爬行）
+ `Sites.FullControl.All`开 SharePoint启或授予每个站点`Sites.Selected`的权限（用于验证文档访问权限）

`connectionConfiguration`必须包含`certificateS3Path`指向 Amazon S3 中的 PKCS \#12 (.p12) 证书文件的指向。

**注意**  
密钥中的`certificatePassword`字段是可选的。如果省略它，Bedrock Managed Knowledge Base 会使用应用程序的客户端 ID 作为密码打开 PKCS \#12 (.p12) 文件，因此证书必须是使用该密码创建的。我们建议您始终设置显式的高熵，`certificatePassword`以保护证书的静态私钥。

```
"connectorParameters": {
    "type": "SHAREPOINT",
    "version": "1",
    "aclEnabled": true,
    "connectionConfiguration": {
        "tenantId": "{{your-tenant-id}}",
        "authType": "ENTRA_ID_APP_ONLY",
        "secretArn": "{{arn:aws:secretsmanager:region:account-id:secret:secret-name}}",
        "certificateS3Path": {
            "s3BucketName": "{{your-certificate-bucket}}",
            "s3KeyName": "{{certs/certificate.p12}}"
        }
    },
    "dataEntityConfiguration": {
        "siteUrls": [
            "{{https://contoso.sharepoint.com/sites/engineering}}"
        ],
        "crawlFiles": true,
        "crawlPages": true
    }
}
```

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

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

Bedrock Managed Knowledge Base SharePoint 在查询时使用应用程序的基于证书的权限（为抓取配置的`ENTRA_ID_APP_ONLY`应用程序注册）对每个候选文档进行验证。与委托用户登录流程不同，不需要每位用户的交互式登录或同意，验证使用相同的应用程序注册和证书，通过`Sites.FullControl.All`或`Sites.Selected`权限来确认查询用户仍然可以访问每个文档。

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

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

1. **微软 Graph（抓取）**：
   + 获取带有范围的应用程序令牌`https://graph.microsoft.com/.default`并确认`roles`声明中包含`User.Read.All`和`GroupMember.Read.All`。
   + 调用 Microsoft Graph 站点端点（例如`GET https://graph.microsoft.com/v1.0/sites/{site}`）并确认它返回了该站点。

1. **SharePoint REST（实时验证）**：
   + 使用带作用域`https://{tenant}.sharepoint.com/.default`的证书客户端断言获取令牌。
   + 确认令牌的`roles`声明包含 SharePoint `Sites.FullControl.All`（或`Sites.Selected`）权限。`roles: null`值表示缺少权限或管理员同意。
   + 致电`GET https://{tenant}.sharepoint.com/_api/web`并确认其成功 (HTTP 200)。响应失败或未经授权意味着缺少 SharePoint 权限或管理员同意，这会导致所有文档都被拒绝。

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

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


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

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