feat(MFA): Add docs for Multi-Factor Authentication

dir.yaml

@@ -543,6 +543,9 @@
         - dashboard/sso-ldap
         - dashboard/sso-saml
         - dashboard/sso-oidc
+    - title_en: Multi-factor Authentication
+      title_cn: 多因素认证
+      path: multi-factor-authn/multi-factor-authentication
     - dashboard/audit-log
     - title_en: Rate Limit
       title_cn: 速率限制

en_US/admin/admin-guide.md

@@ -8,6 +8,7 @@ This Administration Guide is designed to assist administrators and operators in
 - [MQTT Durable Sessions](../durability/management.md) guides you to configure the Durable Sessions feature and set parameters for data replicas for high availability.
 - [EMQX Dashboard](../dashboard/introduction.md) provides a comprehensive introduction to the built-in management console in EMQX. You will learn how to manage and monitor EMQX clusters, configure various features, and utilize the required functionalities.
 - [Single Sign-On (SSO)](../dashboard/sso.md) introduces the mainstream identity services that EMQX integrates with and guides how to configure the SSO based on these services.
+- [Multi-Factor Authentication (MFA)](../multi-factor-authn/multi-factor-authentication.md) explains how to set up and use MFA for the Dashboard login to enhance security.
 - [Audit Log](../dashboard/audit-log.md) introduces how to enable and configure the audit log to track important operation changes in your EMQX cluster in real-time.
 - [Rate Limit](../rate-limit/rate-limit.md) explains how to avoid system overload by configuring rate limiters for connection and messaging speed, ensuring system stability.
 - [Log and Observability](../observability/overview.md) introduces metric observation and monitoring features in EMQX, facilitating system monitoring and debugging.

en_US/admin/api.md

@@ -60,7 +60,7 @@ In the specified file, add multiple API keys in the format `{API Key}:{Secret Ke
 
 - **API Key**: Any string as the key identifier.
 - **Secret Key**: Use a random string as the secret key.
-- **Role (optional)**: Specify the key's [role](#roles-and-permissions), applicable only in the Enterprise edition.
+- **Role (optional)**: Specify the key's [role](#roles-and-permissions).
 
 For example:
 
@@ -74,9 +74,9 @@ API keys created this way are valid indefinitely.
 
 Each time EMQX starts, it will add the data set in the file to the API key list. If an API key already exists, its Secret Key and Role will be updated.
 
-#### Roles and Permissions (Enterprise Edition)
+#### Roles and Permissions
 
-In the EMQX Enterprise edition, the REST API implements role-based access control. When creating an API key, you can assign one of the following three predefined roles:
+In the EMQX Enterprise, the REST API implements role-based access control. When creating an API key, you can assign one of the following three predefined roles:
 
 - **Administrator**: This role can access all resources and is the default value if no role is specified. The corresponding role identifier is `administrator`.
 - **Viewer**: This role can only view resources and data, corresponding to all GET requests in the REST API. The corresponding role identifier is `viewer`.

en_US/multi-factor-authn/multi-factor-authentication.md

@@ -0,0 +1,118 @@
+# Multi-Factor Authentication (MFA) 
+
+EMQX 5.9.0 introduces the Multi-Factor Authentication (MFA) feature for the EMQX Dashboard to enhance security. The feature requires users to complete a two-step authentication process when logging in. This process adds an additional layer of security to prevent unauthorized access by verifying the user's identity using a password and a time-based one-time password (TOTP).
+
+This page explains how to set up and use MFA for the EMQX Dashboard, covering both the user and administrator perspectives.
+
+## Key Concepts
+
+- **MFA**: A security feature that requires two forms of identification: the user's password and a second factor, such as a TOTP generated by an authenticator app.
+- **TOTP**: A temporary code generated by an authenticator app like Google Authenticator or Authy, based on a shared secret between the app and the server.
+- **QR Code**: A graphical representation of the shared secret that can be scanned by an authenticator app to simplify the setup process.
+
+## How MFA Works
+
+When MFA is enabled on the EMQX Dashboard, it enhances the login process by adding an extra layer of security. Here's how the MFA process works:
+
+1. **User Login**: When you attempt to log in to the Dashboard, you'll first enter your username and password as usual.
+2. **MFA Prompt**: If MFA is enabled for your account, you will be prompted to enter a verification code. This code is generated by an authenticator app (like Google Authenticator or Authy) on your mobile device.
+3. **First-Time Setup**: If MFA has never been set up before, you will be asked to scan a QR code or manually enter a secret key into your authenticator app to complete the setup.
+4. **Subsequent Logins**: After the initial setup, each time you log in, you'll need to open your authenticator app and enter the time-sensitive code it generates to complete the login process.
+
+The goal of MFA is to ensure that even if someone obtains your password, they cannot log in to your account without also having access to the code from your authenticator app.
+
+## Enable and Configure MFA
+
+MFA is disabled by default. To enable MFA for users, the administrator must configure the system to support MFA and set it up for individual users. Only users with [administrator privileges](../dashboard/system.md#users) can enable or disable MFA for other users.
+
+### Enable MFA by Default for the Dashboard
+
+To enable MFA for all Dashboard users by default, the administrator needs to configure the `dashboard.default_mfa` setting in the configuration file. This can be set to either `none` (to disable MFA) or `{mechanism: totp}` (to enable TOTP-based MFA).
+
+Example configuration:
+
+```bash
+dashboard.default_mfa = {mechanism: totp}
+```
+
+### Enable MFA for Users via EMQX Dashboard
+
+ Administrators can enable MFA directly from the Dashboard by following these steps:
+
+1. In the Dashboard, click **System** -> **Users** from the left menu.
+2. On the **Users** page, you will see a list of users. In the **Actions** column, click **MFA Settings** next to the specific user for whom you want to enable MFA.
+3. In the **MFA Settings** dialog, click **Enable** to enable MFA for the selected user.
+
+Once enabled, the user will be required to complete the MFA setup process during their next login.
+
+### Reset TOTP Secret Key
+
+In case the user needs to reset their TOTP setup (for example, if the authenticator app is uninstalled or if the secret key has been compromised), the administrator can reset the TOTP secret key for the user via the **MFA Settings** dialog.
+
+1. On the **System** -> **Users** page, locate the user for whom you want to reset the TOTP secret key. In the **Actions** column, click on **MFA Settings** for the selected user.
+
+2. In the **MFA Settings** dialog, you will see the **Reset TOTP Secret Key** button. Clicking this button will initiate the reset process.
+
+   A confirmation prompt will appear, notifying you that resetting the secret key will make the previous key invalid. The user will need to set up a new TOTP secret key during their next login.
+
+3. Click **Confirm** to proceed with the reset. After the reset, the user will need to follow the initial MFA setup process during their next login (scanning a new QR code or entering a new secret key in their authenticator app).
+
+### Enable and Manage MFA via Configuration File and REST API
+
+Administrators can enable or manage MFA for users through the configuration file and REST API.
+
+::: tip
+
+The POST and DELETE methods on the `/users/{username}/mfa` endpoint can only be used by administrators or by the user themselves. This means that a user with a "viewer" role cannot modify another user's MFA settings. Only the user associated with the current authentication token (the "bearer token") can modify their own MFA settings. 
+
+For more information on the role-based access control implementation of the REST API, see [Roles and Permissions](../admin/api.md#roles-and-permissions).
+
+:::
+
+#### Enable MFA for a Specific User
+
+To enable MFA for a specific user, the administrator can send a `POST` request to the `/users/{username}/mfa` API endpoint with the following request body:
+
+```json
+{
+  "mechanism": "totp"
+}
+```
+
+#### Disable MFA for a Specific User
+
+To disable MFA for a specific user, the administrator can send a `DELETE` request to the `/users/{username}/mfa` API endpoint.
+
+## Log In Using MFA
+
+As a user, once MFA is enabled for your account, you will need to follow these steps to log in to the EMQX Dashboard:
+
+### First-Time Setup
+
+When you log in for the first time after MFA has been enabled, you'll need to set up your authenticator app.
+
+1. **Enter Your Username and Password**:
+   On the login page, enter your username and password as usual.
+
+2. **Scan the QR Code or Enter Setup Key**:
+   After the initial password verification, the Dashboard will prompt you to scan a QR code or manually enter a setup key into your authenticator app to complete setup.
+
+3. **Verify the code from the app**:
+   The app will generate time-sensitive codes for future logins. Enter the code from the app for verification and click **Confirm**.
+
+   The code is valid only for a short period of time (usually 30 seconds), so make sure to enter it quickly.
+
+<img src="./assets/mfa_login.png" alt="mfa_login" style="zoom:70%;" />
+
+### Subsequent Logins
+
+After you've completed the initial setup, you can use the authenticator app to log in.
+
+1. **Enter Your Username and Password**:
+   On subsequent login attempts, enter your username and password.
+2. **Enter the TOTP Code**:
+   Once your password is verified, you will be prompted to enter the TOTP code generated by your authenticator app.
+3. **Successful Login**:
+   If the code is valid, you will be logged into the Dashboard.
+4. **Invalid Code**:
+   If the code is incorrect or expired, you will see an error message. In this case, you can try entering the current code from your authenticator app.

zh_CN/admin/admin-guide.md

@@ -7,6 +7,7 @@
 - [MQTT 会话持久化](../durability/management.md)指导您如何配置和管理会话持久化功能以及如何为高可用性数据副本设置参数。
 - [EMQX Dashboard](../dashboard/introduction.md) 为您全面介绍 EMQX 内置的管理控制台，您将了解如何管理和监控 EMQX 集群并配置和使用所需的各项功能。
 - [单点登录](../dashboard/sso.md)介绍了 EMQX 支持的几种主流身份服务提供商，以及如何在 Dashboard 中配置基于这些服务的单点登录功能。
+- [多因素认证](../multi-factor-authn/multi-factor-authentication.md) 介绍了如何设置和使用多因素认证登录 EMQX Dashboard 以提升安全性。
 - [审计日志](../dashboard/audit-log.md)介绍了如何启用和配置审计日志功能来实时追踪 EMQX 集群的重要操作变更。
 - [速率限制](../rate-limit/rate-limit.md)介绍了如何通过配置消息接入速度限制器避免系统过载，从而保证系统稳定。
 - [日志及可观测性](../observability/overview.md)介绍了 EMQX 中的指标观测和监控功能，便于您进行系统监控和调试。

zh_CN/multi-factor-authn/multi-factor-authentication.md

@@ -0,0 +1,111 @@
+# 多因素认证
+
+EMQX 5.9.0 引入了用于 EMQX Dashboard 的多因素认证（MFA）功能，以增强安全性。此功能要求用户在登录时完成两步认证过程。该过程通过使用密码和基于时间的一次性密码（TOTP）验证用户身份，为系统增加了额外的安全层，防止未经授权的访问。
+
+本页同时从管理员和用户的角度出发解释了如何为 EMQX Dashboard 设置和使用 MFA。
+
+## 关键概念
+
+- **MFA**：一种安全功能，要求提供两种身份验证方式：用户的密码和第二种因素，如由身份验证器应用生成的TOTP。
+- **TOTP**：由身份验证应用程序（如 Google Authenticator 或 Authy）生成的临时验证码，基于应用程序与服务器之间共享的密钥。
+- **二维码**：共享密钥的图形表示，可以通过身份验证应用程序扫描以简化设置过程。
+
+## MFA 如何工作
+
+当 EMQX Dashboard 启用 MFA 时，它通过增加额外的安全层来增强登录过程。以下是 MFA 的工作原理：
+
+1. **用户登录**：当您尝试登录 Dashboard 时，首先输入您的用户名和密码。
+2. **MFA 提示**：如果您的账户启用了 MFA，系统将提示您输入验证码。此验证码由您手机上的身份验证应用程序生成。
+3. **首次设置**：如果之前没有设置 MFA，系统将要求您扫描二维码或手动输入密钥，将其添加到您的身份验证应用程序中，完成设置。
+4. **后续登录**：完成首次设置后，每次登录时，您需要打开身份验证应用程序并输入它生成的时效性验证码来完成登录过程。
+
+MFA 的目标是确保即使有人获得了您的密码，也无法登录您的账户，因为他们还需要访问您身份验证应用程序中生成的验证码。
+
+## 启用和配置 MFA
+
+MFA 默认为禁用状态。要为用户启用 MFA，管理员必须配置系统以支持 MFA，并为各个用户设置它。只有具有[管理员权限](../dashboard/system.md#用户)的用户才能为其他用户启用或禁用 MFA。
+
+### 默认启用 MFA
+
+要为 Dashboard 所有的用户默认开启 MFA，管理员需要在配置文件中配置 `dashboard.default_mfa` 设置。该设置可以设置为 `none`（禁用 MFA）或 `{mechanism: totp}`（启用基于 TOTP 的 MFA）。
+
+示例配置：
+
+```bash
+dashboard.default_mfa = {mechanism: totp}
+```
+
+### 通过 EMQX Dashboard 启用 MFA
+
+管理员可以直接通过 Dashboard 启用 MFA，步骤如下：
+
+1. 在 Dashboard 中，点击左侧菜单的**系统设置** -> **用户**。
+2. 在**用户**页面中，您将看到一个用户列表。在**操作**列中，点击您要为其启用 MFA 的用户旁边的 **MFA 设置**。
+3. 在 **MFA 设置**对话框中，点击**启用 MFA** 以为所选用户启用 MFA。
+
+启用后，用户将在下次登录时需要完成 MFA 设置过程。
+
+### 重置 TOTP 密钥
+
+如果用户需要重置其 TOTP 设置（例如，如果身份验证应用程序被卸载或密钥被泄露），管理员可以通过 **MFA 设置**对话框重置该用户的 TOTP 密钥。
+
+1. 在**系统设置** -> **用户**页面中，找到您要重置 TOTP 密钥的用户。在**操作**列中，点击该用户旁边的 **MFA 设置**。
+
+2. 在 **MFA 设置**对话框中，您将看到**重置 TOTP 密钥**按钮。点击该按钮将启动重置过程。
+
+   会出现一个确认提示，通知您重置密钥将使之前的密钥无效。用户将在下次登录时需要设置一个新的 TOTP 密钥。
+
+3. 点击**确定**以继续重置。重置后，用户将在下次登录时需要遵循首次 MFA 设置过程（扫描新的二维码或将新密钥输入到身份验证应用程序中）。
+
+### 通过配置文件和 REST API 启用和管理 MFA
+
+管理员可以通过配置文件和 REST API 启用或管理用户的 MFA。
+
+::: tip
+
+在 `/users/{username}/mfa` 端点上使用 POST 和 DELETE 方法时，仅管理员或当前身份验证令牌（即“Bearer token”）的所有者可以使用此接口。也就是说，具有“查看者”角色的用户无法修改其他用户的 MFA 设置。只有与当前身份验证令牌关联的用户（“Bearer token”拥有者）才能修改自己的 MFA 设置。
+
+有关基于角色的访问控制（RBAC）的更多信息，请参见[用户](../admin/api.md#角色与权限)。
+
+:::
+
+#### 启用特定用户的 MFA
+
+要为特定用户启用 MFA，管理员可以向 `/users/{username}/mfa` API 端点发送 POST 请求，请求体如下：
+
+```json
+{
+  "mechanism": "totp"
+}
+```
+
+#### 停用特定用户的 MFA
+
+要为特定用户停用 MFA，管理员可以向 `/users/{username}/mfa` API 端点发送 DELETE 请求。
+
+## 使用 MFA 登录
+
+当 MFA 为您的账户启用后，您需要按照以下步骤登录 EMQX Dashboard：
+
+### 首次设置
+
+在首次登录并启用 MFA 后，您需要设置身份验证应用程序。
+
+1. **输入您的用户名和密码**： 在登录页面，按通常方式输入您的用户名和密码。
+
+2. **扫描二维码或输入设置密钥**： 在初步验证密码后，Dashboard 将提示您扫描二维码或手动将设置密钥输入到您的身份验证应用程序中以完成设置。
+
+3. **验证应用程序中的代码**： 应用程序将生成未来登录的时效性验证码。输入应用程序中的验证码并点击**确定**。
+
+   该验证码仅在短时间内有效（通常为 30 秒），因此请确保快速输入。
+
+<img src="./assets/mfa_login.png" alt="mfa_login" style="zoom:70%;" />
+
+### 后续登录
+
+完成初次设置后，您可以使用身份验证应用程序登录。
+
+1. **输入您的用户名和密码**： 在后续的登录尝试中，输入您的用户名和密码。
+2. **输入 TOTP 代码**： 验证密码后，系统会提示您输入由身份验证应用程序生成的 TOTP 代码。
+3. **成功登录**： 如果验证码有效，您将成功登录 Dashboard。
+4. **验证码无效**： 如果验证码错误或过期，您将看到一条错误消息。在这种情况下，您可以尝试重新输入当前身份验证应用程序中的验证码。