indykite-authzen-search-resource

IndyKite AuthZEN - リソース検索

リソース検索では、AuthZEN エンドポイントに「このサブジェクトが特定のアクションを実行できるリソースはどれか」と問い合わせます。1つのサブジェクト、1つのアクション、リソースのタイプを指定すると、プロジェクトで現在 ACTIVE な KBAC ポリシーと現在のグラフ状態に基づいて、一致するリソースインスタンスが返されます。

これは3つある AuthZEN 検索エンドポイントの1つです。それぞれ、(subject, action, resource) の3要素のうち2つを固定し、残りの1つを列挙します。

エンドポイント	固定する要素	列挙する要素	スキル
/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 を使って作成します。

使用する場面

次のような要望がある場合に、このスキルを有効にしてください。

• 1つのアクションについて、サブジェクトが操作できる特定のタイプのすべてのリソースを一覧表示する（例：「linus が PROVISION できるサーバーはどれですか？」「このユーザーが読み取れるドキュメントはどれですか？」）。
• ユーザーが操作を許可されている項目だけに絞ったリストやフィードを作成する。
• 予想したリソースがサブジェクトの許可されたリソースの集合に含まれている、または含まれていない理由を調査する。

単一の yes/no 判定にはこのスキルを有効にしないでください（indykite-authzen-evaluation を使用してください）。アクションやサブジェクトを列挙する場合は、代わりに関連する検索スキルを使用してください。また、ポリシーの作成やグラフデータの読み書きにも使用しないでください（検索ではリソースの一覧表示のみができます）。

前提条件

• 質問に対応する subject.type、resource.type、および actions を含む、1つ以上の ACTIVE KBAC ポリシー。該当するポリシーがない場合は、まず indykite-authzen-kbac-policies を使って作成してください。ポリシーセットが空の状態で検索すると、{"results": []} が返されます。
• 呼び出し元アプリケーション用の認証情報が設定された AppAgent（認証情報ガイド）。
• サブジェクトノードと候補となるリソースノード（およびポリシー条件に一致する関係）が設定された IKG。
• 候補となるポリシーが参照するすべての部分パラメーター。context.input_params に渡せる状態にしておいてください。

前提条件が不足している場合は、その旨を伝えてください。ポリシーがない場合やノードが存在しない場合の空の結果セットは、「許可されたものがない」という実際の結果と見分けがつきません。

手順

1. サブジェクトとアクションを固定し、リソースはタイプで指定する

リソース検索では、サブジェクトとアクションを固定し、指定したタイプのリソースを検索します。

要素	フィールド	例
subject	subject.type + subject.id	Person / linus
action	action.name	PROVISION
resource	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 と異なる ID のユーザーのトークンを指定した場合は 403 になります。詳しくは references/search-resource-reference.md を参照してください。準備済みの本文はこちらです：assets/search-resource-request.json。

3. 検索を送信する

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

エンドポイントは、呼び出し元のアプリケーション（AppAgent の認証情報。常に必須）を認証し、任意でユーザーも認証します（アクセストークン。特定の場合にのみ適用され、指定すると結果を絞り込めることがあります）。各リクエストヘッダーにどの認証情報を指定するかについては、Credentials guide を参照してください。

実行可能なシェルヘルパーで、認証済みリクエストを作成できます：scripts/search-resource.sh。--print を指定すると、curl をプレビューできます（ホスト固定、トークンはマスキングされます）。

4. 結果を確認する

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

各 results[] エントリは、subject がアクションを実行できるリソース（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 は、現在の ACTIVE ポリシーとグラフの状態に基づき、subject が指定されたアクションを実行できるリソースインスタンス（type + id）の results 配列を返します（配列が空の場合は該当するタイプのリソースに許可がないことを示す通常の 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 でプレビュー）。

エージェント固有の注意事項

このスキルは汎用的な Markdown 指示を使用しており、README に記載されているすべてのエージェントで動作します。エージェントは HTTP リクエストを送信できる必要があります（curl、HTTP クライアント、または IndyKite Terraform provider）。Claude Code のフック、Cursor の @ メンション、Copilot のワークスペースコンテキストは必要ありません。

参考資料

• AuthZEN ガイド（開発者ハブ）
• Config API ドキュメント - authorization policies
• Credentials guide