indykite-authzen-search-resource

IndyKite AuthZEN - 资源搜索

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

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

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

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

适用场景

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

• 列出主体在某个操作下可以操作的某类型的所有资源（例如“linus 可以 PROVISION 哪些服务器？”、“此用户可以读取哪些文档？”）；
• 构建一个列表或信息流，并筛选出用户有权操作的项目；
• 排查某个预期资源为何存在或不存在于主体的获准资源集合中。

对于单个是/否判定（indykite-authzen-evaluation）、枚举操作或主体（对应的其他搜索技能），或编写策略、读取/写入图数据（搜索只会列出资源），请勿启用此技能。

前提条件

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

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

步骤

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

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

部分	字段	示例
主体	subject.type + subject.id	Person / linus
操作	action.name	PROVISION
资源	仅 resource.type	Server（不含 id）

请勿设置 resource.id——搜索返回的就是这些实例。

2. 构建请求正文

{
  "subject":  { "type": "Person", "id": "linus" },
  "resource": { "type": "Server" },
  "action":   { "name": "PROVISION" },
  "context":  { "input_params": { "max_price": 4000 } }
}

仅当候选策略引用了 $name 局部参数时，才包含 context.input_params；每个键都应不带 $，并使用正确的类型。对于复合 IKG 上按位置路由的 3.0-kbac 策略，也要在此处提供逻辑位置（{ "region": "east" }，这是项目 alias_mapping 中的一个键）；只能返回存储在该位置的资源。位置缺失或未知时会返回 422，而用户令牌对应的身份与 subject 不同时会返回 403——请参阅 references/search-resource-reference.md。可直接使用的请求正文：assets/search-resource-request.json。

3. 发送搜索请求

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

此端点会对调用应用进行身份验证（其 AppAgent 凭据始终必需），并可选地对用户进行身份验证（访问令牌仅在某些情况下适用；提供令牌时可以缩小结果范围）。关于各凭据应放在哪个请求标头中，请参阅凭据指南。

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

4. 查看结果

{ "results": [ { "type": "Server", "id": "edge-box-2" } ] }

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

5. 验证

结果为空或出乎意料，通常是以下原因导致：意外设置了 resource.id（此处只使用 resource.type）、action 与策略不匹配、subject.id 不是 external_id、缺少 $param 或其类型错误（收紧 max_price 会缩小结果集），或者资源节点不存在。完整检查清单：references/search-resource-reference.md。

结果

成功应用此技能后：

• POST /access/v1/search/resource 会返回一个 results 数组，其中包含主体在当前 ACTIVE 策略和图状态下可以对其执行给定操作的资源实例（type + id）。空数组表示不允许操作该类型的任何资源——这是正常的 200 响应。
• 返回的资源与同一组三元组对应的单次决策（/access/v1/evaluation）结果一致。

此技能中的文件

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

Agent 专属说明

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

参考资料

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