indykite-authzen-search-subject

IndyKite AuthZEN - 件名検索

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

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

エンドポイント	固定する要素	列挙する要素	スキル
/search/action	件名 + リソース	アクション	indykite-authzen-search-action
/search/resource	件名 + アクション	リソース	indykite-authzen-search-resource
/search/subject	リソース + アクション	件名	このスキル

このスキルでは、リクエストの作成と送信、および結果の読み取りについて説明します。ポリシーの作成は行いません。これらの結果の評価対象となる 2.0-kbac および 3.0-kbac ポリシーは、indykite-authzen-kbac-policies を使って作成します。

使用するタイミング

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

• 特定のリソースに対してアクションを実行できる、あるタイプのすべての件名を一覧表示する（例：「gpu-node-7 に DEPLOY できる人は？」「このドキュメントを承認できる人は？」）。
• アイテムに現在アクセスできる人を確認するための監査ビューやレビュアービューを作成する。
• 期待した件名がリソースの許可対象に含まれている、または含まれていない理由を調査する。

単一の 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.type のみ	Person（id なし）
アクション	action.name	PROVISION
リソース	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 の認証情報。常に必須です）を認証します。ユーザーアクセストークンも受け付けますが、サブジェクト検索では通常、結果セットに影響しません（サブジェクトとして操作するのではなく、サブジェクトを列挙するためです）。各リクエストヘッダーにどの認証情報を指定するかについては、Credentials ガイドで説明しています。

認証済みリクエストを作成する、実行可能なシェルヘルパーは 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 は、現在の ACTIVE ポリシーとグラフの状態に基づき、特定のリソースに対する所定のアクションが許可されたサブジェクトインスタンス（type + id）の results 配列を返します（配列が空の場合は、そのタイプのサブジェクトが許可されていないことを意味する正常な 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 でプレビューできます）。

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

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

参考資料

• AuthZEN ガイド（開発者ハブ）
• Config API ドキュメント - 認可ポリシー
• Credentials ガイド