Authorization Reference
Authorization Reference は、プロジェクトの認可仕様と生成済みの状態を読み取り専用で確認するための画面です。ポリシー全体を理解したり、ルールや要件解釈を確認したり、生成された validation の例や具体的な入力に対する判定を確かめたりするときに使います。
npx ninka-authz docs
何を確認できるか
Authorization Reference は、レビュー時に出てくる次のような問いに答えるためのものです。
- このポリシーは何を許可し、何を拒否するのか
- どの role・action・resource・条件・関係を使っているのか
- 手形を作る際に、どのような解釈が記録されたのか
- 表示中の仕様と生成済みの成果物は、現在も対応しているのか
- 具体的な入力に対して、コンパイル済みポリシーはどの判定を返すのか
Authorization Reference は、エディタでも認可サーバでも、本番監視用のダッシュボードでもありません。手形を書き換えず、プロジェクトをコンパイルせず、人間の承認状態も記録しません。アプリケーションの認可判定経路にも入りません。
Resources・Roles・Actions の各ビューは、その語がどこで使われているかを探すための索引です。プロジェクト全体の実効権限を計算したものではありません。
LIVE: 現在のプロジェクトを確認する
npx ninka-authz docs
LIVE モードでは、現在のプロジェクトを loopback 上で表示します。画面を開いている間は、関係する作業ツリーの変更に追従します。ただし、その変更を代わりにコンパイルすることはありません。
ポリシーごとに、主に次を確認できます。
- Overview：ポリシーの identity と成果物の状態
- Rules：effect、subject、action、resource、conditions、relationships
- Source：手形のソース
- Audit：記録されたソーステキストと ambiguities
- Try it：ポリシーの入力契約から生成されるフォーム
- Validation examples：Try it に読み込める生成済みの検証例
STALE は、仕様だけが先に変わった状態
最後のコンパイル後に手形を変更すると、LIVE は新しい仕様を表示しつつ、コンパイル済みの状態を STALE と表示します。再コンパイルするまで、対話的な評価は無効になります。
手形を編集する
↓
Reference は新しい仕様を表示する
↓
コンパイル済みの状態は STALE
↓
Try it は無効
↓
npx ninka-authz compile
↓
仕様とコンパイル済みの状態が再び対応する
古いコンパイル結果を、現在の手形を表すものとして評価しないための動作です。
具体的な入力を試す
Try it は、生成された入力契約からフォームを作り、その入力をコンパイル済みポリシーに対してブラウザ内で評価します。
ポリシーのレビュー中に、具体的なケースを確かめるために使います。Show evaluation input を開くと runtime に渡されるオブジェクトを確認できるため、アプリケーションが組み立てるべき入力との比較にも使えます。
ALLOW・DENY・ERROR は別の結果として扱われます。成果物の整合性エラーや runtime の失敗を、deny の認可判定として表示することはありません。
語彙の値が入力候補として表示されることがありますが、これは入力値の検証ではありません。deny の挙動を確認するために、語彙に無い値を Try it へ入力することもできます。
生成された validation の例を見る
現在の手形から生成された validation の例も確認できます。例を読み込むと Try it のフォームへ値が入り、そのケースを画面上で確認できます。フォームで表現できるケースなら、そのまま評価もできます。
これらは現在の手形とコンパイル済みポリシーについての証拠です。以前のポリシーや、移行元の認可システムとの一致を保証するものではありません。違いについては 認可をテストする を参照してください。
SNAPSHOT: 現在の認可状態を書き出す
npx ninka-authz docs -o ./reference
自己完結した静的な Authorization Reference を書き出します。このコマンドはプロジェクトをコンパイルしたり変更したりせず、人間が承認済みであることも主張しません。snapshot として公開できる成果物の条件を満たしている場合だけ書き出しに成功し、条件を満たしていなければ修正すべき点を報告します。
書き出した snapshot は通常の静的ホスティングで配信できます。取り込まれた bundle をブラウザ内で評価するため、Ninka のサーバや別の認可バックエンドは必要ありません。
snapshot は次の情報を記録します。
- 取り込んだ認可状態の identity (
snapshot_hash) - 書き出し時刻 (
exported_at)
snapshot_hash は「同じ認可状態を取り込んだ snapshot か」を識別し、exported_at は「いつ書き出したか」を示します。どちらも人間の承認状態を表すものではありません。
Authorization Reference には、role・action・conditions・relationships・入力例など、セキュリティ設計に関わる情報が含まれます。開発環境の外へ公開する前に、誰に見せてよい情報かを確認してください。
LIVE と SNAPSHOT の違い
| LIVE | SNAPSHOT | |
|---|---|---|
| 元になる状態 | 現在のプロジェクト | 書き出した時点の認可状態 |
| 更新 | 関係する作業ツリーの変更に追従 | 変化しない |
| stale / 不正な状態の表示 | できる | できない。公開可能な状態でなければ書き出し自体を拒否する |
| 評価 | コンパイル済み bundle をブラウザ内で評価 | snapshot に含まれる bundle をブラウザ内で評価 |
| プロジェクトをコンパイルするか | しない | しない |
| 主な用途 | 開発中の確認・レビュー | ある時点の状態を共有・保存 |
モードバッジを見ると、どの状態を表示しているかと、その整合性を確認できます。
信頼の境界
Authorization Reference は Ninka の認可成果物を人間向けに表示するビューであり、独自の意味論を持つ別のポリシーエンジンではありません。評価するときは、runtime がコンパイル済み bundle を使う際と同じ成果物の identity と結び付きを前提にします。STALE や整合性エラーを黙って評価することはありません。
成果物の連鎖、bundle の結び付き、ハッシュ、生成ファイルの形式は 生成ファイル を参照してください。コンパイラと OPA build の責任境界は 認可コンパイラ で説明しています。