• 日本語

      • セキュリティと監査

      前提条件

      このページを読む前に、AI ビルダー クイックスタートに従って NocoBase CLI のインストールと初期化が完了していることを確認してください。

      ユーザーが NocoBase CLI を通じて AI Agent で NocoBase を操作する場合、認証、権限制御、監査追跡に注意が必要です。操作の境界を明確にし、プロセスを追跡可能にすることが重要です。

      認証

      AI Agent が NocoBase に接続する際、主に 2 つの認証方式があります：

      • API key 認証：API keys プラグインで API Key を生成し、CLI 環境に設定します。以降のリクエストではこの API Key を使用して API にアクセスします
      • OAuth 認証：ブラウザで一度 OAuth ログイン認証を行い、その後は現在のユーザー身元で API にアクセスします

      どちらの方式も nb コマンドと組み合わせて使用できます。違いは、身元のソース、適用シナリオ、リスク管理戦略にあります。

      API key 認証

      API key は主に自動化、スクリプト化、長期実行タスクに使用されます。例えば：

      • AI Agent による定期的なデータ同期
      • 開発環境での頻繁な nb api の呼び出し
      • 固定ロールによる明確で安定した構築タスクの実行

      基本的な流れは以下の通りです：

      1. NocoBase で API keys プラグインを有効にし、API Key を作成
      2. この API Key に専用ロールを割り当て、root や管理者の完全な権限を直接割り当てない
      3. nb env add で API アドレスと Token を CLI 環境に保存

      例：

      nb env add local \
  --scope project \
  --api-base-url http://localhost:13000/api \
  --auth-type token \
  --access-token <your-api-key>

      設定完了後、AI Agent はこの環境を通じて API を呼び出せます：

      nb api resource list --env local --resource users

      この方式は安定しており、自動化に適しています。ユーザーが毎回ログインし直す必要もありません。ただし、Token が無効化されない限り、Token を持つ人はバインドされたロールの権限でシステムにアクセスし続けることができるため、以下の点に特に注意してください：

      • Token には専用ロールのみをバインドする
      • 必要な CLI 環境にのみ保存する
      • 定期的にローテーションし、「無期限」をデフォルトにしない
      • 漏洩の疑いがある場合は即座に削除して再生成する

      その他の一般的な説明は NocoBase セキュリティガイドを参照してください。

      OAuth 認証

      OAuth は主に現在のログインユーザーの身元で操作を実行するタスクに使用されます。例えば：

      • AI に現在の管理者として一回限りの設定調整を実行させる
      • 操作を明確なログインユーザーに帰属させる必要がある
      • 高権限の Token を長期的に保存したくない

      基本的な流れは以下の通りです：

      1. CLI 環境を追加し、認証方式として oauth を選択
      2. nb env auth を実行
      3. ブラウザで認証ページを開き、ログインして認証を完了
      4. CLI が認証情報を保存し、以降の nb api リクエストは現在のユーザー身元で NocoBase にアクセス
      5. ユーザーが複数のロールを持っている場合は、--role でロールを指定可能

      例：

      nb env add local \
  --scope project \
  --api-base-url http://localhost:13000/api \
  --auth-type oauth

nb env auth local

      nb env auth はブラウザのログインフローを開始します。成功すると、CLI は認証情報を現在の環境設定に保存し、その後も AI Agent に nb api を呼び出させることができます。

      OAuth アクセストークンとリフレッシュトークンの有効期間は、システムの Token ポリシー 設定に従います。

      • OAuth アクセストークンの有効期間はシステム Token の有効期間と同じで、デフォルトは 1 日 です
      • OAuth リフレッシュトークンの有効期間はシステムセッションの有効期間と同じで、デフォルトは 7 日 です

      CLI はアクセストークンの有効期限が近づくと、優先的にリフレッシュトークンを使用してセッションを自動更新します。リフレッシュトークンが期限切れ、利用不可、またはサーバーからリフレッシュトークンが返されなかった場合は、nb env auth を再度実行する必要があります。Token ポリシーを変更した場合、その変更を OAuth サービスに反映するにはシステムの再起動が必要です。

      OAuth の特徴は、リクエストが通常は現在のログインユーザーとそのロールコンテキストで実行されるため、監査記録も実際の操作者に対応付けやすい点です。この方式は、人的関与が必要で身元の確認が求められる操作に適しています。

      推奨プラクティス

      以下の原則に従って選択することを推奨します：

      • 開発、テスト、自動化タスク：API key を優先的に使用しますが、必ず専用ロールをバインドしてください
      • 本番環境、人的関与あり、強い身元帰属が必要：OAuth を優先的に使用してください
      • 高リスクな操作：技術的に Token が使用可能でも、OAuth に変更し、適切な権限を持つユーザーが認証を完了してから実行することを推奨します

      明確な要件がない場合は、以下のデフォルト原則に従ってください：

      • デフォルトでは OAuth を使用する
      • 自動化、無人運用、またはバッチ実行が明確に必要な場合のみ API key を使用する

      権限制御

      AI Agent 自体には「追加の権限」はありません。AI ができることは、現在使用されている身元とロールに完全に依存します。

      つまり：

      • API key でアクセスする場合、権限の境界はこの Token にバインドされたロールによって決まります
      • OAuth でアクセスする場合、権限の境界は現在のログインユーザーと現在のロールによって決まります

      AI は NocoBase の ACL システムをバイパスしません。あるロールが特定のデータテーブル、フィールド、ページ、またはプラグイン設定の権限を持っていない場合、AI Agent が対応するコマンドを知っていても、正常に実行することはできません。

      ロールと権限ポリシー

      AI Agent には、既存の管理者ロールを再利用するのではなく、専用のロールを準備することを推奨します。

      このロールには通常、以下の範囲内の権限のみを開放する必要があります：

      • 操作可能なデータテーブル
      • 実行可能なアクション（閲覧、作成、更新、削除など）
      • 特定のページやメニューへのアクセスの可否
      • システム設定、プラグイン管理、権限設定などの高リスク領域への入場の可否

      例えば、ai_builder_editor というロールを作成し、以下のみを許可できます：

      • CRM 関連のデータテーブルの管理
      • 指定ページの編集
      • 一部のワークフローのトリガー
      • ロール権限の変更は不可
      • プラグインの有効化、無効化、インストールは不可
      • 重要なデータテーブルの削除は不可

      AI に権限設定を支援させたい場合は、権限設定と組み合わせて行えますが、権限の境界は先に人が決定することを推奨します。

      最小権限の原則

      最小権限の原則は AI ビルダーのシナリオで特に重要であり、以下のアプローチを採用できます：

      1. AI 用の専用ロールを作成する
      2. 初期段階では閲覧権限のみを開放する
      3. タスクに応じて作成、編集などの必要な権限を段階的に追加する
      4. 削除、権限変更、プラグイン管理などの高リスク操作は人的制御を維持する

      例えば：

      • コンテンツ入力用の AI には、対象データテーブルの閲覧と作成権限のみが必要
      • ページ構築用の AI には、関連ページと UI 設定権限のみが必要
      • データモデリング用の AI には、テスト環境のみでテーブル構造の変更権限を開放し、本番環境には直接開放しない

      root、admin、またはグローバルシステム設定権限を持つロールを AI Agent に直接バインドすることは推奨しません。この方法はデプロイは簡単ですが、権限の露出面が大幅に拡大します。

      ログ

      AI ビルダーのシナリオでは、ログは操作追跡と問題特定に使用されます。

      以下の 2 種類のログに注目してください：

      • リクエストログ：API リクエストのパス、メソッド、ステータスコード、所要時間、リクエスト元などの情報を記録
      • 監査ログ：重要なリソース操作の実行主体、操作対象、結果、関連メタデータを記録

      nb api でリクエストを送信する際、CLI は自動的に x-request-source: cli リクエストヘッダーを付与するため、サーバー側ではこのリクエストが CLI からのものであることを識別できます。

      リクエストログ

      リクエストログは、リクエストパス、レスポンスステータス、所要時間、ソースマーカーなどの API 呼び出し情報を記録します。

      ログファイルは通常以下に配置されます：

      storage/logs/<appName>/request_YYYY-MM-DD.log

      nb api 呼び出しのシナリオでは、リクエストログに以下が含まれます：

      • req.header.x-request-source

      これにより、CLI リクエストと通常のブラウザリクエストを区別できます。

      リクエストログのディレクトリとフィールドの説明は、NocoBase サーバーログを参照してください。

      監査ログ

      監査ログは、重要な操作の実行主体、対象リソース、実行結果、関連リクエスト情報を記録します。

      監査対象となっている操作について、ログには以下が記録されます：

      • resource
      • action
      • userId
      • roleName
      • status
      • metadata.request.headers.x-request-source

      例えば、AI が CLI を通じて collections:apply、fields:apply、またはその他の監査が有効な書き込み操作を呼び出した場合、監査ログに x-request-source: cli が記録され、UI 操作と CLI からの操作を区別できます。

      監査ログの詳細は、監査ログを参照してください。

      セキュリティに関する推奨事項

      AI ビルダーのシナリオに適した実践的な推奨事項を以下に示します：

      • AI Agent に root、admin、またはグローバルシステム設定ロールを直接バインドしない
      • AI Agent 用の専用ロールを作成し、タスクごとに権限の境界を分割する
      • API key を定期的にローテーションし、同一の高権限 Token の長期再利用を避ける
      • テスト環境でデータモデリング、ページ構造、ワークフローの変更を検証してから、本番環境に同期する
      • リクエストログと監査ログを有効にして定期的に確認し、重要な操作の追跡可能性を確保する
      • データの削除、権限の変更、プラグインの有効化/停止、システム設定の調整などの高リスク操作は、人的確認後に実行することを推奨する
      • AI が長期運行する場合は、複数の低権限環境に分割し、単一の高権限環境への集中使用を避けることを優先する

      関連リンク