indykite-authzen-kbac

IndyKite KBAC - 認可ポリシー

KBAC（Knowledge-Based Access Control）は、IndyKite のグラフ駆動型認可モデルです。KBAC ポリシーでは、条件として指定された Cypher（Neo4j／openCypher のグラフクエリー言語）を IKG（IndyKite のナレッジグラフであるプロパティグラフデータベース）に対して評価し、誰（subject）が、どの操作（actions）を、何（resource）に対して実行できるかを宣言します。ポリシー自体は判定を生成しません。判定または検索が要求されたときに、AuthZEN エンドポイントが参照するルールです。

このスキルでは、KBAC ポリシーのライフサイクルを扱います。ポリシー JSON の作成と、Config API を使った管理が対象です。

• meta.policy_version: "2.0-kbac"、単一の subject.type、actions リスト、単一の resource.type、および予約変数 subject と resource をバインドする condition.cypher を持つポリシー。
• /configs/v1/authorization-policies に対する Config API の操作：作成（POST）、読み取り（GET /{id} または名前による取得）、一覧表示（GET ?project_id=…&type=kbac）、更新（If-Match ETag を指定した PUT /{id}）、削除（DELETE /{id}）。
• 公開：判定に参加するにはポリシーが ACTIVE である必要があります。INACTIVE または DRAFT のポリシーは保存されますが、無視されます（DRAFT は無効な場合もあります）。

ポリシーが ACTIVE になると、ランタイムの AuthZEN スキルによって評価されます。

必要なこと	エンドポイント	スキル
1 件の可否判定	/access/v1/evaluation	indykite-authzen-evaluation
複数の判定を一度に実行	/access/v1/evaluations	indykite-authzen-evaluations
リソースに対して subject が実行できるアクション	/access/v1/search/action	indykite-authzen-search-action
指定したアクションにおいて subject が操作できるリソース	/access/v1/search/resource	indykite-authzen-search-resource
リソースに対するアクションを許可された subject	/access/v1/search/subject	indykite-authzen-search-subject

使用するタイミング

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

• KBAC 認可ポリシー（policy_version: 2.0-kbac、subject、actions、resource、condition.cypher）を作成する。
• Config API を通じてポリシーを作成／公開する、または DRAFT と ACTIVE を切り替える。
• 既存の KBAC ポリシーを読み取り、一覧表示、更新、削除する（CIQ ポリシーと区別するために ?type=kbac を指定した一覧表示も含む）。
• indykite-authzen-evaluation の判定または indykite-mcp-server の authzen_evaluate ツールを支えるポリシーが必要である。

ユーザーが次のことを望んでいる場合は、このスキルを有効にしないでください。

• 判定を行う（1 件または複数のトリプル）場合は、indykite-authzen-evaluation／indykite-authzen-evaluations を使用します。
• 許可されたアクション、リソース、または subject を列挙する場合は、検索スキル -search-action／-search-resource／-search-subject を使用します。
• ContX IQ の読み取り／書き込みポリシーを作成する場合（同じ /configs/v1/authorization-policies エンドポイントが CIQ にも使われ、type=ciq で区別されます）は、indykite-ciq-* スキルを使用します。
• グラフデータを作成／更新／削除する場合は使用しません。KBAC ポリシーはグラフに対するルールであり、グラフへの書き込みではありません。

前提条件

• IndyKite プロジェクトと、PROJECT_GID に設定するプロジェクトの GID（ポリシーの project_id になります）。
• SERVICE_ACCOUNT_TOKEN に設定する、Config API の書き込みアクセス権を持つ サービスアカウントトークン（すべての /configs/v1/authorization-policies 呼び出しで使用します）。
• ポリシーの サブジェクトタイプ（リクエストを行うノードタイプ。Person、Service、Namespace など）。ポリシーで指定できるサブジェクトタイプは 1 つだけです。同じアクションに 2 つのサブジェクトタイプが必要な場合は、ポリシーを 2 つ作成してください。
• 条件が照合する IKG モデル（ノードタイプ、プロパティ、リレーションシップ）。データが存在する前にポリシーを作成できますが、空のグラフに対する判定は単に false になります。

これらのいずれかが不足している場合は、JSON を書く前にその旨を伝えてください。

手順

1. ルールを（サブジェクト、アクション、リソース、条件）として整理する

KBAC ポリシーは、特定の形式の質問に答えます。JSON を書く前に、次の 4 つの要素をすべて明確にしてください。

要素	内容	例
subject	リクエストを行う単一のノードタイプ。	Person
actions	ポリシーで許可する 1 つ以上の大文字の動詞。	["PROVISION"]
resource	操作対象となる単一のノードタイプ。	Server
condition	判定が true となるために満たす必要がある Cypher パターン + WHERE。	予算内の価格

このスキル全体で使用する例：

Person（サブジェクト）は、評価時に指定された予算内にサーバーの価格が収まる場合、Server（リソース）を PROVISION できます。

2. Cypher 条件を書く

条件は単一の cypher 文字列です。次の 2 つの重要なルールがあります。

• subject.type に一致する、文字どおり subject という名前の変数と、resource.type に一致する、文字どおり resource という名前の変数をバインドする必要があります。判定時には、AuthZEN リクエストの subject.id / resource.id が、各ノードの external_id と照合されます。
• リクエストごとに変わる値は、WHERE 句に $name と記述する部分パラメーターです。判定呼び出しでは context.input_params の下で（$ を付けずに）値を指定します。ここでは、予算を $max_price とします。

MATCH (subject:Person), (resource:Server)
WHERE resource.property.price <= $max_price

リレーションシップに基づくルールでは、プロパティのチェックの代わりに、またはそれに加えてリレーションシップをマッチさせます。

MATCH (subject:Person)-[:CAN_AFFORD]->(resource:Server)

条件の文法全体（属性参照、複数ホップのパターン、部分パラメーター）については、references/policy-reference.md を参照してください。

3. ポリシーと作成用エンベロープを組み立てる

KBAC ポリシーのトップレベルキーは、meta.policy_version（"2.0-kbac"）、subject.type、actions、resource.type、condition.cypher のちょうど 5 つです。

Config API はポリシーオブジェクトを直接受け取らず、ポリシーを JSON 文字列化した値として含む作成用エンベロープを受け取ります。

{
  "name": "kbac-person-provision-server",
  "display_name": "Person: PROVISION a Server within budget",
  "description": "Allow a Person to PROVISION a Server when its price is within a budget supplied at evaluation time.",
  "project_id": "<project-gid>",
  "policy": "{ \"meta\": { \"policy_version\": \"2.0-kbac\" }, … }",
  "status": "ACTIVE"
}

読みやすさのため、アセット assets/policy-provision-server.json では policy をオブジェクトとして、project_id をプレースホルダーとして保持しています。作成手順では、送信の直前に project_id を設定し、policy を文字列化します。

4. ポリシーを作成する

POST <API_URL>/configs/v1/authorization-policies

サービスアカウントトークンで認証します。Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>。

# set project_id and stringify only the `policy` field, then POST
jq --arg pid "$PROJECT_GID" '.project_id = $pid | .policy |= tojson' assets/policy-provision-server.json \
  | curl -X POST "$API_URL/configs/v1/authorization-policies" \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SERVICE_ACCOUNT_TOKEN" \
      -d @-

または、ヘルパー scripts/create-policy.sh を使用できます。このヘルパーは project_id を設定し、policy フィールドを文字列化し、IndyKite のホストを固定して、--print の出力ではトークンを伏せ字にします。

201 Created が返ると、ポリシーの id（gid:…）、監査フィールド（create_time、created_by、…）、および ETag ヘッダーが返されます。更新と削除に必要なため、id と ETag を保管してください。ポリシーは status が ACTIVE の場合にのみ判定に使用されます。

5. 読み取り、一覧表示、更新、削除

同じ /configs/v1/authorization-policies パスでポリシーのライフサイクルを管理します（すべてサービスアカウントトークンを使用します）。

• IDで読み取り：GET /configs/v1/authorization-policies/{id} — 文字列化された policy、status、tags、監査フィールド、現在の ETag を含む完全なレコードを返します。
• 名前で読み取り：GET /configs/v1/authorization-policies/{name}?location={PROJECT_GID}。
• KBAC ポリシーの一覧表示：GET /configs/v1/authorization-policies?project_id={PROJECT_GID}&type=kbac — type=kbac は KBAC ポリシーのみを返します（ContX IQ の場合は type=ciq を使用します）。一覧の各項目では policy が空文字列で返されます。本文を取得するには ID で読み取ります。
• 更新：ヘッダー If-Match: <etag> と、変更するフィールド（display_name、description、policy、status、tags）を含む本文を指定して PUT /configs/v1/authorization-policies/{id} を実行します。これを使って公開（status: "ACTIVE"）、無効化（status: "INACTIVE"）、DRAFT として保持、または条件の改訂を行います。新しい ETag が返されます。
• 削除：ヘッダー If-Match: <etag> を指定して DELETE /configs/v1/authorization-policies/{id} を実行します。

リクエスト／レスポンスの完全な形式、レスポンスフィールド、ETag の同時実行ルールについては、references/policy-reference.md を参照してください。

成果

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

• プロジェクトに、policy_version: "2.0-kbac"、単一の subject.type、actions リスト、単一の resource.type、および subject と resource を結び付ける condition.cypher を含む KBAC ポリシーが存在します。
• ポリシーは ACTIVE（または意図的に INACTIVE／DRAFT）で、その id と現在の ETag が把握されているため、読み取り、更新、削除が可能です。
• ?type=kbac で一覧表示するとポリシーが表示され、一致する (subject, action, resource) の組に対する indykite-authzen-evaluation の判定に反映されます。

このスキル内のファイル

• references/policy-reference.md — KBAC ポリシーのスキーマ（meta、subject、actions、resource、condition.cypher、部分パラメーター、複数アクションおよびリレーションシップのバリエーション）と Config API のライフサイクル（作成／読み取り／?type=kbac での一覧表示／更新／削除、ETag による同時実行制御、レスポンスフィールド）。
• assets/policy-provision-server.json — Person PROVISION Server の例で使用できる、実行可能な KBAC ポリシー作成エンベロープ。
• scripts/create-policy.sh — project_id を設定し、policy を文字列化して、作成エンベロープを /configs/v1/authorization-policies に POST する Bash ヘルパー（ホスト固定。プレビューには --print を使用）。

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

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

参考資料

• AuthZEN ガイド（開発者ハブ）
• ナレッジグラフによる動的認可（開発者ハブ）
• Config API ドキュメント — 認可ポリシー
• Cypher クエリ言語マニュアル（Neo4j、openCypher） — IndyKite ナレッジグラフに対する KBAC ポリシーの条件で使用されるグラフクエリ言語です。
• 音楽データセットのチュートリアル（KBAC ポリシーと AuthZEN の実例）
• KBAC レシピ（開発者ハブのリソース）
• IndyKite Terraform プロバイダー — indykite_authorization_policy
• 認証情報ガイド