Context Ontology Accelerator是一个开源的、基于本体（ontology）的语义上下文加速器，它让 AI Agent 能更准确、一致且可解释地做出决策。要安全地多团队协作使用它，关键就是搞清它的角色与权限管理：哪些内置角色、怎么授权、以及表级/列级数据授权如何生效。本文用一份完整清单带你快速上手，无需阅读源码即可掌握核心机制 🎯

两层授权模型：先搞懂请求如何被拦截

Context Ontology Accelerator 采用两层授权模型，任何一次数据查询必须同时通过两层检查：

请求到达 │ ▼ 第 1 层：Cedar 策略（API 网关鉴权） "这个用户能否调用该 API、访问该命名空间？" ├─ 拒绝 → 403 Forbidden └─ 允许 ▼ │ 第 2 层：SQL Firewall（查询执行时） "这个用户能否读取这些具体的表 / 列？" ├─ 拒绝 → 查询被拒并返回原因 └─ 允许 → 查询执行

两层相互独立：绕过任何一层都无法绕过另一层，且任一层解析失败都会拒绝（fail-closed）。

完整角色清单：2 个全局角色 + 4 个命名空间角色

系统内置两类角色。**平台角色（Platform Roles）**跨所有命名空间生效；**命名空间角色（Namespace Roles）**只在被授予的那个命名空间内生效。由于namespace-owner与namespace-maintainer功能完全等价，实际上形成5 种不同的权限档位：

🌐 全局平台角色（对所有命名空间生效）

📦 命名空间角色（仅限所授命名空间）

此外，任何已认证用户都可以列出命名空间（list动作）。

每个角色背后的权限由一份 Cedar 策略文件定义，例如data-analyst的策略 只授予query、readMetric、searchDocuments等只读动作。所有种子策略位于 libs/common/src/coa_authorization/seed/ 目录。

权限矩阵：谁能做什么一目了然

更细粒度的「API 端点 → Cedar 动作」完整映射，见官方文档 authz-access-matrix.md。

如何授权：给用户，还是给团队组？

授权（Grant）把「用户 / 用户组」与「角色 + 作用域」绑定，支持两种主体类型：

• User：指定一个邮箱（如alice@company.com）
• Group：匹配 IdP 中的组名，所有 token 携带该组的用户自动继承角色 ——团队场景的推荐做法，权限与身份提供方保持同步，无需逐人授权

重要提示：授权不会在 Cognito 或外部 IdP 中创建、校验用户。grant 只是一条「授权意图」，在匹配身份登录后才真正生效。所以给platform-admin授权前，请像对待任何特权操作一样仔细核对邮箱或组名。

管理入口：

• 平台授权：Web 应用Identity页面，或POST /grants（仅platform-admin可写）
• 命名空间授权：命名空间内的Permissions标签页，或POST /namespaces/{namespaceId}/grants

任何用户都可以通过GET /principals/{principalId}/grants查看自己的授权列表。

表级 / 列级数据授权：3 个可选字段

这是本系统权限模型的精华：同一个data-analyst，可以只让他看部分表、部分列、部分指标。在创建 grant 时附加 3 个可选的覆盖字段即可（字段契约定义在 grant.smithy）：

举个例子：给alice@company.com授予data-analyst后，SELECT name FROM customers可以执行，而SELECT ssn FROM customers或SELECT * FROM payroll会在查询执行时被 SQL Firewall 拦截。完整示例请求见 control-plane README。

⚠️ 两个容易踩的坑：

• 省略字段 = 无限制：不填这 3 个字段时，用户对该命名空间内的全部数据拥有查询权限（仍受 Cedar 动作级权限约束）
• 显式空列表 = 全部拒绝：传tableAllowlist: []表示「什么都不能查」，与「省略字段」含义完全不同

SQL Firewall 的具体实现在 packages/context-manager/src/coa_serve/tier2/sql_firewall.py：标识符比较大小写不敏感，解析失败、受限表上的SELECT *、异常 grant 配置一律拒绝。

关键规则：限制只叠加、不解除（platform-admin 也不例外）

这是整个权限模型中最反直觉、也最重要的一条：

没有任何角色能绕过第 2 层数据级限制 —— 包括platform-admin。

两层各自遵循不同合并规则：

• Cedar 层（动作级）取最宽松：持有多个角色时，任一角色允许即允许
• SQL Firewall 层（数据级）取最严格：限制累积且永不消解
  • columnDenylist：只要该命名空间的任一grant 拒了某列，该列就被拒
  • tableAllowlist/allowedMetrics：取各 grant 声明列表的并集；只有当没有任何grant 声明列表时才无限制

实际效果示例（针对命名空间ns-Z）：

含义：加更高级角色 ≠ 放开更多数据。要解除限制，必须撤销或修改携带限制的那条 grant。这是有意设计 —— 否则只要某人兼任一个不受限角色，PII 黑名单就会被悄悄绕过。需要「破例」读取时，请显式修改或新发一条 grant，留下可审计、可撤销的记录。

3 个实用授权模式

🚀 新团队入驻

1. 为团队创建命名空间
2. 给团队负责人授予data-steward（User grant）
3. 给团队 IdP 组授予data-analyst（Group grant）
4. 对敏感表追加数据级限制

🔒 限制 PII 访问给junior-analysts组授予data-analyst，并附带columnDenylist覆盖customers.ssn、customers.date_of_birth、employees.salary等敏感列。

🔍 审计员的平台级只读给审计组授予platform-viewer—— 他能查看所有命名空间，但无法放松任何命名空间级的数据限制，可与 PII 模式安全叠加。

常见行为补充：归档命名空间冻结

当命名空间处于ARCHIVED状态时，所有变更类操作（管理数据源/指标/本体、修改命名空间、授权等）会被一条 Cedarforbid策略硬性禁止，包括platform-admin和namespace-owner；读操作和重新激活（setNamespaceStatus）、删除仍允许。这条不变量同样不可被任何角色覆盖。

速查：相关文档与源码路径

一句话总结：Context Ontology Accelerator 用 Cedar 管「能调什么 API」，用 SQL Firewall 管「能读什么数据」；5 种角色档位覆盖从平台管理员到只读分析师的全部场景，而表级/列级授权让最小权限原则真正落到每一行数据上 ✅