# 多要素認証（MFA）

EMQX 5.9.0では、EMQXダッシュボードのセキュリティ強化のために多要素認証（MFA）機能が導入されました。この機能により、ユーザーはログイン時に2段階の認証プロセスを完了する必要があります。このプロセスは、パスワードと時間ベースのワンタイムパスワード（TOTP）を用いてユーザーの本人確認を行うことで、不正アクセスを防止する追加のセキュリティ層を提供します。

本ページでは、EMQXダッシュボードのMFAの設定および利用方法について、ユーザーと管理者の両方の視点から説明します。

## 主要な概念

- **MFA**：ユーザーのパスワードと、認証アプリで生成されるTOTPなどの第二の認証要素の2種類の識別情報を要求するセキュリティ機能です。
- **TOTP**：Google AuthenticatorやAuthyなどの認証アプリによって生成される一時的なコードで、アプリとサーバー間で共有された秘密情報に基づいています。
- **QRコード**：認証アプリのセットアップを簡単にするために、共有秘密情報をグラフィカルに表現したコードです。

## MFAの動作

EMQXダッシュボードでMFAが有効になると、ログインプロセスに追加のセキュリティ層が加わります。MFAの流れは以下の通りです。

1. **ユーザーログイン**：ダッシュボードにログインする際、まず通常通りユーザー名とパスワードを入力します。
2. **MFAプロンプト**：アカウントにMFAが有効な場合、認証アプリ（Google AuthenticatorやAuthyなど）で生成された認証コードの入力を求められます。
3. **初回セットアップ**：MFAを初めて設定する場合は、QRコードをスキャンするか、認証アプリに秘密鍵を手動で入力してセットアップを完了します。
4. **以降のログイン**：初回セットアップ後は、ログインのたびに認証アプリを開き、生成された時間制限付きコードを入力してログインを完了します。

MFAの目的は、たとえパスワードが漏洩しても、認証アプリのコードがなければログインできないようにすることです。

::: tip
アカウントを保護するために、TOTPのセットアップは速やかに完了させることが重要です。  
ご自身のアカウントや他のユーザーのためにTOTPを有効化した後は、できるだけ早くQRコードをスキャンするか秘密鍵を認証アプリに入力してください。  
この手順の遅延は、ログイン情報が漏洩した場合に不正登録のリスクを高める可能性があります。  
:::

## MFAの有効化と設定

MFAはデフォルトで無効になっています。ユーザーに対してMFAを有効化するには、管理者がシステムをMFA対応に設定し、個別ユーザーに対して設定を行う必要があります。MFAの有効化・無効化は[管理者権限](../dashboard/system.md#users)を持つユーザーのみが実施可能です。

### ダッシュボードの全ユーザーに対してMFAをデフォルトで有効化する

すべてのダッシュボードユーザーに対してMFAをデフォルトで有効にするには、管理者は設定ファイルの `dashboard.default_mfa` を以下のように設定します。値は `none`（MFA無効）または `{mechanism: totp}`（TOTPベースのMFA有効）を指定できます。

設定例：

```bash
dashboard.default_mfa = {mechanism: totp}
```

### EMQXダッシュボードからユーザーごとにMFAを有効化する

管理者はダッシュボードから以下の手順でユーザーごとにMFAを有効化できます。

1. ダッシュボードの左メニューから **System** -> **Users** をクリックします。
2. **Users** ページでユーザー一覧が表示されます。対象ユーザーの **Actions** 列にある **MFA Settings** をクリックします。
3. **MFA Settings** ダイアログで **Enable** をクリックし、選択したユーザーのMFAを有効化します。

有効化後、ユーザーは次回ログイン時にMFAセットアップを完了する必要があります。

### TOTP秘密鍵のリセット

認証アプリのアンインストールや秘密鍵の漏洩などによりTOTPの再設定が必要な場合、管理者は **MFA Settings** ダイアログから対象ユーザーのTOTP秘密鍵をリセットできます。

1. **System** -> **Users** ページでリセット対象ユーザーを探し、**Actions** 列の **MFA Settings** をクリックします。
2. **MFA Settings** ダイアログにある **Reset TOTP Secret Key** ボタンをクリックします。

   確認メッセージが表示され、秘密鍵をリセットすると以前の鍵は無効になることが通知されます。ユーザーは次回ログイン時に新しいTOTP秘密鍵のセットアップが必要です。

3. **Confirm** をクリックしてリセットを実行します。リセット後、ユーザーは次回ログイン時に新規セットアップ（新しいQRコードのスキャンまたは秘密鍵の入力）を行います。

### 設定ファイルおよびREST APIによるMFAの有効化・管理

管理者は設定ファイルやREST APIを通じてユーザーのMFAを有効化・管理できます。

::: tip

`/users/{username}/mfa` エンドポイントへのPOSTおよびDELETEメソッドは、管理者または対象ユーザー本人のみが使用可能です。  
つまり、「viewer」ロールのユーザーは他ユーザーのMFA設定を変更できません。現在の認証トークン（ベアラートークン）に紐づくユーザーのみが自身のMFA設定を変更できます。  

REST APIのロールベースアクセス制御の詳細は[Roles and Permissions](../admin/api.md#roles-and-permissions)を参照してください。

:::

#### 特定ユーザーのMFAを有効化する

管理者は以下のリクエストボディを付けて `/users/{username}/mfa` エンドポイントに `POST` リクエストを送信することで、特定ユーザーのMFAを有効化できます。

```json
{
  "mechanism": "totp"
}
```

#### 特定ユーザーのMFAを無効化する

管理者は `/users/{username}/mfa` エンドポイントに `DELETE` リクエストを送信することで、特定ユーザーのMFAを無効化できます。

## MFAを用いたログイン

ユーザーはアカウントにMFAが有効化された後、以下の手順でEMQXダッシュボードにログインします。

### 初回セットアップ

MFA有効化後の初回ログイン時には認証アプリのセットアップが必要です。

1. **ユーザー名とパスワードの入力**  
   ログインページで通常通りユーザー名とパスワードを入力します。

2. **QRコードのスキャンまたはセットアップキーの入力**  
   パスワード認証後、ダッシュボードからQRコードのスキャンまたはセットアップキーの手動入力を求められます。認証アプリにこれらを登録してセットアップを完了してください。

3. **認証アプリのコードを検証**  
   認証アプリが生成する時間制限付きコードを入力し、**Confirm** をクリックして検証します。

   コードは通常30秒程度の有効期限があるため、速やかに入力してください。

<img src="./assets/mfa_login.png" alt="多要素認証ログイン画面" style="zoom:70%;" />

### 以降のログイン

初回セットアップ完了後は、認証アプリを用いてログインします。

1. **ユーザー名とパスワードの入力**  
   以降のログイン時も、まずユーザー名とパスワードを入力します。

2. **TOTPコードの入力**  
   パスワード認証後、認証アプリが生成するTOTPコードの入力を求められます。

3. **ログイン成功**  
   入力したコードが有効であれば、ダッシュボードにログインできます。

4. **コードが無効な場合**  
   コードが誤っているか期限切れの場合はエラーメッセージが表示されます。その場合は認証アプリの最新コードを再度入力してください。