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

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

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

Amazon S3 数据源可以选择支持文档级访问控制。与其他连接器不同，Amazon S3 没有本地权限系统可供抓取，因此您可以通过自己管理的配置文件来定义 ACL。有关所有连接器上的 ACL 感知概述，请参阅[访问控制列表感知启用](kb-managed-acl.md)。

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

对于 A ACL-enabled mazon S3 数据源，Bedrock 托管知识库在检索前筛选期间应用客户提供的访问控制列表，仅返回允许查询用户访问的文档。 Real-time Amazon S3 不支持 ACL 验证，因为客户提供的 ACL 元数据是真实来源。

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

要启用 Amazon S3 数据源的 ACL 感知，`true`请在中设置为`aclEnabled`，`connectorParameters`并使用以下两种方法之一定义访问权限：
+ **全局 ACL 配置文件** — 一个集中 JSON 文件，用于定义文件夹（前缀）级别的访问权限。非常适合具有稳定权限结构的组织。对全局文件的更改需要重新索引受影响的前缀。
+ **Document-level 元数据文件**-每个文档都有自己的元数据文件，其中包含访问控制信息。这可以在权限更改时更快地更新索引，因为只有受影响的文档才需要重新编制索引。

**重要**  
对于 ACL-enabled Amazon S3 数据源，不会提取没有关联 ACL 条目的文档。确保每个文档都有通过全局 ACL 文件或其元数据文件定义的 ACL。

```
"connectorParameters": {
    "type": "S3",
    "version": "1",
    "aclEnabled": true,
    "connectionConfiguration": {
        "bucketName": "{{your-bucket-name}}",
        "bucketOwnerAccountId": "{{123456789012}}"
    },
    "aclConfiguration": {
        "globalAccessControlListS3Uri": "s3://{{your-bucket-name}}/{{acl/global-acl.json}}"
    }
}
```

## 全局 ACL 文件结构
<a name="kb-managed-ds-s3-acl-global"></a>

全局 ACL 文件是一个 JSON 数组，其中每个条目都将一个 key prefix 映射到一组访问控制条目。每个`keyPrefix`都是文件夹（适用于其下的所有文档）或单个文档的绝对 Amazon S3 URI。

```
[
    {
        "keyPrefix": "s3://{{your-bucket-name}}/{{finance/}}",
        "aclEntries": [
            {
                "Name": "{{user1@example.com}}",
                "Type": "USER",
                "Access": "ALLOW"
            }
        ]
    }
]
```

每个`aclEntries`元素都包含：
+ `Name`— 用户的电子邮件地址。
+ `Type`— 一定是`USER`。
+ `Access`— 要`ALLOW`么是`DENY`。拒绝覆盖允许。

## Per-document 元数据文件
<a name="kb-managed-ds-s3-acl-perdoc"></a>

作为全局 ACL 文件的替代方案，您可以使用元数据文件为每个文档定义 ACL。为每个文档创建一个名`{{filename}}.metadata.json`为相同的 Amazon S3 路径的文件。包括一个与全局文件具有相同条目格式的`accessControlList`数组。

```
{
    "metadataAttributes": {},
    "accessControlList": [
        {
            "Name": "{{user1@example.com}}",
            "Type": "USER",
            "Access": "ALLOW"
        },
        {
            "Name": "{{user2@example.com}}",
            "Type": "USER",
            "Access": "DENY"
        }
    ]
}
```

Per-document 元数据优先于全局 ACL 文件。如果文档同时具有匹配的全局前缀条目和每个文档的元数据文件，则使用每个文档的元数据。

**注意**  
ACL 配置文件必须与您的数据源内容存储在相同的 Amazon S3 存储桶中。

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

由于 Amazon S3 ACL 是客户提供的，因此请在查询之前对其进行验证：

1. 确认`aclEnabled``true`在数据源中`connectorParameters`。

1. 确认每个文档都有一个 ACL，可以是全局 ACL 文件中的一个条目，也可以是每个文档的`.metadata.json`文件。没有 ACL 的文档不会被收录。

1. 验证 ACL JSON：每个条目都有 `Name``Type`（用户电子邮件`USER`）、（）和`Access`（`ALLOW`或`DENY`），并且 ACL 文件与您的内容位于同一个存储桶中。

1. 确认测试用户的电子邮件与您希望他们检索的文档`ALLOW`条目`Name`中的电子邮件完全匹配。

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

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


**ACL-enabled Amazon S3 的症状、原因和修复方法**  

| 症状 | 可能的原因 | Fix | 
| --- | --- | --- | 
| 对于本应具有访问权限的用户，检索会返回 0 个结果。 | 用户的电子邮件与任何 ACL 条目都不匹配（电子邮件不匹配）。 | 确保 ACL Name 与用户的电子邮件完全匹配。 | 
| 文件永远不会退还给任何人。 | 该文档没有 ACL 条目，因此未被收录。 | 通过全局 ACL 文件或每个文档的文件为文档.metadata.json添加 ACL，然后重新同步。 | 
| 每个文档的 ACL 未生效。 | .metadata.json文件名错误或路径错误。 | 将其{{filename}}.metadata.json命名为相同的 S3 路径；每个文档的元数据会覆盖全局文件。 | 
| ACL 的更改不会反映出来。 | 全局 ACL 文件更改需要对受影响的前缀重新编制索引。 | 重新同步受影响的前缀。 |