indykite-authzen-evaluations

IndyKite AuthZEN - 批量评估

批量评估可在一次请求中做出多个 KBAC 决策。你可以提供顶层的 subject / action / resource / context 作为默认值，并提供一个 evaluations[] 数组，其中的每个条目只覆盖自己指定的部分；响应会按顺序为每个条目返回一个布尔值 decision。

本技能介绍如何构建并发送批量请求，以及如何读取结果。本技能不编写策略——每个条目评估所依据的 2.0-kbac 和 3.0-kbac 策略由 indykite-authzen-kbac-policies 编写。

适用场景

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

• 检查一个主体能否访问多个资源（例如：“这 20 台服务器中，哪些服务器允许 grace 执行 PROVISION？”）；
• 检查一个操作是否适用于多个主体（例如：“这些人中，哪些人能部署 gpu-node-7？”）；
• 在一次调用中评估多个不同的 (subject, action, resource) 三元组。

不要在以下场景启用本技能：做出单个是/否决策（indykite-authzen-evaluation）；针对一次探测枚举所有实例（搜索技能 indykite-authzen-search-action / -search-resource / -search-subject）；或编写策略或读取/写入图数据（批量评估只会生成决策）。

前提条件

• 一个或多个覆盖批次中各三元组的ACTIVE KBAC 策略。如果没有，请先使用 indykite-authzen-kbac-policies 编写策略。
• 一个 AppAgent 及其凭据令牌（即 X-IK-ClientKey 的值）。
• 已填充主体节点和资源节点的 IKG（以及条件匹配所需的任何关系）。
• 所有匹配策略引用的部分参数均已准备好，可通过 context.input_params 传入。

步骤

1. 选择默认值，再为每个条目设置差异

确定批次中哪些部分保持不变（放在顶层），哪些部分会变化（放在每个 evaluations[] 条目中）。条目会继承所有未覆盖的顶层部分。

示例：默认操作为 PROVISION，默认资源为 gpu-node-7；每个条目的主体各不相同，其中一个条目还覆盖了资源。

2. 构建批量请求正文

{
  "action":   { "name": "PROVISION" },
  "resource": { "type": "Server", "id": "gpu-node-7" },
  "evaluations": [
    { "subject": { "type": "Person", "id": "linus" } },
    { "subject": { "type": "Person", "id": "grace" } },
    { "subject": { "type": "Person", "id": "grace" }, "resource": { "type": "Server", "id": "edge-box-2" } },
    { "subject": { "type": "Person", "id": "dennis" } }
  ],
  "context": { "input_params": { "max_price": 80000 } }
}

subject.id / resource.id 是节点的 external_id；action.name 区分大小写；context.input_params 的键不带 $，并保留其类型。对于组合 IKG 上按位置路由的 3.0-kbac 策略，每个条目或默认值也要以相同方式传入其逻辑位置（{ "region": "east" }，即项目 alias_mapping 中的一个键）——请参阅 references/evaluations-reference.md。可直接使用的请求正文：assets/evaluations-provision-servers.json。

3. 发送批量请求

POST <API_URL>/access/v1/evaluations

身份验证：

• 始终需要：X-IK-ClientKey: <AppAgent-credentials-token>。
• 可选：Authorization: Bearer <user-access-token>——仅在某些情况下适用（例如条件引用了令牌声明/作用域），此时它可能会改变受声明限制的条目结果。

可运行的 shell 辅助脚本：scripts/evaluate-batch.sh——使用 --print 可预览 curl（固定主机；令牌会被隐藏）。

4. 读取决策——每个条目对应一个，顺序不变

{
  "evaluations": [
    { "decision": false },
    { "decision": true },
    { "decision": false },
    { "decision": true }
  ]
}

数组按位置对应：evaluations[i] 是请求中第 i 个条目的决策。

5. 留意缺少参数时的差异

单次 /evaluation 若省略了必需的部分参数，会返回 422。批量调用则不会整体失败——它会返回 200，且每个匹配策略需要该缺失参数的条目都会返回 decision: false，并包含 context.reason：

{ "decision": false, "context": { "reason": "invalid_argument: missing or wrong input params, 'max_price'" } }

因此，在判断访问被拒绝之前，务必区分真正的拒绝（decision: false，没有 context）和缺少输入导致的拒绝（decision: false，且带有 context.reason）。

结果

成功应用此技能后：

• POST /access/v1/evaluations 会返回一个 evaluations[] 数组，其中每个请求条目按顺序对应一个 decision，且正确将顶层部分应用为默认值。
• 缺少参数的条目会被识别为 decision: false + context.reason（状态码为 200），而不会被误认为请求失败。
• 每个批量决策都与单次决策技能（indykite-authzen-evaluation）针对相同三元组返回的结果一致。

此技能中的文件

• references/evaluations-reference.md - /evaluations：请求/响应格式、默认值与覆盖语义、缺少参数时的行为、错误代码。
• assets/evaluations-provision-servers.json - 可运行的批量请求正文，用于 PROVISION 示例。
• scripts/evaluate-batch.sh - 将批量请求发送到 /access/v1/evaluations 的 Bash 辅助脚本（固定主机；使用 --print 预览）。

Agent 专属说明

此技能使用通用 Markdown 指令，适用于 README 中列出的所有 Agent。Agent 需要能够发送 HTTP 请求（使用 curl、HTTP 客户端或 IndyKite Terraform provider）。不需要 Claude Code hooks、Cursor @ 提及或 Copilot 工作区上下文。

参考资料

• AuthZEN 指南（开发者中心）
• Config API 文档 - 授权策略
• 凭据指南