NOGIKU

NAPS プロトコル ​

概要 ​

NAPS（Nogiku Access Permissions Sync）は、連携システムが自らの定義する権限の名前と説明を宣言し、Nogiku Access がそれを安全に取得するための「権限情報の自動取得」プロトコルです。 プロトコルでは、通信元の検証やペイロードの形式を指定しています。

NAPS が有効化されている場合、Nogiku Access は定期的にエンドポイントを巡回し、権限情報を自動で同期します。

背景 ​

Nogiku Access は、各連携システムの権限基盤ではありますが、権限の命名・権限の意味付けの決定権は連携システム側にあります。

そのため、Nogiku Access 側に権限情報を伝達する仕組みなしでは、権限一覧の保守や権限の意味理解は連携システムの知識を持つユーザーの責務となります。

この状態では、権限名のタイプミス等による意図しない権限エラーを生じやすくなるほか、前提的な UX が低下します。

技術仕様 ​

連携システムは、自身のベース URL 配下に権限情報エンドポイントを公開する。Nogiku Access はこのエンドポイントを呼び出し、返却された権限一覧をシステム権限として同期する。

エンドポイント ​

項目値
メソッドGET
パス/.well-known/permissions
完全 URL{ベース URL}/.well-known/permissions

認証 ​

Nogiku Access からのリクエストには Authorization ヘッダーで JWT を付与する。

Authorization: Bearer <JWT>

JWT のペイロードは次の形式とする。

json
{
  "iss": "https://<Nogiku Access Engine のホスト>/<ベースパス>/api",
  "iat": 1700000000,
  "exp": 1700000300
}
クレーム説明
issNogiku Access Engine の issuer
iat発行時刻（Unix 秒）
exp有効期限（Unix 秒）。発行から 5 分
連携システム側の検証手順 ​
  1. Authorization ヘッダーから Bearer トークンを取り出す
  2. {iss}/jwks から JWKS を取得し、JWT の署名を検証する
  3. iss が自環境で信頼する Nogiku Access Engine の issuer と一致することを確認する
  4. 現在時刻が exp より前であることを確認する

検証に失敗した場合は 401 Unauthorized を返す。

検証の重要性

委員会システムの権限情報を認証なしに公開すると、外部の第三者がそこからシステムの機能や構成を推測できてしまいます。 必ずプロトコル通りの検証を実装してください。

レスポンス ​

検証に成功した場合、200 OK で次の JSON を返す。

json
{
  "version": "naps@1.0",
  "permissions": [
    {
      "name": string,
      "description": string
    }
  ]
}
フィールド型説明
version文字列固定値 "naps@1.0"
permissions配列権限の一覧
permissions[].name文字列（1 文字以上）権限の名称
permissions[].description文字列権限の説明（空文字可）

権限名の表現 ​

階層的な権限は、各レベルの名前を : で連結したフラットな文字列で表現する。

ex）親 users の子 read は users:read とする。

Nogiku Access は、一覧に含まれる権限名から親ノードを自動的に補完する。補完された親ノードには空の description が設定される。例えば、users:read だけが返された場合、users という親権限が自動作成される。

Nogiku Access 側の挙動 ​

  • その権限が直近の NAPS 返却に存在したのであれば、その権限は "ENABLED" として扱い、削除不可・改名不可
  • その権限が直近の NAPS 返却に存在しなかった場合、その権限は "DEPRECATED" として扱い、削除可能・改名可能。自動的な削除は実行しない