indykite-authzen-evaluations

IndyKite AuthZEN - 一括評価

一括評価では、1 回のリクエストで多数の KBAC 判定を行います。トップレベルの subject ／ action ／ resource ／ context をデフォルト値として指定し、各エントリーで指定した部分だけを上書きする evaluations[] 配列を渡します。レスポンスには、エントリーごとに順番に 1 つの真偽値 decision が含まれます。

このスキルでは、一括リクエストの作成と送信、結果の確認方法を説明します。ポリシーの作成は対象外です。各エントリーの評価に使用される 2.0-kbac と 3.0-kbac のポリシーは、indykite-authzen-kbac-policies を使って作成します。

使用する場面

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

• 1 つのサブジェクトに対して複数のリソースを確認する（例：「この 20 台のサーバーのうち、grace が PROVISION できるのはどれですか？」）。
• 複数のサブジェクトに対して 1 つのアクションを確認する（例：「この人たちのうち、gpu-node-7 をデプロイできるのは誰ですか？」）。
• (subject, action, resource) の異なる組み合わせを、1 回の呼び出しで評価する。

単一の可否判定にはこのスキルを有効にしないでください（indykite-authzen-evaluation）。1 つの対象についてすべてのインスタンスを列挙する場合も対象外です（検索スキルの indykite-authzen-search-action ／ -search-resource ／ -search-subject を使用してください）。また、ポリシーの作成やグラフデータの読み書きにも使用しないでください（一括評価で行うのは判定の提示のみです）。

前提条件

• バッチ内の組み合わせを対象とする ACTIVE KBAC ポリシーが 1 つ以上あること。ポリシーがない場合は、先に indykite-authzen-kbac-policies を使って作成してください。
• AppAgent とその認証情報トークン（X-IK-ClientKey の値）。
• サブジェクトとリソースのノード（および条件に一致する関係）が IKG に登録されていること。
• 一致するポリシーが参照するすべての部分パラメーターを、context.input_params で渡せる状態にしておくこと。

手順

1. デフォルト値を選び、エントリーごとに変える

バッチ全体で共通する部分（トップレベルに指定）と、変化する部分（各 evaluations[] エントリーに指定）を決めます。エントリーで上書きしないトップレベルの部分はすべて、そのエントリーに引き継がれます。

実行例：1 つのアクション（PROVISION）と 1 つのリソース（gpu-node-7）をデフォルト値にします。サブジェクトはエントリーごとに変わり、1 つのエントリーではリソースも上書きします。

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

{
  "action":   { "name": "PROVISION" },
  "resource": { "type": "Server", "id": "gpu-node-7" },
  "evaluations": [
    { "subject": { "type": "Person", "id": "linus" } },
    { "subject": { "type": "Person", "id": "grace" } },
    { "subject": { "type": "Person", "id": "grace" }, "resource": { "type": "Server", "id": "edge-box-2" } },
    { "subject": { "type": "Person", "id": "dennis" } }
  ],
  "context": { "input_params": { "max_price": 80000 } }
}

subject.id ／ resource.id はノードの external_id、action.name は大文字と小文字を区別します。context.input_params のキーには $ を付けず、値の型は維持してください。複合 IKG 上のロケーションルーティングされた 3.0-kbac ポリシーでは、各エントリーまたはデフォルト値として、プロジェクトの alias_mapping のキーである論理ロケーション（{ "region": "east" }）を同様に指定します。詳しくは references/evaluations-reference.md を参照してください。すぐに使える本文はこちらです：assets/evaluations-provision-servers.json。

3. 一括リクエストを送信する

POST <API_URL>/access/v1/evaluations

認証：

• 必須：X-IK-ClientKey: <AppAgent-credentials-token>。
• 任意：Authorization: Bearer <user-access-token>。一部のケース（条件がトークンクレーム／スコープを参照する場合など）にのみ適用され、クレームで制御されるエントリーの判定を変えることがあります。

実行可能なシェルヘルパーは scripts/evaluate-batch.sh です。--print を指定して実行すると、curl をプレビューできます（ホストは固定され、トークンは伏せ字になります）。

4. 判定を確認する - エントリーごとに順番に 1 つずつ

{
  "evaluations": [
    { "decision": false },
    { "decision": true },
    { "decision": false },
    { "decision": true }
  ]
}

配列の位置が対応します。evaluations[i] は、リクエストの i 番目のエントリーに対する判定です。

5. パラメーター欠落時の違いに注意する

必須の部分パラメーターを省略した 単一の /evaluation は 422 を返します。一方、バッチ呼び出しは全体として失敗せず、200 を返します。マッチしたポリシーが欠落したパラメーターを必要とする各エントリーは、decision: false と context.reason を返します。

{ "decision": false, "context": { "reason": "invalid_argument: missing or wrong input params, 'max_price'" } }

そのため、アクセスが拒否されたと結論づける前に、実際の拒否（decision: false、context なし）と、入力不足による拒否（decision: false かつ context.reason あり）を必ず区別してください。

結果

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

• POST /access/v1/evaluations は evaluations[] 配列を返します。配列にはリクエストエントリーごとの decision がリクエスト順に含まれ、トップレベルの要素がデフォルトとして正しく適用されます。
• パラメーターが欠落したエントリーは decision: false + context.reason（200）として読み取られ、リクエスト失敗とは誤認されません。
• 各バッチ判定は、同じトリプルに対して単一判定スキル（indykite-authzen-evaluation）が返す結果と一致します。

このスキルのファイル

• references/evaluations-reference.md - /evaluations：リクエスト／レスポンスの形式、デフォルトとオーバーライドのセマンティクス、パラメーター欠落時の動作、エラーコード。
• assets/evaluations-provision-servers.json - PROVISION の例で使用できる、実行可能なバッチリクエスト本文。
• scripts/evaluate-batch.sh - /access/v1/evaluations にバッチリクエストを送信する Bash ヘルパー（ホスト固定。プレビューするには --print を指定します）。

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

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

参考資料

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