メインコンテンツへスキップ

セキュリティモデル

UPP は、セキュリティと使いやすさのバランスを取った**「初回承認 + 事前共有キー」**セキュリティモデルを使用します。

主な原則

  1. ユーザー承認が必須 - 新しい実行ノードには明示的なユーザー承認が必要
  2. キーベース認証 - 既知の実行ノードは事前共有キーで認証
  3. 内部ネットワークのみ - ローカルネットワーク展開用に設計され、公共インターネットには公開されません
  4. キー永続化 - キーは将来の接続に向けて安全に保存

認証フロー

UPP 認証フロー: 実行ノード登録とキー検証プロセスを示す決定木

初回接続

実行ノードが初めて接続するとき(キーなし):

1. 実行ノードが登録を送信

2. Qaptly が承認ダイアログを表示

Qaptly Desktop にダイアログが表示されます:

3. ユーザーの決定

ユーザーが承認した場合:
ユーザーが拒否した場合:

4. 実行ノードがキーを保存

重要: 将来の接続のために assignedKey を保存してください!

後続の接続

有効なキーを持つ既知の実行ノードの場合:

1. 実行ノードがキーとともに登録を送信

2. Qaptly がキーを検証

キーは保存されたハッシュに対して検証されます。ユーザーの操作は不要です。

3. 自動承認


事前共有キー(高度)

本番デプロイメントの場合、最初の接続前にキーを事前設定できます。

ユースケース

  • 組込みデバイス: 事前設定されたキーでデプロイ
  • CI/CD パイプライン: 自動テスト実行ノード
  • フロート管理: 複数の実行ノードを一度にデプロイ

実装

1. 手動でキーを生成

Qaptly Desktop の実行ノード拡張設定ファイルに追加:

2. キーを実行ノードデバイスにデプロイ

3. 実行ノードが接続

実行ノードはユーザーの操作なしに自動的に承認されます。
事前共有キーは以下の場合に便利です:
  • 本番環境
  • 自動テスト
  • ヘッドレスデプロイメント
  • フロート管理

セキュリティのベストプラクティス

1. 内部ネットワークのみ

UPP はローカルネットワーク展開用に設計されています: ✅ 正しい: ws://<qaptly_desktop_ip>:18765/upp(192.168.1.100 のようなローカルネットワーク IP) ❌ 禁止: 公共インターネットに公開したり、パブリック IP アドレスにバインドしたりしない セキュリティガイドライン:
  • 信頼できる内部ネットワークにのみ展開
  • 必要に応じてファイアウォールルールでアクセスを制限
  • リモート実行ノードアクセスには VPN の使用を検討
  • ポート 18765 をインターネットにポートフォワードしない

2. キーストレージ

しないでください:
  • キーをバージョンコントロールにコミット
  • キーを公開共有
  • 複数の実行ノードで同じキーを使用
  • 本番環境でキーをプレーンテキストで保存
してください:
  • 環境変数またはコンフィグファイルを使用
  • 適切なファイルパーミッション(chmod 600)を設定
  • 開発/本番に異なるキーを使用
  • 定期的にキーをローテーション(オプション)

3. 実行ノード ID の一意性

一意の実行ノード ID を選択:

4. バージョン情報

常に正確なバージョン番号を含める:
これにより、ユーザーが古い実行ノードを特定できます。

キー管理

キー生成

Qaptly は以下を使用してキーを生成:
  • 256 ビットのランダムバイト
  • 16 進数エンコーディング
  • 暗号化乱数生成器

キーストレージ

キーは以下で保存:
  • SHA-256 ハッシング(プレーンテキストではない)
  • セキュアなファイルパーミッション
  • バックアップメカニズム

キーローテーション(オプション)

キーをローテーションするには:
  1. ユーザー: Qaptly Desktop でお古い実行ノードを無効化
  2. 実行ノード: キーなしで接続(初回フロー)
  3. ユーザー: 承認して新しいキーを受け取る
  4. 実行ノード: 新しいキーを保存して使用

エラーコード

認証エラー

AUTH_FAILED を処理する


切断後の再接続

実行ノードが切断された場合(ネットワーク問題、再起動など):

5 分以内

  • 同じキーで再接続
  • Qaptly は登録を記憶
  • ユーザー承認は不要
  • イベント登録が復元

5 分後

  • 実行ノードが登録解除
  • キーで再度登録する必要がある
  • 「後続の接続」フロー と同じ
  • キーが無効な場合、ユーザー承認が必要になる場合がある

認証をテストする

テスト 1: 初回接続

期待される結果:
  1. 「ユーザー承認を待機中…」
  2. Qaptly にダイアログが表示される
  3. 承認後: 「assignedKey を受信」

テスト 2: 再接続

期待される結果:
  1. 即座に成功
  2. ユーザーの操作なし

テスト 3: 無効なキー

期待される結果:
  1. AUTH_FAILED エラー
  2. 実行ノードは正常に処理すべき

例: 完全な認証フロー


次のステップ

プロトコルリファレンス

完全なメッセージ仕様

機能

JSON Schema を使用した機能の定義

クイックスタート

最初の実行ノードを構築

例

完全な実装例