indykite-authzen-evaluation

IndyKite AuthZEN - 单次授权决策

KBAC 决策会向 AuthZEN 端点提出一个问题：此主体可以对此资源执行此操作吗？ 随后返回布尔值 decision。系统会根据当前处于 ACTIVE 状态的项目 2.0-kbac 策略对 IKG 进行求值，以得出决策。

此技能涵盖如何做出单次决策：构造 (subject, action, resource, context) 请求、发送请求并读取布尔值。此技能不会编写策略——决策所依据的策略（其 subject / actions / resource / condition.cypher）需通过 indykite-authzen-kbac-policies 编写。

这是 AuthZEN 系列中用于单次调用的技能：

需求	端点	技能
一次是/否决策	/access/v1/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 策略	Config API	indykite-authzen-kbac-policies

适用场景

当用户希望进行以下操作时，启用此技能：

• 判断某个主体是否可以对某个资源执行某项操作（例如：“ada 能否在预算为 120000 的情况下对服务器 gpu-node-7 执行 PROVISION？”）；
• 在应用中通过实时授权检查来控制某项操作；
• 排查单次决策返回 true 或 false 的原因。

不要启用此技能来编写或修改决策所依据的策略（indykite-authzen-kbac-policies），在一次调用中做出多个决策（indykite-authzen-evaluations），列举允许的操作 / 资源 / 主体，而不是测试一个三元组（搜索技能 -search-action / -search-resource / -search-subject），或返回或修改图数据（决策只有是/否，不会读取或写入数据）。

前提条件

• 一个或多个处于 ACTIVE 状态的 KBAC 策略，其 subject.type / actions / resource.type 覆盖此三元组。如果没有，请先通过 indykite-authzen-kbac-policies 编写策略；没有匹配策略的决策结果就是 false。
• 已为调用应用配置凭证的 AppAgent（凭证指南）。
• IKG 中已填充主体和资源节点（以及条件所匹配的任何关系）。求值会读取图，不会为图填充数据。
• 已准备好每个匹配策略所引用的部分参数，以便通过 context.input_params 传递。

如果缺少任何前提条件，请明确指出——先补齐条件，远比排查难以解释的 false 决策更省事。

步骤

1. 明确三元组及其上下文

确定问题的三个部分，以及每个请求的取值：

部分	字段	示例
主体	subject.type + subject.id	Person / ada
操作	action.name	PROVISION
资源	resource.type + resource.id	Server / gpu-node-7
上下文	context.input_params	{ "max_price": 120000 }

subject.id / resource.id 是节点的 external_id；action.name 区分大小写。

2. 构建请求正文

{
  "subject":  { "type": "Person", "id": "ada" },
  "resource": { "type": "Server",    "id": "gpu-node-7"  },
  "action":   { "name": "PROVISION" },
  "context":  { "input_params": { "max_price": 120000 } }
}

仅当匹配策略的条件引用 $name 部分参数时，才提供 context.input_params；填写各键时不带前导 $，并保留其类型（数字仍为数字）。基于复合 IKG 的位置路由 3.0-kbac 策略（使用 USE graph.byName($region)）也采用相同方式提供其逻辑位置——{ "region": "east" }，这是项目 alias_mapping 中的键，而不是数据库名称；位置缺失或未知会返回 422，用户令牌的身份与 subject 不同则会返回 403（参见 references/evaluation-reference.md）。可直接使用的请求正文：assets/evaluation-provision-server.json。

3. 发送决策请求

POST <API_URL>/access/v1/evaluation

端点会验证调用应用（始终需要其 AppAgent 凭据），并可选地验证用户（访问令牌；仅在某些情况下适用，例如条件引用了令牌声明或范围）。有关各凭据应放入哪个请求标头，请参阅凭据指南。

可运行的 shell 辅助脚本会构建经过身份验证的请求：scripts/evaluate.sh——使用 --print 预览 curl（固定主机；令牌已隐藏）。

4. 读取决策

{ "decision": true }

true 表示至少有一个 ACTIVE 策略在其条件满足时，授权了 (subject, action, resource) 三元组。false 表示没有策略授权该三元组——可能是没有策略匹配该三元组，也可能是匹配策略的条件不满足所提供的 input_params 和图数据。false 决策是正常的 200 响应，并非错误。

5. 验证

如果决策结果与预期不符，请先按此清单逐项检查，再进行更改：

1. 策略是否为 ACTIVE？ 草稿或非活跃策略会被忽略。
2. 三元组是否匹配？ subject.type、action.name 和 resource.type 必须与策略的 subject.type、actions 和 resource.type 完全匹配（动词区分大小写）。
3. 变量是否命名为 subject / resource？ 条件只能通过这些保留名称绑定请求中的主体和资源。
4. ID 是否为 external_id？ subject.id / resource.id 会与节点的 external_id 匹配。ID 错误时不会匹配任何内容 → false。
5. 是否提供了每个 $param？ 缺少条件所需的 input_params 键会返回 422（errors: ["missing or wrong input params, '<name>'"]），而不是静默返回 false。
6. 数据是否确实存在于 IKG 中？ 确认主体节点、资源节点以及任何匹配的关系都存在。

完整的请求/响应架构、错误表和更深入的故障排查指南：references/evaluation-reference.md 和 references/troubleshooting.md。

结果

成功应用此技能后：

• 对于具有有效 input_params 的允许 (subject, action, resource) 三元组，POST /access/v1/evaluation 会返回 {"decision": true}；对于拒绝的三元组，则返回 {"decision": false}。
• 缺少必需的 input_params 键时，会返回 422，应修正该问题，而不能误判为拒绝。
• 同一个三元组可通过 indykite-authzen-evaluations 批量评估，也可通过 indykite-mcp-server 的 authzen_evaluate 工具调用，决策语义保持一致。

此技能中的文件

• references/evaluation-reference.md - /evaluation 端点：基础路径、身份验证、请求/响应格式、错误代码，以及批量和搜索相关技能的链接。
• references/troubleshooting.md - 决策为何会意外地为 true/false，以及如何确定相关策略。
• assets/evaluation-provision-server.json - Person PROVISION Server 示例的可运行单次评估请求正文。
• scripts/evaluate.sh - 用于向 /access/v1/evaluation 发送决策请求的 Bash 辅助脚本（固定主机；使用 --print 可预览）。

特定于 Agent 的说明

此技能使用通用 Markdown 说明，适用于 README 中列出的所有 Agent。Agent 必须能够发送 HTTP 请求（使用 curl、HTTP 客户端或 IndyKite Terraform 提供程序）。不需要 Claude Code hooks、Cursor @-mentions 或 Copilot 工作区上下文。

参考资料

• AuthZEN 指南（开发者中心）
• 使用知识图谱实现动态授权（开发者中心）
• KBAC：使用 AuthZEN API 实现基于关系的授权
• KBAC：使用输入参数实现参数化授权（max_price）
• 音乐数据集教程（KBAC + AuthZEN 示例详解）
• 凭证指南