Restrict Access to Sensitive Documents in Your Amazon Q S3 Knowledge Bases¶

Ch11.022 Restrict Access to Sensitive Documents in Your Amazon Q S3 Knowledge Bases¶

📊 Level ⭐⭐ | 18.7KB | entities/restrict-access-to-sensitive-documents-in-your-amazon-q-s3-knowledge-bases.md

概述¶

Amazon Q 的 S3 知识库文档级 ACL（Access Control List）功能是企业级 RAG（检索增强生成）系统在权限收敛层的关键工程实践。该功能解决了两个核心问题：知识库级别的粗粒度权限控制无法满足敏感文档的隔离需求，以及传统 S3 bucket 权限与 AI 查询层的联动缺失。

通过文档级 ACL，管理员可以在同一知识库内实现"部分用户可见 / 部分用户不可见"的差异化访问策略，适用于 HR、财务、法律等受监管数据的隔离场景。

核心机制：ACL 评估在查询时而非索引时¶

文档级 ACL 的执行时机是一个容易被低估的设计决策。Amazon Q 在查询时（query time）评估用户身份与 ACL 配置的匹配关系，而非索引时。

这一设计带来三个关键特性：

索引层无需预先过滤：文档可以被完整索引，但查询结果根据用户权限动态过滤。这意味着 S3 上的文档原样保留，无需在索引前做权限预处理。
支持"否认优先"（Deny-by-default）：未在 ACL 文件中明确列出的文档或前缀，默认拒绝访问。Fail-closed 行为确保配置遗漏不会导致意外数据泄露。
ALLOW vs DENY 的短路评估：同一用户对同一文档同时存在 ALLOW 和 DENY 时，DENY 优先。这一设计允许组织在团队或群组层面设置宽泛的 ALLOW 规则，然后针对特定资源实施精确的 DENY 限制。

相比"索引时过滤"的设计，查询时评估的优势在于：索引构建与权限决策分离，ACL 配置变更不需要重新索引整个 prefix，只触发增量同步。

两种 ACL 配置方法¶

Global ACL 文件¶

适用场景：权限结构稳定、以 folder/prefix 为粒度的组织。

配置方式：在 S3 bucket 根目录或特定 prefix 下放置一个集中式 JSON 文件（如 quicksight-acl.json），定义所有用户的访问权限。

优势：

单一文件管理，维护成本低
权限变更只需修改一处
适合稳定的文件夹结构

劣势：

权限变更时需要重新索引整个 affected prefix
在大型文件夹结构下可能导致较长的同步时间

Document-level Metadata 文件¶

适用场景：权限变更频繁、需要精确到单文档控制的场景。

配置方式：为每个文档创建同名的 .metadata.json sidecar 文件，在其中定义该文档的访问权限。

优势：

变更只影响单个文档的重新索引
权限决策与文档本身绑定，逻辑内聚

劣势：

每个文档需要一个 sidecar 文件，管理的文件数量随文档线性增长
元数据文件的所有权应分配给熟悉各数据集敏感性的团队成员

选择逻辑总结：

维度	Global ACL	Document-level Metadata
权限变更频率	低频	高频
控制粒度	Prefix/Folder	单文档
索引开销	全 prefix 重新索引	单文档增量同步
管理复杂度	低（单一文件）	高（文件数 = 文档数）

选择公式：权限变更频率 × 文档数量 决定了配置方法的优劣。高频变更 + 大量文档 = metadata 文件；低频变更 + folder 级别隔离 = Global ACL 。

IAM Policy Assignments 的纵深防护¶

值得注意的是，文档级 ACL 控制的是知识库内的文档访问权限，但无法控制知识库本身的创建权限。这是两个正交的权限维度。

权限类型	控制内容
IAM Policy Assignments	哪些用户可以用哪些 S3 bucket 创建知识库
Document-level ACL	已创建的知识库内，用户可以看到哪些文档

两者组合才能形成完整的防护体系：

IAM 层面：防止在敏感 bucket 上创建不带 ACL 的知识库
ACL 层面：控制知识库内部的文档级访问

绕过风险与防护¶

如果不对知识库创建权限进行控制，任何拥有 S3 bucket 访问权限的 QuickSight 用户都可以在同一 bucket 上创建一个未启用 ACL 的新知识库，从而绕过文档级访问控制直接访问所有文档。

这一风险在共享 S3 bucket 场景下尤为突出。组织必须在知识库创建层面实施预防性控制，而非仅依赖知识库内部的 ACL 配置。

建议：在包含敏感文档的 S3 bucket 上，应限制只有受信任的管理员才能创建知识库。IAM policy assignment 是可选的但强烈推荐使用。

QuickSight Flows 与 ACL 的集成¶

QuickSight Flows 支持在自动化流程中嵌入 ACL 评估，实现运行时权限检查 。

这对于构建企业级"AI 助手 + 文档访问"自动化流水线意义重大。例如 executive summary 生成流程可以在步骤层面检查用户是否有权访问相关文档，无权访问时自动降级到 web 搜索而非返回错误。

ACL 感知工作流的典型应用场景：

定期报告自动生成（基于用户有权限访问的文档）
领导层简报生成
跨部门数据汇总（仅聚合用户有权限看到的内容）
合规审计文档准备

这确保了数据治理策略在人工和自动化场景下的一致性执行。

关键工程约束¶

1. 不可逆性¶

启用文档级 ACL 是单向操作，无法在后续关闭。建议在任何生产部署前先在测试或非生产知识库上完整验证配置正确性，特别是验证 ALLOW 和 DENY 规则的优先级行为是否符合预期。

2. 身份匹配规则¶

ACL 中的 Name 字段必须与 Quick 用户的 email 地址精确匹配
email 匹配不区分大小写
Group 名称必须完全一致
用户 email 变更需要同步更新 ACL 文件

3. ACL 文件本身的写权限管控¶

任何可以修改 ACL 文件的用户都可以给自己授予任意文档的访问权限。安全建议：

S3 s3:PutObject 权限应严格限制在最小权限集内
S3 bucket 上启用 versioning 以保留 ACL 文件的历史版本变更记录
将 Document-level 元数据文件的所有权分配给数据所有者或安全负责人
定期审查 CloudTrail 审计日志以检测异常配置变更

4. 同步延迟¶

QuickSight 不实时监控 ACL 文件变更。权限更新在下一次知识库同步（默认每日）后才生效。

对于时间敏感的权限撤销场景（如员工离职、合同终止），必须手动触发立即同步 。

部署最佳实践¶

分层防护策略¶

将 IAM policy assignment（控制哪些用户可以在哪些 S3 bucket 上创建知识库）与知识库内部的文档级 ACL 结合使用，形成纵深防御。

配置验证流程¶

在测试环境验证 ACL 配置正确性
验证 ALLOW 和 DENY 规则的优先级行为
验证用户身份匹配（email 精确匹配）
验证 Flows 中的 ACL 感知行为
确认手动同步机制可用

变更管理¶

任何 ACL 变更前先在测试知识库验证
启用 S3 versioning 保留变更历史
记录所有 ACL 变更到审计日志
定期（建议每季度）审查 ACL 配置的合理性

深度分析¶

查询时评估将权限控制从"配置时"转化为"访问时"¶

Amazon Q 选择在查询时评估 ACL 而非索引时，这一设计决策的深层含义在于：它将权限控制从数据工程问题转化为运行时决策问题。索引时评估要求在数据入湖时就知道"谁会访问什么"，这在多租户或动态权限场景下会导致索引管道复杂化；查询时评估则允许索引保持原样，权限决策在用户发起请求时才发生。这意味着同一个 S3 bucket 可以服务于不同权限域的用户，而无需为每个权限组合维护独立索引。不过，这也意味着 ACL 配置错误的发现被推迟到了运行时，而非在数据入湖时就被捕获。

Deny-by-default 是企业级 RAG 的安全基线¶

Fail-closed 行为（deny-by-default）不仅仅是一个技术特性，它代表了企业级 AI 系统访问控制的哲学转变。在传统 RBAC 中，管理员习惯于"默认放行、显式拒绝"的思维模式；而在文档级 ACL 场景下，未列出的资源自动拒绝意味着权限管理的容错性为零——任何 ACL 配置遗漏都会直接导致部分用户"看不见"他们应该能访问的文档。这种零默认容错模型在 HR、财务等强合规要求场景下是必要的，但也对 ACL 文件的维护流程提出了更高要求：必须为每个新加入的 prefix 和用户显式添加 ALLOW 规则，否则会在日常运营中引发大量"看不见文档"的工单。

Global ACL vs Metadata 的本质是"变更频率 × 重新索引开销"的权衡¶

两种 ACL 配置方法的根本差异不在于技术实现，而在于变更频率与重新索引开销的权衡。Global ACL 在权限变更时需要重新索引整个 affected prefix，如果一个 prefix 包含数万份文档，即使只改变了一个用户的访问权限，也要触发全量重新同步；Metadata 方案虽然支持单文档增量更新，但每个文档配套一个 .metadata.json sidecar 文件，当文档数量增长到数万时，sidecar 文件的数量和管理复杂度会线性爆炸。实践中，混合策略（Global ACL 处理稳定的基础权限结构 + Metadata 处理动态的例外情况）是大多数组织的最优选择。

IAM Policy Assignment 与 Document ACL 是互补而非冗余的两层防线¶

这两个控制维度解决的是完全不同的问题：IAM Policy Assignment 控制"谁能在哪个 S3 bucket 上创建知识库"，Document ACL 控制"知识库创建后用户能看到哪些文档" 。没有 IAM 层的情况下，恶意用户可以在同一个敏感 S3 bucket 上创建自己的"影子知识库"（不带 ACL），直接绕过文档级控制访问所有数据。这是共享 bucket 场景下的典型攻击向量，也是为什么 AWS 官方文档将 IAM 层描述为"可选但强烈推荐"——对于包含敏感数据的 bucket，这层防护实际上是必需的。

ACL 文件本身是最高价值的攻击面¶

在评估 Amazon Q 文档级 ACL 的安全性时，ACL 配置文件的写入权限是最容易被忽视但最关键的 attack surface 。任何获得 s3:PutObject 权限的人都可以为自己授予任意文档的访问权限——这与修改 IAM Policy 的高权限门槛形成对比，ACL 文件的写入在共享 bucket 场景下可能仅因为 broad S3 权限就意外开放。这意味着：S3 bucket 上 ACL 文件的写入权限必须与 S3 bucket 本身的写入权限分离管理；S3 versioning 必须开启以支持变更审计；ACL 文件的 owner 应明确归属到数据安全负责人而非应用开发团队。

实践启示¶

启用 ACL 前，必须在非生产环境完成完整验证。启用文档级 ACL 是单向不可逆操作，一旦开启只能通过重建知识库来关闭。建议在测试知识库上模拟完整的 ALLOW/DENY 场景，包括验证：当同一用户同时出现在 ALLOW 和 DENY 规则时 DENY 生效；未在 ACL 中列出的 prefix 默认拒绝；身份匹配（email 大小写、group 名称精确性）正确工作。
部署顺序：先 IAM Policy Assignment，再启用 ACL。对于包含敏感数据的 S3 bucket，应先通过 IAM Policy Assignment 限制只有受信任管理员能在该 bucket 上创建知识库，然后再在知识库层面启用文档级 ACL 。跳过 IAM 层意味着共享 bucket 上的任何 QuickSight 用户都能创建影子知识库绕过 ACL。
将 ACL 文件视为一等安全资产进行管理。S3 s3:PutObject 权限应严格限制在最小权限集内；S3 bucket 必须启用 versioning 以保留变更历史；建议将 Document-level metadata 文件的所有权明确分配给数据所有者或安全负责人。CloudTrail 审计日志应用于定期检测异常 ACL 配置变更。
在员工离职和合同终止流程中嵌入"手动触发知识库同步"步骤。QuickSight 不实时监控 ACL 文件变更，权限撤销默认在下次每日同步后生效。对于时间敏感的权限撤销场景（如关键岗位员工突然离职），必须手动触发立即同步，并在 IAM 层同时撤销该用户创建新知识库的权限。
身份治理与 ACL 维护必须联动。ACL 中的 Name 字段必须与 QuickSight 用户的 email 地址精确匹配。当用户 email 变更（如换岗、姓名变更）时，需要同步更新所有相关 ACL 文件中的 Name 字段，否则该用户会因 email 不匹配而失去应有访问权限，或在某些边缘情况下获得意外访问权限。建议将 email 变更流程与 ACL 维护流程在 ITSM 系统中强制绑定。