indykite-authzen-search-subject

IndyKite AuthZEN - 主体搜索

主体搜索会向 AuthZEN 端点询问：哪些主体可以对该资源执行指定操作？ 给定一个主体类型、一个资源和一个操作，它会根据项目当前处于 ACTIVE 状态的 KBAC 策略和当前图状态，返回匹配的主体实例。

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

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

此技能介绍如何构建并发送请求，以及如何读取结果。它不会编写策略——用于评估这些结果的 2.0-kbac 和 3.0-kbac 策略是通过 indykite-authzen-kbac-policies 编写的。

使用时机

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

• 列出所有可以对特定资源执行某项操作的指定类型主体（例如：“谁可以对 gpu-node-7 执行 DEPLOY？”、“谁可以批准此文档？”）；
• 构建审计视图或审核者视图，查看当前有哪些人可以访问某个项目；
• 调试某个预期主体为何在或不在某资源的许可主体集合中。

对于单个是/否决策（indykite-authzen-evaluation）、枚举操作或资源（请改用同级搜索技能），或编写策略或读取/写入图数据（搜索仅列出主体），请勿启用此技能。

前提条件

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

如果缺少某项前提条件，请明确说明——缺少策略或节点时返回的空结果集，看起来与真实的“没有任何许可”完全相同。

步骤

1. 固定资源和操作；主体仅指定类型

主体搜索固定资源和操作，并搜索指定类型的主体：

部分	字段	示例
subject	仅 subject.type	Person（不含 id）
action	action.name	PROVISION
resource	resource.type + resource.id	Server / gpu-node-7

不要设置 subject.id——主体正是搜索要返回的内容。

2. 构建请求正文

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

仅当候选策略引用 $name 部分参数时，才包含 context.input_params；提供每个键时不要带 $，并确保类型正确。对于复合 IKG 上按位置路由的 3.0-kbac 策略，也要在此处传入逻辑位置（{ "region": "east" }，这是项目 alias_mapping 中的一个键）；只能返回存储在该位置的主体，若位置缺失或未知，则返回 422——参见 references/search-subject-reference.md。可直接使用的请求正文：assets/search-subject-request.json。

3. 发送搜索请求

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

该端点会对调用应用进行身份验证（其 AppAgent 凭据始终必需）。也接受用户访问令牌，但对于主体搜索，它通常不会影响结果集（你是在枚举主体，而不是以某个主体的身份执行操作）。有关各凭据应放入哪个请求标头，请参阅凭据指南。

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

4. 读取结果

{ "results": [ { "type": "Person", "id": "grace" }, { "type": "Person", "id": "dennis" } ] }

每个 results[] 条目都是一个主体（type + id，即 external_id），该主体获准对该资源执行相应操作。results 数组为空是正常的 200 响应，表示没有该类型的主体获得许可——这不是错误。

5. 验证

结果为空或出乎意料时，通常是以下原因：误将 subject.id 设为某个值（这里只使用 subject.type）、resource.id 不是 external_id、action 与策略不匹配、缺少 $param 或其类型错误（放宽 max_price 会扩大结果集），或主体节点不存在。完整检查清单：references/search-subject-reference.md。

结果

成功应用此技能后：

• POST /access/v1/search/subject 会返回一个 results 数组，其中包含获准对特定资源执行指定操作的主体实例（type + id）；结果基于当前 ACTIVE 策略和图状态（空数组表示没有该类型的主体获准执行操作——这是正常的 200 响应）。
• 返回的主体与相同三元组对应的单次决策（/access/v1/evaluation）结果一致。

此技能中的文件

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

Agent 专属说明

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

参考资料

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