# MySQL 認証

拡張認証では、MySQL 統合によるパスワード認証をサポートしています。

::: tip 注意

MySQL 認証は EMQX サーバレスのデプロイメントではサポートされていません。

:::

## テーブル構造とクエリ文

MySQL 認証器は任意のテーブル構造をサポートでき、複数テーブルの結合クエリやビューからのクエリも可能です。ユーザーはクエリ用の SQL テンプレートを提供し、クエリ結果に以下のフィールドが含まれていることを保証する必要があります。

- `password_hash`：必須。データベース内の平文またはハッシュ化されたパスワードフィールド。
- `salt`：任意。空または存在しない場合は空のソルト（salt = ""）とみなされます。
- `is_superuser`：任意。現在のクライアントがスーパーユーザーかどうかを示します。デフォルトは `false` です。**`true` に設定された場合、そのユーザー名を使用するクライアントは認可制約を受けません。スーパーユーザーの設定は推奨されません。**

テーブル構造の例：

```sql
CREATE TABLE `mqtt_user` (
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,
  `username` varchar(100) DEFAULT NULL,
  `password_hash` varchar(100) DEFAULT NULL,
  `salt` varchar(35) DEFAULT NULL,
  `created` datetime DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `mqtt_username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

::: tip

上記の例では、クエリを支援するために暗黙の `UNIQUE` インデックスフィールド（`username`）を作成しています。ユーザー数が多いシステムでは、クエリに使用するテーブルが最適化され、有効なインデックスを利用して多数の接続時のデータ検索を高速化し、EMQX の負荷を軽減することを確認してください。

:::

このテーブルでは `username` が検索条件として使われます。例えば、ユーザー名 `emqx_u`、パスワード `public`、ソルト `slat_foo123`、ハッシュ方式 `sha256`、スーパーユーザーフラグ `false` のユーザーを追加する場合：

```sql
mysql> INSERT INTO mqtt_user(username, password_hash, salt, is_superuser) VALUES ('emqx_u', SHA2(concat('public', 'slat_foo123'), 256), 'slat_foo123', 0);
Query OK, 1 row affected (0.01 sec)
```

対応するクエリ文とパスワードハッシュ方式の設定パラメータは以下の通りです。

- パスワード暗号化方式：`sha256`
- ソルトモード：`suffix`
- SQL：

```sql
SELECT password_hash, salt, is_superuser FROM mqtt_user WHERE username = ${username} LIMIT 1
```

## MySQL 認証の設定

デプロイメント画面で、**アクセス制御** -> **認証** -> **拡張認証** をクリックし、**MySQL 認証** を選択して **設定** をクリックします。

以下の関連設定を行えます。

- **サーバー**：MySQL サーバーのアドレス（host:port）を入力します。

  ::: tip

  - 現在のデプロイメントが Dedicated Flex エディションの場合は、[VPC ピアリング接続](./vpc_peering.md)を作成し、内部ネットワークアドレスをサーバーアドレスとして使用してください。
  - 現在のデプロイメントが BYOC エディションの場合は、パブリッククラウドコンソールで VPC ピアリング接続を作成してください。詳細は [VPC ピアリング接続の作成](./byoc_vpc_peering.md)を参照し、内部ネットワークアドレスをサーバーアドレスとして使用してください。
  - 「Init resource failure!」というメッセージが表示された場合は、サーバーアドレスが正しいか、セキュリティグループが開放されているかを確認してください。

  :::

- **データベース**：MySQL データベース名を入力します。

- **ユーザー名**（任意）：ユーザー名を入力します。

- **パスワード**（任意）：パスワードを入力します。

- **TLS を有効化**：TLS の有効化設定を行います。

- **接続プールサイズ**（任意）：EMQX ノードから MySQL データベースへの同時接続数を整数で指定します。デフォルト値は `8` です。

- **クエリタイムアウト**：接続のタイムアウト時間を入力します。単位は時間、分、秒、ミリ秒が選択可能です。

- **パスワードハッシュ**：パスワード保存に使用するハッシュアルゴリズムを選択します。例：plain、md5、sha、bcrypt、pbkdf2 など。
  - `plain`、`md5`、`sha`、`sha256`、`sha512` の場合は以下も設定します。
    - **ソルト位置**：ソルトをパスワードとどのように結合するかを指定します。外部ストレージから EMQX 内蔵データベースへの資格情報移行を除き、通常は変更不要です。選択肢は suffix（パスワードの後ろにソルトを追加）、prefix（パスワードの前にソルトを追加）、disable（ソルトを使用しない）です。注：plain を選択した場合はソルトモードを disable に設定してください。
  - `pbkdf2` アルゴリズムの場合は以下も設定します。
    - **疑似乱数関数**：キー生成に使うハッシュ関数を指定します。例：sha256。
    - **反復回数**：ハッシュの繰り返し回数を指定します。デフォルトは 4096。
    - **導出キー長**（任意）：キーの長さを指定します。未指定の場合は疑似乱数関数により決定されます。

- **前提条件**（任意）：1～256 文字の Variform 式を入力し、EMQX がこの認証器をクライアントに対して呼び出すかどうかを制御します。式が文字列 `'true'` と評価された場合のみ認証器が呼び出され、それ以外はスキップされます。この項目は EMQX 6.1 以降のデプロイメントで利用可能です。対応するクライアント属性や例は [認証器の前提条件](./custom_auth.md#authenticator-preconditions) を参照してください。

- **SQL**：テーブル構造に応じたクエリ SQL を記入します。詳細は [SQL テーブル構造とクエリ文](https://docs.emqx.com/en/enterprise/latest/access-control/authn/mysql.html#sql-table-structure-and-query-statements) を参照してください。
