indykite-authzen-search-action

IndyKite AuthZEN - action search

Action search 会向 AuthZEN 端点询问：该主体可以对该资源执行哪些操作？ 它会返回当前 ACTIVE KBAC 策略和当前图状态下获准的操作名称列表，而不是单个布尔值。

它是三个 AuthZEN 搜索端点之一，每个端点都会固定 (subject, action, resource) 中的两个部分，并枚举第三个部分：

端点	固定部分	枚举内容	技能
/search/action	subject + resource	actions	此技能
/search/resource	subject + action	resources	indykite-authzen-search-resource
/search/subject	resource + action	subjects	indykite-authzen-search-subject

此技能涵盖如何构建并发送请求，以及如何读取结果。它不会编写策略——这些结果中的 actions 来自 2.0-kbac 和 3.0-kbac 策略，编写这些策略请使用 indykite-authzen-kbac-policies。

适用场景

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

• 列出主体可以对特定资源执行的所有操作（例如，“linus 可以对 gpu-node-7 做什么？”）；
• 驱动一个 UI，仅显示用户当前获准对某个项目执行的操作；
• 排查 (subject, resource) 对中某个预期操作为何获准或未获准。

如果要查询单个是/否决策（indykite-authzen-evaluation）、枚举资源或主体（使用相应的搜索技能）、一次运行多个决策（indykite-authzen-evaluations），或编写策略或读写图数据（搜索仅会列出操作），则不要启用此技能。

前提条件

• 一个或多个 subject.type / resource.type 与所查询对象对匹配的 ACTIVE KBAC 策略。如果没有，请先使用 indykite-authzen-kbac-policies 编写策略；在空策略集上搜索会返回 {"results": []}。
• 一个已为调用应用配置凭据的 AppAgent（凭据指南）。
• 已填充主体和资源节点的 IKG（以及策略条件所匹配的任何关系）。搜索会评估图数据，但不会填充图数据。
• 候选策略引用的任何部分参数，并准备通过 context.input_params 传入。

如果缺少任何前提条件，请明确说明——策略缺失或节点不存在导致的空结果集，与确实“没有允许的操作”看起来完全相同。

步骤

1. 固定主体和资源

Action search 会固定主体和资源，并查询它们之间允许执行哪些操作。使用各自节点的 external_id 标识它们：

部分	字段	示例
主体	subject.type + subject.id	Person / linus
资源	resource.type + resource.id	Server / gpu-node-7

没有 action 字段——此搜索的目的正是发现可执行的操作。

2. 构建请求正文

{
  "subject":  { "type": "Person", "id": "linus" },
  "resource": { "type": "Server",    "id": "gpu-node-7" },
  "context":  { "input_params": { "max_price": 120000 } }
}

仅当候选策略的条件引用 $name 部分参数时，才包含 context.input_params；每个键都不要带前导 $，并使用正确的类型（数字应保持为数字）。对于复合 IKG 上按位置路由的 3.0-kbac 策略，也要在此处传入其逻辑位置（{ "region": "east" }，其中键需属于项目的 alias_mapping）；位置缺失或未知会返回 422，而身份与 subject 不同的用户令牌会返回 403——请参阅 references/search-action-reference.md。可直接使用的请求正文：assets/search-action-request.json。

3. 发送搜索请求

POST <API_URL>/access/v1/search/action

该端点会验证调用应用的身份（其 AppAgent 凭据始终必需），并可选地验证用户（访问令牌——仅在某些情况下适用；提供后可以缩小结果范围）。有关每种凭据应放入哪个请求标头，请参阅凭据指南。

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

4. 读取结果

{ "results": [ { "name": "DEPLOY" }, { "name": "REBOOT" }, { "name": "SNAPSHOT" } ] }

每个 results[] 条目都是主体当前可对该资源执行的操作。results 数组为空是正常的 200 响应，表示没有任何操作获准执行——这不是错误。

5. 验证

结果为空或出乎意料时，通常是因为策略并非 ACTIVE 或不匹配、subject.id/resource.id 不是节点的 external_id、缺少必需的 $param 或其类型错误、图数据缺失，或提供的用户令牌缩小了受声明限制的操作范围。完整检查清单：references/search-action-reference.md。

结果

成功应用此技能后：

• POST /access/v1/search/action 会返回一个 results 数组，其中包含主体在当前 ACTIVE 策略和图状态下可对特定资源执行的操作（空数组表示没有任何操作获准执行——这是正常的 200 响应）。
• 返回的操作与通过 indykite-authzen-kbac-policies 编写的 KBAC 策略中的 actions 一致。

此技能中的文件

• references/search-action-reference.md - 端点、身份验证、请求/响应结构、错误代码、故障排除和相关端点。
• assets/search-action-request.json - 适用于 linus / gpu-node-7 示例的可运行操作搜索请求正文。
• scripts/search-action.sh - Bash 辅助脚本，用于向 /access/v1/search/action 发送搜索请求（固定主机；使用 --print 预览）。

针对 Agent 的说明

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

参考资料

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