デバイスプロビジョニングパターン

コンテキスト

FlexGalaxy.AIは、各アカウント（テナント）が独自のIoTデバイスフリートを管理するマルチテナントAPaaSです。プラットフォームは複数のバックエンドシステムを使用します — デバイス管理とテレメトリにThingsBoard、OTA更新にhawkBit、プラットフォームAPI認証にDotID — それぞれが独自のデバイスIDと認証情報モデルを持っています。

デバイスプロビジョニングは単一のイベントではありません。デバイスはライフサイクル全体を通じて複数のプロビジョニング段階を経る可能性があります — 工場での組み立てからフィールドデプロイまで — それぞれ異なるID証明、認証情報要件、ターゲットアカウントがあります。

Provisioning Serviceは専用のマイクロサービスであり、DeviceAdminとは分離され、api.flexgalaxy.com/provisioning/v1/で公開されています。DeviceAdminは登録をProvisioning Serviceに委譲し、その上にデバイス管理APIを提供します。

プロビジョニングシナリオ

デバイスはライフサイクルの異なる段階で、異なるアクターによって、異なるアカウントにプロビジョニングされます：

シナリオ1：工場プロビジョニング（コントローラ）

コアコントローラがコントローラ工場で製造され、基本ファームウェアが書き込まれます。これは最も初期のプロビジョニングステップです。

Controller Factory
     │
     │  POST /provisioning/v1/enroll
     │  {
     │    "scenario": "factory",
     │    "device_type": "controller",
     │    "manufacturer": "syrius",
     │    "serial": "CTRL-2024-001",
     │    "firmware_version": "bootloader-1.0"
     │  }
     │  + mTLS (manufacturer CA cert)
     │
     ▼
Provisioning Service
     ├── ThingsBoard: create device (basic profile, factory account)
     ├── hawkBit: create target (eligible for firmware updates)
     └── Return: MQTT credentials + DDI token

この段階では：

• コントローラはメーカーのアカウントに登録されます

• 基本ファームウェアと接続認証情報のみが発行されます

• DotID M2Mクライアントなし（まだビジネスAPI参加者ではない）

• コントローラはhawkBit DDI経由でファームウェア更新を受信できます

シナリオ2：組み立てプロビジョニング（ロボット）

コントローラが完全なロボットに組み立てられると、ロボットはフルソフトウェアのインストールと運用プロファイルへの移行のために再プロビジョニングを要求します。

Assembly Line
     │
     │  POST /provisioning/v1/enroll
     │  {
     │    "scenario": "assembly",
     │    "device_type": "amr",
     │    "parent_serial": "CTRL-2024-001",
     │    "serial": "AMR-X1-2024-001",
     │    "capabilities": ["navigation", "picking", "charging"]
     │  }
     │  + mTLS (same manufacturer CA cert)
     │
     ▼
Provisioning Service
     ├── ThingsBoard: upgrade device profile (controller → AMR)
     ├── hawkBit: update target attributes (capabilities, type)
     ├── DotID: create M2M OIDC client (robot can now call platform APIs)
     └── Return: full credentials (MQTT + DDI + M2M API)

この段階では：

• デバイスレコードが「コントローラ」から「AMR」にフル機能付きでアップグレードされます

• DotID M2Mクライアントが作成されます（ロボットがFlexGalaxyビジネスAPIを呼び出せるようになる）

• デバイスはまだメーカーのアカウント配下にある場合があります（出荷前）

シナリオ3：フィールドプロビジョニング（顧客デプロイ）

デバイスが顧客サイト（倉庫、ショッピングモール）に到着すると、顧客のアカウントにプロビジョニングされます。これはタブレットやPDA向けのMDMスタイルのプロビジョニングもカバーします。

Customer Site (warehouse, mall)
     │
     │  POST /provisioning/v1/enroll
     │  {
     │    "scenario": "field",
     │    "claim_token": "tok-abc-123",
     │    "device_type": "pda",
     │    "serial": "PDA-2024-042"
     │  }
     │  (or mTLS for robots being transferred)
     │
     ▼
Provisioning Service
     ├── Validate claim token → resolve customer account
     ├── ThingsBoard: create device (or transfer from manufacturer account)
     ├── hawkBit: update target tenant
     ├── DotID: create/update M2M client (scoped to customer account)
     └── Return: operational credentials for customer environment

フィールドプロビジョニングは以下を処理します：

• メーカーから移管されたロボット — デバイスがメーカーアカウントから顧客アカウントに移動し、認証情報がローテーションされます

• タブレット / PDA — クレームトークン（QRコードスキャン）を使用したMDMスタイルの登録

• 制約付きセンサー — 設置時に配布される事前共有トークン

• クロスアカウント — デバイスが異なるアカウント、組織、権限スコープにまたがる場合があります

シナリオサマリー

シナリオ	アクター	アカウント	ID	発行される認証情報
工場	メーカー	メーカーアカウント	mTLS（メーカーCA）	MQTT + DDI
組み立て	メーカー	メーカーアカウント	mTLS（メーカーCA）	MQTT + DDI + M2M API
フィールド（ロボット）	顧客 / オペレーター	顧客アカウント	mTLSまたはクレームトークン	MQTT + DDI + M2M API（ローテーション済み）
フィールド（PDA/タブレット）	現場オペレーター	顧客アカウント	クレームトークン（QR）	MQTT + DDI + M2M API
フィールド（センサー）	インストーラー	顧客アカウント	事前共有トークン	MQTT + DDI

パターン

デバイスID検証

プロビジョニングシナリオごとに異なるID証明を使用します：

デバイスクラス	ID方式	検証
ロボット（AMR、清掃）	X.509クライアント証明書	メーカーの下位CAに対して検証
PDA / タブレット	クレームトークン + デバイスシリアル	物理セットアップ時に発行されたトークン（QRコード）
制約付きセンサー	事前共有アクセストークン	設置時に配布されたトークン
ゲートウェイ	X.509またはクレームトークン	ゲートウェイタイプに依存

X.509証明書チェーン

ロボットクラスのデバイスでは、FlexGalaxy.AIは証明書チェーンを使用します：

FlexGalaxy Root CA
└── Manufacturer Subordinate CA (e.g., Syrius Robotics CA)
    └── Device Certificate (e.g., AMR-X1 SN-2024-001)

• プラットフォームは開発者ポータル経由で登録されたメーカーCAを信頼します

• 各デバイスはmTLS登録時に自身の証明書を提示します

• Provisioning Serviceはチェーンを検証し、証明書のSubject DNからメーカーとシリアル番号を抽出します

クレームトークン

mTLSができないデバイス（PDA、タブレット、センサー）向け：

1. Operator generates claim tokens in bulk via API or StarGate
2. Tokens are printed as QR codes or loaded onto devices during setup
3. Device presents claim token during enrollment
4. Token maps to account + device type + priority + expiry
5. Token is consumed (single-use)

テナント解決

Provisioning Serviceは、デバイスがどのThingsBoardテナント（FlexGalaxyアカウント）に属するかを解決します：

ID方式	テナント解決
X.509証明書（工場/組み立て）	メーカーCA → メーカーアカウント
X.509証明書（フィールド移管）	クレームトークンによるオーバーライド → 顧客アカウント
クレームトークン	トークンにアカウントIDが直接含まれる
事前共有トークン	トークンは特定のアカウント向けに発行された

バックエンドシステム登録

ID検証とテナント解決の後、Provisioning Serviceはバックエンドシステムにデバイスレコードを作成または更新します：

ステップ	システム	API呼び出し	結果
1	ThingsBoard	POST /api/device または PUT /api/device/{id}	デバイスID、MQTT認証情報
2	hawkBit（OTAForge経由）	POST /rest/v1/targets または属性の更新	コントローラID、DDIセキュリティトークン
3	DotID	OIDCクライアントの作成（該当する場合）	クライアントID、クライアントシークレット（M2M）

すべてのシステムが同一のデバイス識別子（device_id）を使用し、システム間の相関を可能にします。

発行される認証情報タイプ

認証情報	システム	目的	ローテーション
MQTTアクセストークン	ThingsBoard	テレメトリ取り込み、デバイス管理	Provisioning Service経由
DDIセキュリティトークン	hawkBit（OTAForgeプロキシ経由）	OTA更新のポーリング	Provisioning Service経由
OIDCクライアント認証情報	DotID (Keycloak)	ビジネスAPIアクセス（client_credentialsグラント）	DotID API経由
X.509証明書（使用する場合）	mTLS	登録ID	メーカー管理

デバイスライフサイクル

┌──────────┐     ┌────────────┐     ┌──────────┐     ┌──────────┐     ┌───────────────┐
│ Unmanaged │────►│  Factory   │────►│ Assembled │────►│  Field   │────►│ Decommissioned│
│           │     │ Provisioned│     │ Upgraded  │     │  Active  │     │               │
└──────────┘     └────────────┘     └──────────┘     └──────────┘     └───────────────┘
                       │                  │                │
                       │ failure          │ failure        │ suspend
                       ▼                  ▼                ▼
                 ┌────────────┐     ┌────────────┐   ┌──────────┐
                 │  Rejected  │     │  Rejected  │   │ Suspended │
                 └────────────┘     └────────────┘   └──────────┘

状態	説明
未管理	物理デバイスまたはコンポーネント、未登録
工場プロビジョニング済み	基本ファームウェアでコントローラ登録済み、メーカーアカウント
組み立て済み / アップグレード済み	フル機能を持つ完全なロボット、メーカーアカウント
フィールド稼働中	顧客サイトにデプロイ済み、顧客アカウント、完全稼働中
停止中	一時的に無効化（例：リース期限切れ、ポリシー違反）
廃止	すべてのシステムから削除済み、認証情報は失効
拒否	登録失敗（無効なID、不明なメーカー）

アカウント移管

デバイスがメーカーから顧客へ（または顧客間で）移動する場合：

1. scenario: "field" + クレームトークンまたはmTLSによる新規登録リクエスト

2. Provisioning ServiceがThingsBoardデバイスを新しいテナントに移管

3. hawkBitターゲット属性を更新（新しいテナントコンテキスト）

4. DotID M2Mクライアントをローテーション（新しいアカウントスコープ）

5. 旧認証情報を失効し、新しい認証情報を発行

6. device.transferredイベントをKafkaに送信

廃止

デバイスが廃止される場合：

1. ThingsBoard認証情報を失効（デバイスを無効化）

2. hawkBitターゲットを削除（OTA更新の停止）

3. DotID M2Mクライアントを削除（APIアクセスを失効）

4. テレメトリデータをアーカイブ（保持ポリシーが適用）

5. device.decommissionedイベントをKafkaに送信

APIインターフェース

操作	エンドポイント	説明
POST /provisioning/v1/enroll	デバイスの登録または再プロビジョニング
GET /provisioning/v1/devices/{id}	プロビジョニングステータスと履歴を取得
POST /provisioning/v1/devices/{id}/transfer	デバイスを別のアカウントに移管
POST /provisioning/v1/devices/{id}/rotate-credentials	すべてのシステムで認証情報をローテーション
POST /provisioning/v1/devices/{id}/suspend	デバイスを停止
POST /provisioning/v1/devices/{id}/reactivate	停止中のデバイスを再有効化
DELETE /provisioning/v1/devices/{id}	デバイスを廃止
POST /provisioning/v1/claim-tokens	クレームトークンを生成（バッチ）
GET /provisioning/v1/claim-tokens?account={id}	未使用のクレームトークンを一覧表示

依存関係

サービス	関係
ThingsBoard	デバイスレコードとMQTT認証情報の作成/移管
OTAForge (hawkBit)	ターゲットとDDIセキュリティトークンの作成/更新
DotID (Keycloak)	M2M OIDCクライアントの作成
Org Service	アカウント/テナントコンテキスト、組織階層の解決

利用元

利用者	用途
DeviceAdmin	登録、移管、廃止操作を委譲
デバイス	工場、組み立て、またはフィールドデプロイ時に登録
StarGate	プロビジョニング管理とクレームトークン生成のための管理UI
アプリケーション	デバイスプロビジョニングステータスの照会

結果

利点

• マルチシナリオプロビジョニング — 同一サービスが工場、組み立て、フィールド登録を異なるID証明と認証情報セットで処理

• アカウント移管 — デバイスが認証情報のローテーションと監査証跡を伴ってアカウント間（メーカー → 顧客）で移動可能

• 一貫したID — ThingsBoard、hawkBit、DotID間で同一のデバイスIDによりシステム間相関を実現

• DeviceAdminからの分離 — プロビジョニングロジックは複雑であり（補償トランザクション、マルチシナリオ、アカウント移管）、独自のライフサイクルを持つ独立サービスとすることで利点が得られる

トレードオフ

• マルチシステム連携 — プロビジョニングはThingsBoard、hawkBit、DotIDのすべてが利用可能であることに依存。いずれかがダウンすると登録が失敗

• 補償トランザクション — 登録途中でシステムが失敗した場合、部分的なレコードをクリーンアップする必要がある

• カスタムサービス — FlexGalaxy固有のサービスであり、既製コンポーネントではない。構築と保守が必要