工作原理启用 ACL 管理 Real-time 访问验证获取 Atlassian 管理员证书限制后续步骤

Document-level 访问控制

Confluence Cloud 知识库可以选择支持文档级访问控制。启用后，Amazon Quick 会在每次抓取期间同步来自 Confluence 的访问控制列表 (ACL)，并在查询时验证每个用户的权限。用户只能在 Confluence 中看到他们有权访问的文档中的答案。

工作原理

当用户查询使用启用 ACL 管理的 Confluence 知识库的 Amazon Quick 代理时，系统会分两个阶段实施访问控制：

Pre-retrieval 筛选 — Amazon Quick 对向量索引执行语义搜索，以找到最相关的文档段落。系统会应用在上次抓取期间从 Confluence 同步的访问控制列表。这将生成一套初步的候选人文件。
Real-time 验证 — 系统通过检查查询用户在 Confluence 中的当前访问权限来实时验证候选文档。只有用户当前有权访问的文档才会出现在响应中。

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

Amazon Quick 会抓取以下 Confluence ACL 资源：

空间-默认情况下，空间权限适用于空间中的所有文档。
页面-可以将页面限制为特定的用户和群组。嵌套页面继承父页面的限制，并且可以有自己的限制。
博客-博客文章可以仅限于空间中的特定用户和群组。
附件-附加到页面或博客文章的文件继承其父文档的访问控制。

启用 ACL 管理

您可以在创建知识库的过程中在 “其他设置” 步骤中配置 ACL 管理。选中 “使用 ACL 控制文档访问权限” 复选框将其启用。此选项需要 Atlassian 管理员凭据，这些凭据是在身份验证方法步骤中提供的。如果没有管理员凭据，ACL 选项将被禁用。

重要

创建知识库后，您无法更改 ACL 管理。如果需要更改此设置，则必须创建新的知识库。

Atlassian 管理员凭证允许 Amazon Quick 访问您的 Confluence 实例中的所有用户和群组信息，无论个人的电子邮件可见性设置如何。有关从 Atlassian 组织获取管理员凭证的步骤，请参阅。获取 Atlassian 管理员证书有关知识库设置步骤，请参阅对您的账户进行身份验证。

有关 ACL 最佳实践的更多信息，请参阅知识库中管理 ACL 的最佳实践。

Real-time 访问验证

当用户提交涉及 ACL-enabled Confluence 知识库内容的查询时，Amazon Quick 会实时验证用户的访问权限：

用户在快速聊天助手中提问。
如果答案涉及 ACL-enabled知识库中的 Confluence 内容，Quick 会提示用户登录 Confluence。
用户使用其 Confluence 电子邮件和密码登录并接受授权对话框。
Quick 使用用户的凭证通过 Confluence API 实时验证对每个候选文档的访问权限。
只有用户当前有权在 Confluence 中访问的文档才会出现在响应中。

登录是一次性步骤。登录后，用户在会话到期后才会再次收到提示。

注意

如果实时权限验证失败（例如，如果 Confluence API 暂时不可用），则用户会看到一条错误消息，提示他们重试。Amazon Quick 不会回退到缓存权限，必须进行实时验证才能确保访问控制的准确性。

获取 Atlassian 管理员证书

要在 Confluence 知识库设置期间提供 Atlassian 管理员证书，您的 Atlassian 组织管理员必须完成以下步骤。

获取您的 API 密钥和组织 ID

使用管理员权限登录 Atlassian 管理门户。
打开组织的 Administration 应用程序。网址应如下所示:https://admin.atlassian.com/o/ORGANIZATION-UUID/overview.
从 URL 中复制组织 ID。
选择设置，然后选择 API 密钥。
选择创建 API 密钥。
为 API 密钥选择以下范围：
- read:directories:admin
- read:workspaces:admin
复制并保存组织 ID 和 API 密钥。

注意
API 密钥过期。请监控过期日期，并在密钥过期之前更新您的数据来源凭证。

获取目录 ID

使用 Atlassian 管理工作区 API 检索您的目录 ID。

运行以下命令，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 工作空间，因此您无需翻阅所有工作空间类型。

在 API 响应中，找到与您的 Confluence Cloud 实例匹配的工作区条目。验证工作空间名称是否与您的实例匹配。
复制该attributes部分中的directory值。这是您的目录 ID。

有关 Atlassian 管理员 API 范围的更多信息，请参阅 Atlassian API 范围文档。有关 API 的详细信息，请参阅 Atlassian 管理员工作区 API 参考。

限制

需要 Atlassian 管理员凭证 — Document-level 访问控制需要 Atlassian 管理员凭证，这些凭据必须在知识库设置期间提供。没有管理员凭据就无法启用 ACL，也无法在创建知识库后添加管理员凭证。
Real-time 必须进行验证 — Amazon Quick 总是在查询 ACL-enabled 知识库时执行实时权限检查。如果 Confluence API 不可用，则涉及 ACL-protected 内容的查询会返回错误，而不是回退到缓存的权限。

有关 ACL 的一般限制和最佳实践，包括 ACL 永久性、研究兼容性和电子邮件地址管理，请参阅知识库中管理 ACL 的最佳实践。

后续步骤

要验证文档级访问控制并解决权限问题，请参阅。检查文档访问权限（ACL 验证）有关设置 Confluence 知识库集成的信息，请参阅。设置知识库集成

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

知识库集成

Atlassian Jira 云集成