メインコンテンツまでスキップ

クイックスタート

このページでは、Ninka をインストールしてから、アプリケーションで最初の認可判定を行うところまでを一通り進めます。

サンプルの手形を確認し、コンパイルし、生成された Consumer Projection をアプリケーションから呼び出します。Ninka が何を担い、どこからが人間やアプリケーションの責任なのかを先に知りたい場合は、はじめに を参照してください。

1. インストールする​

npm install ninka-authz

Node.js 20 以降が必要です。生成される TypeScript の Consumer Projection が ninka-authz/runtime を import するため、ninka-authz はアプリケーション実行時にも必要な依存関係としてインストールします。

2. 初期ファイルを作る​

npx ninka-authz init

init は ninka/ ワークスペースを作成します。--bare を付けなければ、サンプルポリシーも作成します。手形が存在する場合は、そのままコンパイル工程も実行します。通常の TypeScript プロジェクトでは、Consumer Projection は既定で src/generated/ninka.ts に生成されます。

3. サンプルの手形を読む​

init によって ninka/invoice-access.tegata.json が作成されています。まずこのファイルを開いてください。これが人間がレビューする認可仕様であり、自分のポリシーを書くときも同じ形式を使います。

{
  "tegata": "0.1",
  "policy": { "id": "invoice-access", "description": "Invoice access" },
  "rules": [
    {
      "id": "allow-employee-view-invoice",
      "effect": "allow",
      "subject": { "roles": ["employee"] },
      "actions": ["view"],
      "resource": { "type": "invoice" }
    }
  ]
}

各ポリシーは通常 ninka/<policy-id>.tegata.json に置きます。文書全体の構造と評価規則は 手形スキーマ を参照してください。

init は ninka/vocabulary.json も作成します。ここには、サンプルポリシーで利用できる role・action・resource type などが宣言されています。新しい語や、語彙で管理する属性を追加するときは、このファイルも更新します。詳しくは 語彙 を参照してください。

4. コンパイルする​

npx ninka-authz compile

Ninka は手形を検査し、手形から導かれる Rego とメタデータを書き出します。OPA toolchain を利用できる場合は、実行用の WASM bundle も build します。その WASM に対して生成された validation を実行し、通れば Consumer Projection を生成します。

CI など、完全な実行 bundle の生成を必須にしたい環境では npx ninka-authz build を使います。通常の compile と違い、build は必要な bundle を生成できなければ失敗します。

5. アプリケーションで認可判定を使う​

生成された Consumer Projection を import し、policy id から導出した参照名でポリシーを指定します。

import { createNinka, policies } from "@/src/generated/ninka";

const authz = await createNinka();

const allowed = authz.check(policies.invoiceAccess, {
  subject: {
    properties: {
      roles: session.user.roles,
      user_id: session.user.id,
    },
  },
  action: { name: "view" },
  resource: {
    type: "invoice",
    properties: {
      amount: invoice.amount,
      submitted_by: invoice.submittedBy,
    },
  },
});

if (!allowed) {
  return new Response("Forbidden", { status: 403 });
}

createNinka() はランタイムを生成するときに、埋め込まれた実行 bundle を検証します。policies.invoiceAccess には policy id、仕様のハッシュ、そのポリシー用に生成された TypeScript の入力契約が結び付いています。

一方、いつ check() を呼ぶか、どの具体的なリソースを認可対象にするか、入力をどう組み立てるか、deny をどう処理するかはアプリケーション側の責任です。詳しくは TypeScript ランタイム API を参照してください。.NET については .NET ランタイム API にあります。

6. ポリシー全体を確認する​

npx ninka-authz docs

生成される Authorization Reference では、現在のポリシー、ルール、audit 情報、入力要件、validation の例、コンパイル済みの状態を確認できます。検証済みの WASM bundle がある場合は、Try it で具体的な入力に対する判定もブラウザ内で試せます。

Authorization Reference は読み取り専用です。プロジェクトをコンパイルしたり変更したりせず、人間の承認状態を記録するものでもありません。詳しくは Authorization Reference を参照してください。

7. CI で生成状態を検証する​

npx ninka-authz verify

verify は、現在の手形と toolchain の契約から生成状態を再現し、解決された出力先にあるファイルと比較します。固定された OPA toolchain を利用できる場合は、実行 bundle の再 build や WASM に対する必要な validation も検査します。OPA toolchain 自体を取得できない場合は、確認できなかった項目を not checked と明示し、確認済みであるかのようには扱いません。

verify が見るのはディスク上のファイルです。Git で追跡されているかどうかは検査しません。

正確な検査項目、フラグ、スキップ条件、出力先、失敗条件は CLI リファレンス を参照してください。これらの検査と人間のレビューを分ける理由は 認可コンパイラ で説明しています。

次に読む​