indykite-authzen-kbac

IndyKite KBAC - 授权策略

KBAC（基于知识的访问控制）是 IndyKite 的图驱动授权模型。KBAC 策略声明谁（subject）可以对什么（resource）执行哪些操作（actions），并受 Cypher（Neo4j / openCypher 图查询语言）中的条件限制；该条件会针对 IKG（IndyKite 的知识图谱，一种属性图数据库）进行评估。策略本身不会生成决策——它是一条规则，AuthZEN 端点会在请求决策或搜索时查询这条规则。

此技能涵盖 KBAC 策略生命周期：编写策略 JSON，并通过 Config API 管理策略。

• 一个策略包含 meta.policy_version: "2.0-kbac"、单个 subject.type、actions 列表、单个 resource.type，以及一个将保留变量 subject 和 resource 绑定起来的 condition.cypher。
• /configs/v1/authorization-policies 上的 Config API 操作：创建（POST）、读取（GET /{id} 或按名称读取）、列出（GET ?project_id=…&type=kbac）、更新（使用 If-Match ETag 执行 PUT /{id}）和删除（DELETE /{id}）。
• 发布：策略必须处于 ACTIVE 状态才能参与决策；INACTIVE 或 DRAFT 策略会被存储但忽略（DRAFT 甚至可能无效）。

策略处于 ACTIVE 状态后，运行时 AuthZEN 技能会对其进行评估：

需求	端点	技能
一次是/否决策	/access/v1/evaluation	indykite-authzen-evaluation
一次执行多项决策	/access/v1/evaluations	indykite-authzen-evaluations
主体可对资源执行的操作	/access/v1/search/action	indykite-authzen-search-action
主体可操作的资源（给定某个操作）	/access/v1/search/resource	indykite-authzen-search-resource
获准对资源执行某项操作的主体	/access/v1/search/subject	indykite-authzen-search-subject

适用场景

当用户想要执行以下操作时，启用此技能：

• 编写 KBAC 授权策略（policy_version: 2.0-kbac、subject、actions、resource、condition.cypher）；
• 通过 Config API 创建 / 发布策略，或在 DRAFT 和 ACTIVE 之间切换；
• 读取、列出、更新或删除现有 KBAC 策略（包括使用 ?type=kbac 列出策略，以便与 CIQ 策略区分）；
• 查找支持 indykite-authzen-evaluation 决策或 indykite-mcp-server authzen_evaluate 工具的策略。

当用户想要执行以下操作时，不要启用此技能：

• 作出决策（一个或多个三元组）——使用 indykite-authzen-evaluation / indykite-authzen-evaluations；
• 枚举获准的操作、资源或主体——使用搜索技能 -search-action / -search-resource / -search-subject；
• 编写 ContX IQ 读写策略（同一个 /configs/v1/authorization-policies 端点也支持 CIQ，通过 type=ciq 区分）——使用 indykite-ciq-* 技能；
• 创建 / 更新 / 删除图数据——KBAC 策略是针对图的规则，而不是对图的写入操作。

前置条件

• 一个 IndyKite 项目，以及项目的 GID，存放在 PROJECT_GID 中——它将成为策略的 project_id。
• 一个具有 Config API 写入权限的 服务账户令牌，存放在 SERVICE_ACCOUNT_TOKEN 中——每次调用 /configs/v1/authorization-policies 都会用到它。
• 策略的一个 主体类型——发出请求的节点类型（Person、Service、Namespace 等）。一个策略仅限于一种主体类型；如果两种主体类型需要执行相同的操作，请编写两个策略。
• 条件将匹配的 IKG 模型（节点类型、属性、关系）。可以在数据存在之前编写策略，但在空图上进行决策只会得到 false。

如果缺少上述任一项，请在编写 JSON 之前说明。

步骤

1. 将规则明确为（主体、操作、资源、条件）

每个 KBAC 策略都回答一种形式的问题。编写 JSON 前，请先确定这四个部分：

部分	含义	示例
subject	发出请求的单一节点类型。	Person
actions	策略授予的一个或多个大写动词。	["PROVISION"]
resource	被操作的单一节点类型。	Server
condition	必须成立才能使决策结果为 true 的 Cypher 模式 + WHERE 子句。	价格在预算范围内

本技能中始终使用的示例：

当服务器价格不超过评估时提供的预算时，Person（主体）可以对 Server（资源）执行 PROVISION 操作。

2. 编写 Cypher 条件

条件是一个 cypher 字符串。需要遵守两条硬性规则：

• 它必须绑定一个字面名称为 subject 的变量（与 subject.type 匹配），以及一个字面名称为 resource 的变量（与 resource.type 匹配）。在决策时，AuthZEN 请求中的 subject.id / resource.id 会与各节点的 external_id 匹配。
• 每次请求中可能变化的内容都是部分参数，在 WHERE 子句中写作 $name；决策调用会在 context.input_params 下提供该参数（不带 $）。这里的预算是 $max_price。

MATCH (subject:Person), (resource:Server)
WHERE resource.property.price <= $max_price

对于基于关系的规则，请匹配关系，而不是（或除了）检查属性：

MATCH (subject:Person)-[:CAN_AFFORD]->(resource:Server)

完整的条件语法（属性引用、多跳模式、部分参数）请参阅 references/policy-reference.md。

3. 组装策略及其创建封装

KBAC 策略恰好包含以下顶层键：meta.policy_version（"2.0-kbac"）、subject.type、actions、resource.type 和 condition.cypher。

Config API 不直接接收策略对象，而是接收一个创建封装，其中的策略是一个字符串化 JSON 值：

{
  "name": "kbac-person-provision-server",
  "display_name": "Person: PROVISION a Server within budget",
  "description": "Allow a Person to PROVISION a Server when its price is within a budget supplied at evaluation time.",
  "project_id": "<project-gid>",
  "policy": "{ \"meta\": { \"policy_version\": \"2.0-kbac\" }, … }",
  "status": "ACTIVE"
}

为便于阅读，资源文件 assets/policy-provision-server.json 将 policy 保留为对象，并将 project_id 设为占位符；创建步骤会在发送前设置 project_id 并将 policy 字符串化。

4. 创建策略

POST <API_URL>/configs/v1/authorization-policies

使用服务账户令牌进行身份验证：Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>。

# set project_id and stringify only the `policy` field, then POST
jq --arg pid "$PROJECT_GID" '.project_id = $pid | .policy |= tojson' assets/policy-provision-server.json \
  | curl -X POST "$API_URL/configs/v1/authorization-policies" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN" \
      -d @-

或者使用辅助脚本 scripts/create-policy.sh，它会设置 project_id、将 policy 字段字符串化、固定 IndyKite 主机，并在使用 --print 时隐藏令牌。

201 Created 响应会返回策略的 id（gid:…）、审计字段（create_time、created_by 等）以及一个 ETag 标头。请保留 id 和 ETag——更新和删除时需要它们。只有当策略的 status 为 ACTIVE 时，该策略才会参与决策。

5. 读取、列出、更新和删除

同一个 /configs/v1/authorization-policies 路径用于管理策略的生命周期（以下操作均使用 Service Account 令牌）：

• 按 ID 读取：GET /configs/v1/authorization-policies/{id} - 返回完整记录，包括字符串化的 policy、status、tags、审计字段和当前 ETag。
• 按名称读取：GET /configs/v1/authorization-policies/{name}?location={PROJECT_GID}。
• 列出 KBAC 策略：GET /configs/v1/authorization-policies?project_id={PROJECT_GID}&type=kbac - type=kbac 只返回 KBAC 策略（ContX IQ 请使用 type=ciq）。列表响应中每个条目的 policy 字符串均为空；如需获取策略正文，请按 ID 读取。
• 更新：使用标头 If-Match: <etag> 和包含要更改字段（display_name、description、policy、status、tags）的正文，向 /configs/v1/authorization-policies/{id} 发送 PUT 请求。可用此操作发布（status: "ACTIVE"）、停用（status: "INACTIVE"）、设为 DRAFT，或修改条件。响应会返回新的 ETag。
• 删除：使用标头 If-Match: <etag>，向 /configs/v1/authorization-policies/{id} 发送 DELETE 请求。

完整的请求和响应格式、响应字段以及 ETag 并发控制规则，请参阅 references/policy-reference.md。

结果

成功应用此技能后：

• 项目中存在一条 KBAC 策略，其中包含 policy_version: "2.0-kbac"、单个 subject.type、一个 actions 列表、单个 resource.type，以及一个将 subject 和 resource 绑定起来的 condition.cypher。
• 策略处于 ACTIVE 状态（或有意设为 INACTIVE / DRAFT），并且已知其 id 和当前 ETag，因此可以读取、更新或删除。
• 使用 ?type=kbac 列表查询时会显示该策略；对匹配的 (subject, action, resource) 三元组执行 indykite-authzen-evaluation 决策时，结果会体现该策略。

此技能中的文件

• references/policy-reference.md - KBAC 策略架构（meta、subject、actions、resource、condition.cypher、部分参数、多动作和关系变体）以及 Config API 生命周期（创建 / 读取 / 使用 ?type=kbac 列出 / 更新 / 删除、ETag 并发控制、响应字段）。
• assets/policy-provision-server.json - 可运行的 KBAC 策略创建信封，用于 Person PROVISION Server 示例。
• scripts/create-policy.sh - Bash 辅助脚本，用于设置 project_id、将 policy 字符串化，并将创建信封 POST 到 /configs/v1/authorization-policies（固定主机；使用 --print 进行预览）。

Agent 专属说明

此技能使用通用 Markdown 说明，可用于 README 中列出的所有 Agent。Agent 必须能够发送 HTTP 请求（使用 curl、HTTP 客户端或 IndyKite Terraform provider - 请参阅参考资料）。不需要 Claude Code hooks、Cursor @ 提及或 Copilot workspace 上下文。

参考资料

• AuthZEN 指南（开发者中心）
• 使用知识图谱进行动态授权（开发者中心）
• Config API 文档 - 授权策略
• Cypher 查询语言手册（Neo4j；openCypher） - KBAC 策略条件中用于查询 IndyKite 知识图谱的图查询语言。
• 音乐数据集教程（KBAC 策略与 AuthZEN 示例详解）
• KBAC 配方（开发者中心资源）
• IndyKite Terraform provider - indykite_authorization_policy
• 凭证指南