indykite-authzen-search-action

IndyKite AuthZEN - アクション検索

アクション検索では、AuthZEN エンドポイントに「このサブジェクトはこのリソースに対して、どのアクションを実行できますか？」と問い合わせます。プロジェクトで現在 ACTIVE な KBAC ポリシーと現在のグラフの状態に基づき、許可されたアクション名のリストを返します。単一の真偽値を返すものではありません。

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

エンドポイント	固定する要素	列挙する要素	スキル
/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) の組み合わせで、想定したアクションが許可される、または許可されない理由を調べる。

単一の yes/no 判定（indykite-authzen-evaluation）、リソースまたはサブジェクトの列挙（関連する検索スキル）、複数の判定の一括実行（indykite-authzen-evaluations）、ポリシーの作成、またはグラフデータの読み書き（検索で列挙するのはアクションのみ）には、このスキルを有効にしないでください。

前提条件

• 問い合わせる組み合わせに対して、subject.type / resource.type が一致する ACTIVE な KBAC ポリシーが 1 つ以上あること。存在しない場合は、まず indykite-authzen-kbac-policies で作成してください。ポリシーセットが空の状態で検索すると、{"results": []} が返されます。
• 呼び出し元のアプリケーション用に認証情報が設定された AppAgent (認証情報ガイド)。
• サブジェクトとリソースのノード（およびポリシー条件に一致する関係）が IKG に登録されていること。検索ではグラフを評価しますが、グラフにデータを投入することはありません。
• 候補となるポリシーが参照する 部分パラメーターを、context.input_params で渡せる状態にしておくこと。

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

手順

1. サブジェクトとリソースを指定する

アクション検索では、サブジェクトとリソースの両方を固定し、その間で許可される操作を問い合わせます。それぞれのノードの 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 と異なる ID のユーザー用トークンを指定すると 403 になります。詳しくは references/search-action-reference.md をご覧ください。すぐに使える本文の例：assets/search-action-request.json。

3. 検索を送信する

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

エンドポイントは呼び出し元アプリケーション（AppAgent の認証情報。常に必須）を認証し、必要に応じてユーザー（アクセストークン。一部のケースでのみ適用され、指定すると結果を絞り込めます）も認証します。どの認証情報をどのリクエストヘッダーに指定するかについては、Credentials guide をご覧ください。

実行可能なシェルヘルパーで、認証済みリクエストを作成できます：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 は、現在の ACTIVE ポリシーとグラフの状態に基づき、特定のリソースに対してサブジェクトが実行できるアクションの results 配列を返します（空の配列は何も許可されていないことを意味する正常な 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 - /access/v1/search/action に検索リクエストを送信する Bash ヘルパー（ホスト固定。--print を付けるとプレビューできます）。

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

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

参考資料

• AuthZEN guide（開発者ハブ）
• Config API documentation - authorization policies
• Credentials guide