View a markdown version of this page

Document-level 访问控制 - Amazon Bedrock
工作原理爬行了什么感知 ACL 的先决条件启用 ACL 感知Real-time 访问验证验证配置问题排查

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

Document-level 访问控制

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

ACL 感知不是授权

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

工作原理

当用户查询使用 ACL-enabled OneDrive 数据源的知识库时，Bedrock 管理知识库分两个阶段强制执行访问控制：

  • Pre-retrieval 过滤 — Bedrock Managed Knowledge Base 应用上次抓取 OneDrive 期间同步的访问控制列表，仅返回允许用户（或其群组）访问的候选文档。

  • Real-time 验证 — Bedrock Managed 知识库通过检查查询用户的当前访问权限来实时验证候选文档。 OneDrive响应中仅包含用户当前有权访问的文档。

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

爬行了什么

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

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

感知 ACL 的先决条件

ACL-enabled OneDrive 使用两种不同的微软 API，每个 API 在你的微软 Entra 应用程序上都有自己的应用程序权限设置：抓取使用微软 Graph API，实时验证使用 SharePoint REST API（商业版由）OneDrive 提供支持。 SharePoint在启用 ACL 感知之前，征得管理员同意，为这两个 API 配置权限。

  • User.Read.All然后GroupMember.Read.All在微软Graph上（用于身份爬行）。

  • Sites.FullControl.All开启 SharePoint （用于文件访问验证）。Sites.Read.All还不够 — 只读权限无法执行实时验证所需的有效权限检查。

重要

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

有关包括证书在内的完整设置过程，请参阅设置 Microsoft Entra 应用程序 ID 身份验证 OneDrive。

启用 ACL 感知

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

重要

ACL 配置是永久性的。您无法在不支持 ACL 的情况下创建的数据源上启用 ACL，也无法在启用 ACL 后将其禁用。

启用 ACL 后 OneDrive，您必须certificateS3Path在connectionConfiguration指向 Amazon S3 的 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 访问验证

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

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 感知的先决条件。

注意

在您授予或同意 SharePoint 应用程序权限后，请等待最多一小时让更改对更改前检查的用户生效，因为应用程序访问凭证已缓存。要尽快确认更改，请向尚未查询的其他用户进行测试。

验证配置

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

  1. 微软图形（爬行）：

    • 获取具有范围的应用程序令牌https://graph.microsoft.com/.default。

    • 对令牌进行解码并确认roles索赔包含所需的微软图形权限（User.Read.AllGroupMember.Read.All、和Files.Read.All）。

    • 致电GET https://graph.microsoft.com/v1.0/users/{user}/drive/root/children并确认它列出了用户的云端硬盘项目。

  2. 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 不要根据缓存的用户得出修复失败的结论。

问题排查

注意

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

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