# MongoDBとの統合 EMQXはパスワード認証のためにMongoDBとの統合をサポートしています。EMQXのMongoDB認証機能は、現在、Single、[レプリカセット](https://www.mongodb.com/docs/manual/reference/replica-configuration/)および[シャーディング](https://www.mongodb.com/docs/manual/sharding/)の3つの異なるモードで稼働するMongoDBへの接続をサポートしています。本ページでは、サポートされるデータスキーマの詳細と、EMQXダッシュボードおよび設定ファイルでの設定方法について説明します。 ::: tip [基本的なEMQX認証の概念](./authn.md)の知識が必要です。 ::: ## データスキーマとクエリ文 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** タブが表示されます。 ![authn-MongoDB_ee](./assets/authn-MongoDB_ee.png) 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式](../../configuration/configuration.md#variform-expressions)で、このMongoDB認証機能をクライアント接続に適用するかどうかを制御します。式はクライアントの属性（`username`、`clientid`、`listener`など）に対して評価され、結果が文字列 `"true"` の場合のみ認証機能が呼び出されます。それ以外の場合はスキップされます。詳細は[Authenticator Preconditions](./authn.md#authenticator-preconditions)を参照してください。 - **Enable TLS**：TLSを有効にする場合はトグルスイッチをオンにします。TLS有効化の詳細は[Network and TLS](../../network/overview.md)を参照してください。 - **Filter**：認証情報検索のためのMongoDBセレクターとして解釈されるマップ。[プレースホルダー](./authn.md#authentication-placeholders)がサポートされています。 - **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認証機能は設定項目を使っても設定可能です。 以下は参考となるコード例です。 :::: tabs type:card ::: tab Single mode ```bash { 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" } ``` ::: ::: tab Replica set ```bash { 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" } ``` ::: ::: tab Sharding ```bash { 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" } ``` ::: ::::