組み込みデータベースの使用

EMQXの組み込みデータベースを、低コストかつすぐに使えるパスワード認証のオプションとして利用できます。有効化すると、EMQXはクライアント認証情報を組み込みデータベース（Mnesiaベース）に保存し、REST APIやダッシュボードを通じてデータを管理します。本ページでは、EMQXダッシュボードと設定項目を使って組み込みデータベースによる認証を設定する方法を紹介します。

TIP

EMQX認証の基本概念の知識があると理解が深まります。

ダッシュボードでの設定

EMQXダッシュボードを使って、パスワード認証に組み込みデータベースを設定できます。

1. EMQXダッシュボードの左側ナビゲーションメニューから Access Control -> Authentication をクリックします。
2. Authentication ページの右上にある Create をクリックします。
3. Mechanism に Password-Based、Backend に Built-in Database を選択し、Configuration タブに進みます。以下のように表示されます。

4. 以下の指示に従って認証バックエンドを設定します。

   • UserID Type: クライアントID認証に使用するフィールドを指定します。選択肢は username、clientid（MQTTクライアントが送信する CONNECT メッセージの Username または Client Identifier フィールドに対応）。

   • Password Hash: プレーンテキストのパスワードに適用し、結果をデータベースに保存する前のハッシュアルゴリズムを選択します。利用可能なオプションは plain、md5、sha、sha256、sha512、bcrypt、pbkdf2 です。選択したアルゴリズムに応じて追加設定があります。

     • md5、sha、sha256、sha512 の場合：
       • Salt Position: ソルト（ランダムデータ）をパスワードに混ぜる位置を指定します。suffix（後置）、prefix（前置）、disable（無効）のいずれかです。外部ストレージからEMQX組み込みデータベースへユーザー認証情報を移行する場合を除き、デフォルト値のままで問題ありません。
       • ハッシュ結果は16進文字列として表現され、大文字・小文字を区別せずに保存された認証情報と比較されます。
     • plain の場合：
       • Salt Position は disable にしてください。
     • bcrypt の場合：
       • Salt Rounds: ハッシュ関数を適用する回数を定義します。値は 2^{Salt Rounds} として表され、「コストファクター」とも呼ばれます。デフォルトは 10、許容範囲は 5 から 10 です。セキュリティ向上のためには高い値を推奨します。注：コストファクターを1増やすと認証にかかる時間が倍増します。
     • pbkdf2 の場合：
       • Pseudorandom Function: 鍵生成に使うハッシュ関数を選択します（例：sha256）。
       • Iteration Count: ハッシュ関数の実行回数を設定します。デフォルトは 4096。
       • Derived Key Length（任意）: 生成される鍵のバイト長を指定します。未指定の場合は選択した擬似乱数関数に基づく長さになります。
       • ハッシュ結果は16進文字列として表現され、大文字・小文字を区別せずに保存された認証情報と比較されます。

   • Precondition: Variform式で、この組み込みデータベース認証器をクライアント接続に適用するかを制御します。式はクライアントの属性（username、clientid、listenerなど）に対して評価され、結果が文字列 "true" の場合のみ認証器が呼び出されます。そうでなければスキップされます。詳細はAuthenticator Preconditionsを参照してください。

5. 設定が完了したら Create をクリックします。

設定項目による設定

設定項目を使って認証を設定することも可能です。

例：

{
   backend = "built_in_database"
   mechanism = "password_based"
   password_hash_algorithm {
      name = "sha256",
      salt_position = "suffix"
   }
   user_id_type = "username"
   bootstrap_file = "${EMQX_ETC_DIR}/auth-built-in-db-bootstrap.csv"
   bootstrap_type = "plain"
}

ファイルからのユーザーブートストラップ

password_based:built_in_database 認証器は、作成時にローカルファイルからユーザーをロードすることをサポートしています。

この仕組みは、以下のようなデプロイ時の初期ユーザー投入（シード）に適しています。

• デフォルト管理者アカウントの作成
• 事前定義されたクライアント認証情報のプリロード
• 初回セットアップ時の初期データ準備
• 初期管理者アカウントの事前定義（is_superuser = true の設定）

ブートストラップは認証器作成時に一度だけ実行されます。継続的なユーザー管理や大規模なランタイム移行には適していません。EMQX稼働後の一括インポートはユーザーのインポートを利用してください。

ブートストラップ設定

bootstrap_file = "${EMQX_ETC_DIR}/auth-built-in-db-bootstrap.csv"
bootstrap_type = "plain"  # または "hash"

bootstrap_file

• デフォルト: ${EMQX_ETC_DIR}/auth-built-in-db-bootstrap.csv
• 初期ユーザーをロードするためのローカルファイルを指定します。

ファイル形式は拡張子で判別されます：

• .csv: ヘッダー付きCSV
• .json: オブジェクトのJSON配列

EMQXに付属するデフォルトファイルはCSVヘッダーを使います：

user_id,password,is_superuser

bootstrap_type

• 値: plain または hash
• デフォルト: plain

ファイル内のパスワードデータの解釈方法を決定します。

ファイル形式の要件

bootstrap_type = plain の場合、以下のフィールドが必要です：

• user_id
• password
• is_superuser（任意、デフォルトは false）

EMQXは password を設定された password_hash_algorithm でハッシュ化して保存します。

bootstrap_type = hash の場合、以下のフィールドが必要です：

• user_id
• password_hash
• salt（任意、デフォルトは空文字列）
• is_superuser（任意、デフォルトは false）

EMQXは password_hash を再ハッシュせずにそのまま保存します。

ランタイム動作

認証器作成時に以下を実行します：

1. EMQXがブートストラップファイルを読み込みます。
2. CSVまたはJSONからユーザーを解析します。
3. ユーザーを組み込みデータベースに挿入します。

重要な注意点：

• 既存ユーザーは上書きされません（override = false）。
• is_superuser は以下の場合にのみ true として扱われます：
  • JSONの真偽値 true
  • CSV/JSONの文字列 "true"
  • それ以外はすべて false と解釈されます。
• ファイルの読み込みや解析エラーは警告ログに記録されます。
• ファイルにエラーがあっても認証器作成は成功します。

外部ストレージからEMQX組み込みデータベースへの移行

MySQL、LDAP、他のMQTTブローカーなど外部システムからEMQX組み込みデータベースへユーザー認証情報を移行する場合は、Import Users APIを使ってユーザーを一括アップロードできます。

ブートストラップとは異なり、インポートはEMQX稼働後に実行され、運用中のデータ移行を目的としています。詳細はユーザーのインポートを参照してください。