本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Document-level 访问控制
Confluence Cloud 知识库可以选择支持文档级访问控制。启用后，Amazon Quick 会在每次抓取期间同步来自 Confluence 的访问控制列表 (ACL)，并在查询时验证每个用户的权限。用户只能在 Confluence 中看到他们有权访问的文档中的答案。
## 工作原理
当用户查询使用启用 ACL 管理的 Confluence 知识库的 Amazon Quick 代理时，系统会分两个阶段实施访问控制：
1. **Pre-retrieval 筛选** — Amazon Quick 对向量索引执行语义搜索，以找到最相关的文档段落。系统会应用在上次抓取期间从 Confluence 同步的访问控制列表。这将生成一套初步的候选人文件。
1. **Real-time 验证** — 系统通过检查查询用户在 Confluence 中的当前访问权限来实时验证候选文档。只有用户当前有权访问的文档才会出现在响应中。
这种两阶段方法提供了文档级访问控制，即使 Confluence 权限在两次同步之间发生变化，该控制也能保持最新状态。
Amazon Quick 会抓取以下 Confluence ACL 资源：
+ **空间**-默认情况下，空间权限适用于空间中的所有文档。
+ **页面**-可以将页面限制为特定的用户和群组。嵌套页面继承父页面的限制，并且可以有自己的限制。
+ **博客**-博客文章可以仅限于空间中的特定用户和群组。
+ **附件**-附加到页面或博客文章的文件继承其父文档的访问控制。
## 启用 ACL 管理
您可以在创建知识库的过程中在 **“其他设置”** 步骤中配置 ACL 管理。选中 “**使用 ACL 控制文档访问权限**” 复选框将其启用。此选项需要 Atlassian 管理员凭据，这些凭据是在**身份验证方法**步骤中提供的。如果没有管理员凭据，ACL 选项将被禁用。
**重要**
创建知识库后，您无法更改 ACL 管理。如果需要更改此设置，则必须创建新的知识库。
Atlassian 管理员凭证允许 Amazon Quick 访问您的 Confluence 实例中的所有用户和群组信息，无论个人的电子邮件可见性设置如何。有关从 Atlassian 组织获取管理员凭证的步骤，请参阅。[获取 Atlassian 管理员证书](#confluence-kb-atlassian-admin-credentials)有关知识库设置步骤，请参阅[对您的账户进行身份验证](confluence-knowledge-base.md#confluence-kb-setup-auth)。
有关 ACL 最佳实践的更多信息，请参阅[知识库中管理 ACL 的最佳实践](acl-best-practices-kb.md)。
## Real-time 访问验证
当用户提交涉及 ACL-enabled Confluence 知识库内容的查询时，Amazon Quick 会实时验证用户的访问权限：
1. 用户在快速聊天助手中提问。
1. 如果答案涉及 ACL-enabled知识库中的 Confluence 内容，Quick 会提示用户登录 Confluence。
1. 用户使用其 Confluence 电子邮件和密码登录并接受授权对话框。
1. Quick 使用用户的凭证通过 Confluence API 实时验证对每个候选文档的访问权限。
1. 只有用户当前有权在 Confluence 中访问的文档才会出现在响应中。
登录是一次性步骤。登录后，用户在会话到期后才会再次收到提示。
**注意**
如果实时权限验证失败（例如，如果 Confluence API 暂时不可用），则用户会看到一条错误消息，提示他们重试。Amazon Quick 不会回退到缓存权限，必须进行实时验证才能确保访问控制的准确性。
## 获取 Atlassian 管理员证书
要在 Confluence 知识库设置期间提供 Atlassian 管理员证书，您的 Atlassian 组织管理员必须完成以下步骤。
### 获取您的 API 密钥和组织 ID
1. 使用管理员权限登录 [Atlassian 管理门户](https://admin.atlassian.com/)。
1. 打开组织的 Administration 应用程序。网址应如下所示:`https://admin.atlassian.com/o/{{ORGANIZATION-UUID}}/overview`.
1. 从 URL 中复制**组织 ID**。
1. 选择**设置**，然后选择 **API 密钥**。
1. 选择**创建 API 密钥**。
1. 为 API 密钥选择以下范围：
+ `read:directories:admin`
+ `read:workspaces:admin`
1. 复制并保存**组织 ID** 和 **API 密钥**。
**注意**
API 密钥过期。请监控过期日期，并在密钥过期之前更新您的数据来源凭证。
### 获取目录 ID
使用 Atlassian 管理工作区 API 检索您的目录 ID。
1. 运行以下命令，{{ORGANIZATION-ID}}替换为您的组织 ID 和 {{API-KEY}} API 密钥：
```
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/{{ORGANIZATION-ID}}/workspaces' \
--header 'Authorization: Bearer {{API-KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"query": {
"field": {
"name": "attributes.type",
"values": ["confluence"]
}
},
"limit": 20
}'
```
此查询仅将结果筛选到 Confluence 工作空间，因此您无需翻阅所有工作空间类型。
1. 在 API 响应中，找到与您的 Confluence Cloud 实例匹配的工作区条目。验证工作空间名称是否与您的实例匹配。
1. 复制该`attributes`部分中的`directory`值。这是您的**目录 ID**。
有关 Atlassian 管理员 API 范围的更多信息，请参阅 [Atlassian API 范围文档](https://developer.atlassian.com/cloud/admin/scopes/)。有关 API 的详细信息，请参阅 [Atlassian 管理员工作区 API 参考](https://developer.atlassian.com/cloud/admin/organization/rest/api-group-workspaces/#api-group-workspaces)。
## 限制
+ **需要 Atlassian 管理员凭证** — Document-level 访问控制需要 Atlassian 管理员凭证，这些凭据必须在知识库设置期间提供。没有管理员凭据就无法启用 ACL，也无法在创建知识库后添加管理员凭证。
+ **Real-time 必须进行验证** — Amazon Quick 总是在查询 ACL-enabled 知识库时执行实时权限检查。如果 Confluence API 不可用，则涉及 ACL-protected 内容的查询会返回错误，而不是回退到缓存的权限。
有关 ACL 的一般限制和最佳实践，包括 ACL 永久性、研究兼容性和电子邮件地址管理，请参阅[知识库中管理 ACL 的最佳实践](acl-best-practices-kb.md)。
## 后续步骤
要验证文档级访问控制并解决权限问题，请参阅。[检查文档访问权限（ACL 验证）](sync-reports-observability.md#sync-reports-acl-verification)有关设置 Confluence 知识库集成的信息，请参阅。[设置知识库集成](confluence-knowledge-base.md#confluence-kb-setup)