PostgreSQLとの統合

EMQXはパスワード認証のためにPostgreSQLとの統合をサポートしています。

TIP

基本的なEMQX認証の概念についての知識

データスキーマとクエリ文

EMQXのPostgreSQL認証機能はほぼあらゆるストレージスキーマに対応しています。ビジネスニーズに応じて、認証情報の保存方法やアクセス方法を自由に決定できます。例えば、1つまたは複数のテーブルやビューを使用することが可能です。

ユーザーはクエリ文のテンプレートを提供し、以下のフィールドが含まれていることを確認する必要があります。

• password_hash：必須。データベースに保存されているパスワード（プレーンテキストまたはハッシュ化されたもの）。
• salt：任意。salt = "" またはこのフィールドを削除すると、ソルト値が追加されないことを示します。
• is_superuser：任意。現在のクライアントがスーパーユーザーかどうかを示すフラグ。デフォルトは false。

認証情報を保存するためのテーブル構造の例：

CREATE TABLE mqtt_user (
    id serial PRIMARY KEY,
    username text NOT NULL UNIQUE,
    password_hash  text NOT NULL,
    salt text NOT NULL,
    is_superuser boolean DEFAULT false,
    created timestamp with time zone DEFAULT NOW()
);

TIP

上記の例では、クエリに役立つ暗黙の UNIQUE インデックス（username）が作成されています。 システム内のユーザー数が多い場合は、クエリの応答時間を短縮しEMQXの負荷を軽減するために、事前にテーブルの最適化やインデックス作成を行ってください。

このテーブルでは、MQTTユーザーは username によって識別されます。

例えば、スーパーユーザー（is_superuser: true）で、ユーザー名が user123、パスワードが secret、ソルトが salt のドキュメントを追加したい場合、クエリ文は以下のようになります。

INSERT INTO mqtt_user(username, password_hash, salt, is_superuser) VALUES ('user123', 'f84fa2149dbb62ed4e0cf1f550d2949b33a6513d3a7707e08502511c79ccb0ee', 'salt', true);
INSERT 0 1

対応する設定パラメータは以下の通りです。

• password_hash_algorithm: sha256
• salt_position: suffix

SQL:

query = "SELECT password_hash, salt, is_superuser FROM mqtt_user WHERE username = ${username} LIMIT 1"

ダッシュボードでの設定

EMQXダッシュボードを使って、PostgreSQLをパスワード認証に利用する方法を設定できます。

1. EMQXダッシュボードの左側ナビゲーションメニューから アクセス制御 -> 認証 をクリックします。
2. 認証 ページの右上にある 作成 をクリックします。
3. メカニズム に パスワードベース を、バックエンド に PostgreSQL を選択し、以下のように 設定 タブに進みます。

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

   • PostgreSQLへの接続情報を入力します。

     • サーバー：EMQXが接続するサーバーのアドレス（host:port）を指定します。
     • データベース：PostgreSQLのデータベース名。
     • ユーザー名：ユーザー名を指定します。
     • パスワード：ユーザーパスワードを指定します。

   • 認証に関連する設定を行います。

     • パスワードハッシュ：プレーンテキストのパスワードに適用され、結果がデータベースに保存されるハッシュアルゴリズムを選択します。利用可能なオプションは plain、md5、sha、sha256、sha512、bcrypt、pbkdf2 です。選択したアルゴリズムに応じて追加設定が必要です。
       • md5、sha、sha256、sha512 の場合：
         • ソルト位置：ソルト（ランダムデータ）をパスワードにどのように混ぜるかを指定します。suffix、prefix、disable のいずれかです。外部ストレージからEMQX組み込みデータベースにユーザー認証情報を移行しない限り、デフォルト値のままで問題ありません。
         • ハッシュ結果は16進数文字列で表現され、大文字小文字を区別せずに保存された認証情報と比較されます。
       • plain の場合：
         • ソルト位置：disable に設定してください。
       • bcrypt の場合：
         • ソルトラウンド：ハッシュ関数を適用する回数を、2のべき乗（2^ソルトラウンド）で表す「コストファクター」です。デフォルトは 10、許容範囲は 5～10 です。セキュリティ強化のためには高い値が推奨されます。注：コストファクターを1増やすと認証にかかる時間が倍増します。
       • pbkdf2 の場合：
         • 疑似乱数関数：鍵生成に用いるハッシュ関数を選択します（例：sha256）。
         • 反復回数：ハッシュ関数の実行回数を設定します。デフォルトは 4096 です。
         • 派生鍵長（任意）：生成される鍵の長さ（バイト単位）を指定します。空欄の場合は選択した疑似乱数関数により決定されます。
         • ハッシュ結果は16進数文字列で表現され、大文字小文字を区別せずに保存された認証情報と比較されます。

   • 前提条件：Variform式を使って、このPostgreSQL認証をクライアント接続に適用するかどうかを制御します。式はクライアントの属性（username、clientid、listenerなど）に対して評価され、結果が文字列 "true" の場合のみ認証が実行されます。それ以外の場合はスキップされます。詳細は認証の前提条件を参照してください。

   • TLSを有効化：TLSを有効にする場合はトグルスイッチをオンにします。TLS有効化の詳細はネットワークとTLSを参照してください。

   • 詳細設定：接続プール、タイムアウト、プリペアドステートメントの動作を設定します。

     • 接続プールサイズ（任意）：EMQXノードからPostgreSQLサーバーへの同時接続数を指定します。デフォルトは 8 です。
     • クエリタイムアウト（任意）：EMQXがクエリのタイムアウトと判断するまでの待機時間を指定します。ミリ秒、秒、分、時間の単位が利用可能です。デフォルトは 5 秒です。
     • 接続タイムアウト（任意）：EMQXが接続試行のタイムアウトと判断するまでの待機時間を指定します。ミリ秒、秒、分、時間の単位が利用可能です。デフォルトは 15 秒です。
     • プリペアドステートメントを無効化（任意）：データベースクエリにプリペアドステートメントを使用しないようにします。PostgreSQLのプロキシやミドルウェア（例：PGBouncerやトランザクションモードのSupabase）がセッションレベルのプリペアドステートメント機能をサポートしていない場合に有効にしてください。デフォルトは無効です。

   • SQL：データスキーマに従ってクエリ文を入力します。詳細はSQLデータスキーマとクエリ文を参照してください。

設定が完了したら、作成 をクリックしてください。

設定項目による設定

EMQXの設定項目を使ってPostgreSQL認証を設定することも可能です。設定パラメータの全リストはEMQX Enterprise設定マニュアルを参照してください。

PostgreSQL認証は mechanism = password_based および backend = postgresql で識別されます。

設定例：

{
  mechanism = password_based
  backend = postgresql

  password_hash_algorithm {
    name = sha256
    salt_position = suffix
  }

  database = mqtt
  username = postgres
  password = public
  server = "127.0.0.1:5432"
  query = "SELECT password_hash, salt, is_superuser FROM users where username = ${username} LIMIT 1"
  query_timeout = "5s"
  connect_timeout = "15s"
  disable_prepared_statements = false
}