# 多要素認証（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 を有効化します。

::: tip 補足

自身のアカウントに対してダッシュボードから MFA を有効化すると、同一セッション内で即座に MFA セットアップ画面が表示されます（[初回セットアップ](#first-time-setup)参照）。
管理者が他ユーザーに対して MFA を有効化した場合、そのユーザーの次回ログイン時まで MFA は保留されます。

:::

### TOTP シークレットキーのリセット

認証アプリをアンインストールした場合やシークレットキーが漏洩した場合など、ユーザーが TOTP 設定をリセットする必要があるときは、管理者が **MFA Settings** ダイアログからシークレットキーをリセットできます。

1. **System** -> **Users** ページで対象ユーザーを探し、**Actions** 列の **MFA Settings** をクリックします。
2. **MFA Settings** ダイアログ内にある **Reset TOTP Secret Key** ボタンをクリックします。
3. 確認プロンプトが表示され、リセットすると以前のキーが無効になることが通知されます。ユーザーは次回ログイン時に新しい TOTP シークレットキーのセットアップが必要です。
4. **Confirm** をクリックしてリセットを実行します。

リセット後、ユーザーは次回ログイン時に新しい QRコードをスキャンするか、新しいシークレットキーを認証アプリに入力して初期セットアップを行います。

### 設定ファイルおよび REST API から MFA を有効化・管理する

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

::: tip

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

REST API のロールベースアクセス制御の詳細は [Roles and Permissions](../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="mfa_login" style="zoom:70%;" />

### 以降のログイン

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

1. **ユーザー名とパスワードを入力**
   以降のログイン時も、ユーザー名とパスワードを入力します。
2. **TOTP コードを入力**
   パスワード認証後、認証アプリが生成した TOTP コードの入力を求められます。
3. **ログイン成功**
   コードが有効であれば、ダッシュボードにログインできます。
4. **コードが無効な場合**
   コードが誤っているか期限切れの場合はエラーメッセージが表示されます。その場合は認証アプリの最新コードを再入力してください。

## SSO ユーザーに対する強制 MFA

EMQX 5.10 以降、SSO ユーザーに対しても MFA を強制できます。
[シングルサインオン（SSO）](../dashboard/sso.md)（SAML、OIDC、LDAP）を有効化した後、各バックエンドごとに `force_mfa` スイッチをオンにすると、そのバックエンドからのすべてのユーザーに対して IdP 認証に加えて TOTP の第二要素認証を必須にできます。

これは特にパブリックネットワークに公開された EMQX 環境で重要です。上流の IdP で認証情報が漏洩しても、攻撃者はユーザーの認証デバイスを持たなければダッシュボードにアクセスできません。

`force_mfa` は各 SSO バックエンド（`saml`、`oidc`、`ldap`）ごとに独立して設定します。ローカルアカウントには影響しません。各 SSO ユーザーの TOTP シークレットはローカルユーザーとは別に管理されます。管理者は任意の SSO ユーザーに対して MFA の有効化・無効化・リセットが可能です。MFA が無効なユーザーは、バックエンドで `force_mfa = true` が設定されていても TOTP を免除されます。これは緊急用管理者アカウントに便利です。

### SSO バックエンドで強制 MFA を有効化する

`base.hocon` にて、MFA を必須にしたいバックエンドに `force_mfa = true` を追加します。ダッシュボードの SSO 設定 UI からも設定可能です。詳細は [LDAP SSO の設定](../dashboard/sso-ldap.md)、[SAML SSO の設定](../dashboard/sso-saml.md)、[OIDC SSO の設定](../dashboard/sso-oidc.md) を参照してください。

設定例：

```hocon
dashboard {
  sso {
    saml {
      enable = true
      force_mfa = true          # すべての SAML ユーザーはログイン時に TOTP を完了する必要がある
      # ... その他の SAML 設定
    }
    oidc {
      enable = true
      force_mfa = false         # 強制しない。ユーザー単位で有効化可能
      # ... その他の OIDC 設定
    }
    ldap {
      enable = true
      force_mfa = true
      # ... その他の LDAP 設定
    }
  }
}
```

`force_mfa` のデフォルトは `false` で、5.10 以前の動作を維持します。

::: tip
`force_mfa` をオンにしても既存セッションは無効になりません。次回の新規ログイン時に適用されます。
:::

### 個別の SSO ユーザーの MFA 管理

ダッシュボードの **System** -> **Users** で SSO ユーザー一覧を表示できます。ユーザー名の横にバックエンド名が表示されます。**Actions** 列の **MFA Settings** ボタンから以下の操作が可能です。

- **MFA を有効化**：対応バックエンドで `force_mfa` がオフでも、次回ログイン時に TOTP のセットアップと利用を強制します。
- **MFA を無効化**：該当ユーザーを免除し、バックエンドで `force_mfa` がオンでも TOTP をスキップします。緊急用管理者アカウントに便利です。
- **TOTP シークレットのリセット**：現在のシークレットをクリアし、次回ログイン時にセットアップを再度行います。認証デバイスを紛失した場合に利用します。

### MFA を伴う SSO ログインフロー

MFA 強制は SSO ログイン体験を変更しません。

1. 通常通り「SSO でログイン」ボタンをクリックします。
2. IdP で認証を行います。
3. ダッシュボードに戻った後、MFA 対象ユーザーは TOTP コードの入力を求められます。
4. `force_mfa` が有効な初回ログイン時は、QRコードのスキャンやキー入力による一度きりの TOTP セットアップが案内されます。

::: tip セキュリティ注意点
設計上、TOTP 認証に成功するまではダッシュボードのアクセス権限は発行されません。
SSO コールバックリンクを傍受しても MFA を回避できません。
:::

### FAQ

**Q: `force_mfa` を有効化したら、既にログイン中の SSO ユーザーは強制的にログアウトされますか？**
A: いいえ。`force_mfa` は新規ログイン時のみ適用されます。既存セッションは有効のままです。

**Q: 緊急用アカウントの MFA を一時的に無効化するには？**
A: **System** -> **Users** で対象ユーザーの **MFA Settings** を開き、**Disable MFA** をクリックしてください。以降のログインで TOTP がスキップされます。再度有効化またはリセットするまでこの状態が続きます。

**Q: バックエンド全体ではなく、一部の SSO ユーザーのみに MFA を要求できますか？**
A: はい。`force_mfa` は `false` のままにし、対象ユーザーだけを **Users** ページから個別に MFA 有効化してください。