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

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

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

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

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

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

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

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

启用 ACL 后，Bedrock 托管知识库会从 Confluence 中抓取以下权限结构：
+ **空间**-默认情况下，空间权限适用于空间中的所有文档。
+ **页面**-可以将页面限制为特定的用户和群组。嵌套页面继承父页面的限制。
+ **博客**-博客文章可以仅限于特定的用户和群组。
+ **附件**-附加到页面或博客文章的文件继承其父文档的访问控制。

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

要为 Confluence 数据源启用 ACL 感知，`aclEnabled`请在`true`中设置为`connectorParameters`并使用`BASIC`身份验证类型。除标准电子邮件和 API 令牌外，该密钥还必须包含 Atlassian 组织管理员凭证。这些管理员凭据是身份爬行所必需的。

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

除了标准`username`、`password`（API 令牌）和`hostUrl`字段外， AWS Secrets Manager 密钥还必须包含以下组织管理字段。有关获取这些值的分步说明，请参阅[为 Confluence 设置基本身份验证](kb-managed-confluence-basic-setup.md)。
+ `adminApiKey`— 范围为`read:directories:admin`和`read:workspaces:admin`的 Atlassian 组织 API 密钥。
+ `organizationId`— 您的 Atlassian 组织的 UUID。
+ `directoryId`— 您的 Confluence 工作空间的用户目录的 UUID。

**注意**  
 ACL-enabled Confl `OAUTH2` uence 数据源不支持该身份验证类型。您必须在密钥中`BASIC`与 Atlassian 组织管理员凭据一起使用。

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

Bedrock Managed Knowledge Base 使用密钥中配置的 Atlassian Admin API 令牌在查询时根据 Confluence 完全在服务器端验证每个候选文档，无需最终用户登录。管理员令牌会检查查询用户的当前空间、页面和博客限制，因此自上次抓取以来所做的访问权限更改将受到尊重。

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

您可以独立于检索请求来验证您的证书。执行以下每项检查：

1. **Confluence 内容访问权限（抓**取）：
   + 使用密钥中的`username`和 API 令牌 (`password`) 调用 Confluence REST API（例如，列表空间）并确认它返回 HTTP 200。

1. **Atlassian 管理员 API（身份抓取和实时**验证）：
   + 确认`adminApiKey`具有`read:directories:admin`和`read:workspaces:admin`范围。
   + 使用`adminApiKey`，为您调用 Atlassian 管理员目录 API，`organizationId``directoryId`并确认它会返回您组织的用户和群组。

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

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


**ACL-enabled Confluence 症状、原因和修复方法**  

| 症状 | 可能的原因 | Fix | 
| --- | --- | --- | 
| 检索会返回 0 个结果，但用户可以访问 Confluence。 | Atlassian Admin API 密钥缺少作用域，或者organizationId/directoryId错误，因此无法解决用户和群组限制。 | 确认 h adminApiKey as read:directories:admin 和read:workspaces:admin、that organizationId 和 an directoryId d 是否正确。 | 
| 抓取或同步失败。 | username或 API 令牌 (password) 无效。 | 验证密钥中的BASIC用户名和 API 令牌。 | 
| 所有用户在之前工作后都会被拒绝。 | API 令牌或管理员 API 密钥已过期或已被撤销。 | 轮换密钥中受影响的凭证。 |