indykite-authzen-evaluation

IndyKite AuthZEN - 単一の認可判定

KBAC 判定では、AuthZEN エンドポイントに「このサブジェクトは、このリソースに対してこのアクションを実行できますか？」という 1 つの質問を送り、ブール値の decision を受け取ります。判定は、IKG に対してプロジェクトで現在 ACTIVE な 2.0-kbac ポリシーを評価して行われます。

このスキルでは、リクエスト (subject, action, resource, context) の組み立て、送信、ブール値の読み取りという、単一の判定を扱います。ポリシーの作成は扱いません。判定の評価対象となる subject／actions／resource／condition.cypher を持つポリシーは、indykite-authzen-kbac-policies を使って作成します。

AuthZEN ファミリーのうち、単一呼び出しを扱うスキルです。

必要な処理	エンドポイント	スキル
1 つの可否判定	/access/v1/evaluation	このスキル
複数の判定を一度に行う	/access/v1/evaluations	indykite-authzen-evaluations
サブジェクトがリソースに対して実行できるアクション	/access/v1/search/action	indykite-authzen-search-action
アクションを指定して、サブジェクトが操作できるリソース	/access/v1/search/resource	indykite-authzen-search-resource
リソースに対するアクションを許可されたサブジェクト	/access/v1/search/subject	indykite-authzen-search-subject
KBAC ポリシーの作成／管理	Config API	indykite-authzen-kbac-policies

使用する場面

ユーザーが次のことを求めている場合に、このスキルを有効にします。

• 1 つのサブジェクトが、1 つのリソースに対して 1 つのアクションを実行できるかを判定する（例：「予算 120000 の範囲内で、ada はサーバー gpu-node-7 に PROVISION を実行できますか？」）。
• アプリケーションの操作を、リアルタイムの認可チェックに基づいて制御する。
• 単一の判定が true または false になる理由を調査する。

判定を行うポリシーを作成または変更する場合（indykite-authzen-kbac-policies）、1 回の呼び出しで複数の判定を行う場合（indykite-authzen-evaluations）、1 つの組み合わせをテストするのではなく、許可されたアクション／リソース／サブジェクトを列挙する場合（検索スキル -search-action／-search-resource／-search-subject）、またはグラフデータを返す／変更する場合（判定は可否を返すものであり、データの読み取りや書き込みではありません）には、このスキルを有効にしないでください。

前提条件

• 組み合わせに対応する subject.type／actions／resource.type を持つ、1 つ以上の ACTIVE KBAC ポリシー。該当するポリシーがない場合は、まず indykite-authzen-kbac-policies を使って作成してください。一致するポリシーがない判定は、単に false になります。
• 呼び出し元のアプリケーション用に認証情報を設定した AppAgent（Credentials ガイド）。
• サブジェクトとリソースのノード（および条件に一致する関係）が追加された IKG。評価ではグラフを読み取りますが、データの登録は行いません。
• 一致したポリシーが参照するすべての 部分パラメーター。context.input_params で渡せる状態にしておいてください。

前提条件が満たされていない場合は、その旨を伝えてください。先に解決するほうが、原因の分かりにくい false 判定をデバッグするよりもはるかに簡単です。

手順

1. トリプルとそのコンテキストを定義する

質問を構成する3つの要素と、リクエストごとの値を指定します。

要素	フィールド	例
サブジェクト	subject.type + subject.id	Person / ada
アクション	action.name	PROVISION
リソース	resource.type + resource.id	Server / gpu-node-7
コンテキスト	context.input_params	{ "max_price": 120000 }

subject.id / resource.id はノードの external_id です。action.name は大文字と小文字を区別します。

2. リクエスト本文を作成する

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

一致したポリシーの条件が $name 部分パラメーターを参照する場合に限り、context.input_params を指定してください。各キーから先頭の $ を除き、型はそのまま維持します（数値は数値のままにします）。ロケーションでルーティングされる 3.0-kbac ポリシー（複合 IKG で USE graph.byName($region) を使用）の場合も、同じ方法で論理ロケーションを指定します（{ "region": "east" }）。これはプロジェクトの alias_mapping のキーであり、データベース名ではありません。ロケーションが指定されていない、または不明な場合は 422、subject とは異なる ID のユーザートークンを指定した場合は 403 になります（references/evaluation-reference.md を参照してください）。すぐに使用できる本文はこちらです：assets/evaluation-provision-server.json。

3. 判定リクエストを送信する

POST <API_URL>/access/v1/evaluation

エンドポイントでは、呼び出し元のアプリケーション（AppAgent の認証情報。常に必須）を認証し、任意でユーザー（アクセストークン。トークンのクレーム／スコープを条件が参照する場合など、一部のケースでのみ適用）を認証します。各リクエストヘッダーにどの認証情報を指定するかについては、認証情報ガイドを参照してください。

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

4. 判定を確認する

{ "decision": true }

true は、ACTIVE なポリシーが少なくとも1つ、条件を満たした (subject, action, resource) トリプルを許可したことを意味します。false は、許可したポリシーがないことを意味します。トリプルに一致するポリシーがないか、一致したポリシーの条件が、指定した input_params とグラフデータに対して成立しなかったかのいずれかです。false の判定は通常の 200 であり、エラーではありません。

5. 検証する

判定が期待どおりでない場合は、変更を加える前に次のチェックリストを確認してください。

1. ポリシーは ACTIVE ですか？ 下書き／非アクティブなポリシーは無視されます。
2. トリプルは一致していますか？ subject.type、action.name、resource.type は、ポリシーの subject.type、actions、resource.type と完全に一致する必要があります（動詞は大文字と小文字を区別します）。
3. 変数名は subject / resource ですか？ 条件がリクエストの subject/resource をバインドするのは、これらの予約名を通じてのみです。
4. ID は external_id ですか？ subject.id / resource.id は、ノードの external_id と照合されます。ID が間違っていると一致するものがなく、通知なしで false になります。
5. すべての $param が指定されていますか？ 条件で必要な input_params のキーが不足していると、通知なしで false になるのではなく、422 が返されます（errors: ["missing or wrong input params, '<name>'"]）。
6. データは実際に IKG にありますか？ subject ノード、resource ノード、および一致する関係が存在することを確認してください。

リクエスト／レスポンスの完全なスキーマ、エラー一覧、および詳しいトラブルシューティング手順については、references/evaluation-reference.md と references/troubleshooting.md を参照してください。

成果

このスキルが正常に適用されると、次の状態になります。

• 許可された (subject, action, resource) の組み合わせと有効な input_params に対して、POST /access/v1/evaluation は {"decision": true} を返し、拒否された組み合わせに対しては {"decision": false} を返します。
• 必須の input_params キーが欠落している場合は、拒否と誤認せずに 422 が返され、修正されます。
• 同じ組み合わせを indykite-authzen-evaluations 経由で複数に展開することも、indykite-mcp-server の authzen_evaluate ツール経由で呼び出すこともでき、いずれも同じ判定セマンティクスを使用します。

このスキルのファイル

• references/evaluation-reference.md - /evaluation エンドポイント：ベースパス、認証、リクエスト／レスポンスの形式、エラーコード、バッチおよび検索用の関連スキルへのリンク。
• references/troubleshooting.md - 判定が予期せず true／false になる原因と、該当するポリシーを特定する方法。
• assets/evaluation-provision-server.json - Person PROVISION Server の例で使える、実行可能な単一評価リクエストボディ。
• scripts/evaluate.sh - /access/v1/evaluation に判定リクエストを送信する Bash ヘルパー（ホスト固定。プレビューするには --print を指定）。

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

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

参考資料

• AuthZEN ガイド（開発者ハブ）
• ナレッジグラフを使った動的認可（開発者ハブ）
• KBAC：AuthZEN API を使った関係ベースの認可
• KBAC：入力パラメーターを使ったパラメーター化認可（max_price）
• 音楽データセットのチュートリアル（KBAC と AuthZEN の実例）
• 認証情報ガイド