MongoDBとの統合

EMQXはパスワード認証のためにMongoDBとの統合をサポートしています。EMQXのMongoDB認証機能は、現在、Single、レプリカセットおよびシャーディングの3つの異なるモードで稼働するMongoDBへの接続をサポートしています。本ページでは、サポートされるデータスキーマの詳細と、EMQXダッシュボードおよび設定ファイルでの設定方法について説明します。

TIP

基本的なEMQX認証の概念の知識が必要です。

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

EMQXのMongoDB認証機能は、認証データをMongoDBドキュメントとして保存することをサポートしています。ユーザーはクエリ文のテンプレートを提供し、以下のフィールドが含まれていることを確認する必要があります。

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

例えば、ユーザー名が user123、パスワードが secret、サフィックスとしてソルト salt_foo123 を付加し、パスワードハッシュが sha256 のスーパーユーザー（is_superuser: true）のドキュメントを追加したい場合、クエリ文は以下のようになります。

> db.mqtt_user.insertOne(
  {
      "username": "emqx_u",
      "salt": "slat_foo123",
      "is_superuser": true,
      "password_hash": "44edc2d57cde8d79c98145003e105b90a14f1460b79186ea9cfe83942fc5abb5"
  }
);
{
  "acknowledged" : true,
  "insertedId" : ObjectId("631989e20a33e26b05b15abe")
}

TIP

システム内に多数のユーザーが存在する場合は、クエリ応答時間を短縮しEMQXの負荷を軽減するために、事前にテーブルの最適化およびインデックス作成を行ってください。

このMongoDBデータスキーマに対応するダッシュボードの設定パラメータは以下の通りです。

• Password Hash: sha256
• Salt Position: suffix
• Collection: mqtt_user
• Filter: { username = "${username}" }
• Password Hash field: password_hash
• Salt Field: salt
• is_superuser Field： is_superuser

ダッシュボードでの設定

EMQXダッシュボードを使ってMongoDBをパスワード認証に利用する設定が可能です。

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

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

   • MongoDB接続情報の入力：

     • MongoDB Mode：MongoDBのデプロイモードを選択します。Single、Replica Set、Sharding のいずれかです。
     • Server：EMQXが接続するMongoDBサーバーのアドレスを指定します。MongoDB Mode が Replica Set または Sharding の場合は、接続するすべてのMongoDBサーバーをカンマ区切りで入力してください。
     • Replica Set Name：レプリカセット名を指定します。文字列型。MongoDB Mode を Replica Set に設定した場合のみ必要です。
     • Database：MongoDBのデータベース名。文字列型。
     • Collection：認証ルールが格納されているMongoDBコレクション名。文字列型。
     • Username：MongoDBのユーザー名を指定します。
     • Password：MongoDBのユーザーパスワードを指定します。
     • Read Mode（任意）：MongoDB Mode が Replica Set の場合のみ必要。デフォルトは master。選択肢は master、slave_ok。
       • master：各クエリは必ず最新のデータ（マスター/プライマリサーバー）から読み取る必要があります。接続先サーバーがマスターでない場合、最初の読み取りは失敗し、その後の操作は中止されます。
       • slave_ok：セカンダリ/スレーブサーバーから古いデータを読み取ることも、マスターから最新データを読み取ることも許可されます。
     • Write Mode（任意）：MongoDB Mode が Replica Set の場合のみ必要。選択肢は unsafe、safe。デフォルトは safe。

   • 認証に関する設定：

     • Password Hash Field：パスワードのフィールド名を指定します。
     • 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進数文字列で表現され、大文字・小文字を区別せずに保存された資格情報と比較されます。
     • Salt Field：MongoDB内のソルトフィールドを指定します。
     • is_superuser Field：ユーザーがスーパーユーザーかどうかを判定します。
     • Client ID Override Field：MongoDB認証結果内のフィールド名を指定し、接続時にクライアントが提供したClient IDを上書きできます。これにより認証データに基づくユニークなClient IDの割り当てが可能となり、マルチテナンシーなどのシナリオでセッション競合を防止できます。
     • Precondition：Variform式で、このMongoDB認証機能をクライアント接続に適用するかどうかを制御します。式はクライアントの属性（username、clientid、listenerなど）に対して評価され、結果が文字列 "true" の場合のみ認証機能が呼び出されます。それ以外の場合はスキップされます。詳細はAuthenticator Preconditionsを参照してください。
     • Enable TLS：TLSを有効にする場合はトグルスイッチをオンにします。TLS有効化の詳細はNetwork and TLSを参照してください。
     • Filter：認証情報検索のためのMongoDBセレクターとして解釈されるマップ。プレースホルダーがサポートされています。
     • Advanced Settings：以下の任意の接続設定を構成します。
       • Auth Source：ユーザーの認証資格情報が格納されているMongoDBデータベースを指定します。例：ユーザーが admin データベースで作成されている場合は admin と入力します。
       • Use Legacy Protocol：EMQXがMongoDBのレガシープロトコルを使用する方法を選択します。auto はサーバーがサポートするプロトコルをEMQXが検出、true はレガシープロトコルを使用、false は使用しません。デフォルトは auto。
       • Connection Pool Size：EMQXノードからMongoDBサーバーへの同時接続数を指定します。デフォルトは 8。
       • Connect Timeout：接続確立までの待機時間を指定します。単位はミリ秒、秒、分、時間がサポートされます。デフォルトは 20 秒。

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

設定項目による設定

EMQXのMongoDB認証機能は設定項目を使っても設定可能です。

以下は参考となるコード例です。

{
  mechanism = password_based
  backend = mongodb

  password_hash_algorithm {
    name = sha256
    salt_position = suffix
  }

  collection = "mqtt_user"
  filter { username = "${username}" }

  mongo_type = single
  server = "127.0.0.1:27017"

  database = "mqtt"
  username = "emqx"
  password = "secret"
}

{
  mechanism = password_based
  backend = mongodb

  password_hash_algorithm {
    name = sha256
    salt_position = suffix
  }

  collection = "mqtt_user"
  filter { username = "${username}" }

  mongo_type = rs
  servers = "10.123.12.10:27017,10.123.12.11:27017,10.123.12.12:27017"
  replica_set_name = "rs0"

  database = "mqtt"
  username = "emqx"
  password = "secret"
}

{
  mechanism = password_based
  backend = mongodb
  enable = true

  password_hash_algorithm {
    name = sha256
    salt_position = suffix
  }

  collection = "mqtt_user"
  filter { username = "${username}" }

  mongo_type = sharded
  servers = "10.123.12.10:27017,10.123.12.11:27017,10.123.12.12:27017"

  database = "mqtt"
  username = "emqx"
  password = "secret"
}