From caacc059932afde40a2d4e311e47770940965935 Mon Sep 17 00:00:00 2001
From: Meggielqk <126552073+Meggielqk@users.noreply.github.com>
Date: Tue, 1 Jul 2025 11:05:09 +0800
Subject: [PATCH 1/3] feat(dashboard): Dashboard support token-based login
 (5.10)

---
 en_US/dashboard/introduction.md | 48 +++++++++++++++++++++++++++++++
 zh_CN/dashboard/introduction.md | 50 +++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+)

diff --git a/en_US/dashboard/introduction.md b/en_US/dashboard/introduction.md
index c0bdda66a..ed149bb59 100644
--- a/en_US/dashboard/introduction.md
+++ b/en_US/dashboard/introduction.md
@@ -58,6 +58,54 @@ For users who have installed EMQX for the first time, you can use the default us
 
 After logging in for the first time, the system will automatically detect that you are logging in with the default username and password. It will force you to change the default password, which is good for the security of accessing the Dashboard. Note that the changed password cannot be the same as the original password, and it is not recommended to use `public` as the login password again.
 
+### Token-Based Login via URL
+
+Starting from EMQX 5.6.0, the Dashboard supports a token-based login method that allows users to log in directly by embedding authentication information in the URL.
+
+This feature is particularly useful for seamless redirection and integration scenarios where a user should be logged in automatically without entering credentials manually.
+
+#### How To Use This Login Method
+
+1. Call the `/login` API to obtain the login token and related information.
+
+2. Manually add the username used during login (not included in the `/login` response).
+
+3. Combine the data into a JSON structure:
+
+   ```json
+   {
+     "license": {
+       "edition": "ee"
+     },
+     "role": "administrator",
+     "token": "xxx.jwt.token",
+     "version": "5.5.0-g0fef19f8",
+     "username": "admin"
+   }
+   ```
+
+4. Convert the JSON string to Base64.
+
+5. Embed the encoded string in the `login_meta` query parameter of the Dashboard URL.
+
+#### Example URL
+
+For versions **before 5.6.0**:
+
+```bash
+http://localhost:18083?login_meta=BASE64_ENCODED_STRING
+```
+
+Redirects to the default cluster overview page.
+
+For **version 5.6.0 and later**, you can also specify a target page:
+
+```bash
+http://localhost:18083/#/dashboard/overview?login_meta=BASE64_ENCODED_STRING
+```
+
+This method provides a smooth, pre-authenticated user experience for accessing the EMQX Dashboard. Make sure to handle the token securely and ensure it has appropriate expiration and scope limits.
+
 ### Reset Password
 
 You can reset your Dashboard login password via the `admins` command. For details, see [CLI - admins](../admin/cli.md#admins).
diff --git a/zh_CN/dashboard/introduction.md b/zh_CN/dashboard/introduction.md
index 5c4d1c83b..9391d7752 100644
--- a/zh_CN/dashboard/introduction.md
+++ b/zh_CN/dashboard/introduction.md
@@ -58,6 +58,56 @@ EMQX Dashboard 是一个 Web 应用程序，默认监听 `18083` 端口。下载
 
 首次登录后，系统会自动检测到您正在使用默认用户名和密码登录，并会强制要求修改默认密码，这有利于访问 Dashboard 的安全性提升，注意修改的密码不能与原密码相同，且不建议再次使用 `public` 做为登录密码。
 
+### 通过 URL Token 登录 Dashboard
+
+从 EMQX 5.6.0 开始，Dashboard 支持通过在 URL 中携带登录信息的方式进行免登录访问。
+
+此功能适用于需要无缝跳转或集成场景，可在无需用户手动输入凭据的情况下，自动登录 Dashboard。
+
+#### 使用方法
+
+使用此登录方式的步骤如下：
+
+1. 调用 `/login` 接口，获取登录返回的 token 及相关信息。
+
+2. 手动添加登录时使用的用户名（该字段不包含在接口返回中）。
+
+3. 将数据整理成如下 JSON 结构：
+
+   ```json
+   {
+     "license": {
+       "edition": "ee"
+     },
+     "role": "administrator",
+     "token": "xxx.jwt.token",
+     "version": "5.5.0-g0fef19f8",
+     "username": "admin"
+   }
+   ```
+
+4. 将 JSON 字符串进行 Base64 编码。
+
+5. 将编码后的字符串通过 `login_meta` 参数附加到 Dashboard 的访问 URL 中。
+
+#### 示例 URL
+
+**5.6.0 以下版本**：
+
+```bash
+http://localhost:18083?login_meta=BASE64_ENCODED_STRING
+```
+
+将默认跳转至集群总览页面。
+
+**5.6.0 及以上版本**，可指定跳转页面：
+
+```bash
+http://localhost:18083/#/dashboard/overview?login_meta=BASE64_ENCODED_STRING
+```
+
+通过该方式，可以为用户提供无需手动登录的便捷访问体验。请确保妥善管理 token 的安全性，建议设置合理的过期时间和访问权限范围。
+
 ### 忘记密码
 
 如果您忘记了 Dashboard 登录密码，可以通过 CLI 的 `admins` 命令进行重置，详情请参考 [命令行 - admins](../admin/cli.md#admins)：

From 2fd161009d2404f6706593555c37aab281fb7b60 Mon Sep 17 00:00:00 2001
From: Meggielqk <126552073+Meggielqk@users.noreply.github.com>
Date: Thu, 3 Jul 2025 09:58:00 +0800
Subject: [PATCH 2/3] Combine steps

---
 en_US/dashboard/introduction.md | 49 +++++++++++++------------------
 zh_CN/dashboard/introduction.md | 51 ++++++++++++++-------------------
 2 files changed, 41 insertions(+), 59 deletions(-)

diff --git a/en_US/dashboard/introduction.md b/en_US/dashboard/introduction.md
index ed149bb59..1e9f17b6e 100644
--- a/en_US/dashboard/introduction.md
+++ b/en_US/dashboard/introduction.md
@@ -66,43 +66,34 @@ This feature is particularly useful for seamless redirection and integration sce
 
 #### How To Use This Login Method
 
-1. Call the `/login` API to obtain the login token and related information.
-
-2. Manually add the username used during login (not included in the `/login` response).
-
-3. Combine the data into a JSON structure:
-
-   ```json
-   {
-     "license": {
-       "edition": "ee"
-     },
-     "role": "administrator",
-     "token": "xxx.jwt.token",
-     "version": "5.5.0-g0fef19f8",
-     "username": "admin"
-   }
-   ```
+1. Use the `/login` endpoint to obtain an authentication token. Since the response does not include the username, you will need to manually add it before encoding the full JSON payload.
 
-4. Convert the JSON string to Base64.
+   You can perform all steps, including requesting the token, injecting the username, and encoding the result in Base64, in a single command, as shown below:
 
-5. Embed the encoded string in the `login_meta` query parameter of the Dashboard URL.
+   ```
+   curl -s -X POST "http://127.0.0.1:18083/api/v5/login" \
+     -H 'accept: application/json' \
+     -H 'Content-Type: application/json' \
+     -d '{"username": "admin","password": "public"}' | jq '.username = "admin"' | base64
+   ```
 
-#### Example URL
+2. Construct the login URL. Embed the encoded string in the `login_meta` query parameter of the Dashboard URL. For example:
 
-For versions **before 5.6.0**:
+   For EMQX versions **before 5.6.0**:
 
-```bash
-http://localhost:18083?login_meta=BASE64_ENCODED_STRING
-```
+   ```bash
+   http://localhost:18083?login_meta=BASE64_ENCODED_STRING
+   ```
 
-Redirects to the default cluster overview page.
+   This redirects to the default cluster overview page.
 
-For **version 5.6.0 and later**, you can also specify a target page:
+   For EMQX **version 5.6.0 and later**:
 
-```bash
-http://localhost:18083/#/dashboard/overview?login_meta=BASE64_ENCODED_STRING
-```
+   ```bash
+   http://localhost:18083/#/dashboard/overview?login_meta=BASE64_ENCODED_STRING
+   ```
+
+   This allows specifying the target page after login.
 
 This method provides a smooth, pre-authenticated user experience for accessing the EMQX Dashboard. Make sure to handle the token securely and ensure it has appropriate expiration and scope limits.
 
diff --git a/zh_CN/dashboard/introduction.md b/zh_CN/dashboard/introduction.md
index 9391d7752..3c18616c6 100644
--- a/zh_CN/dashboard/introduction.md
+++ b/zh_CN/dashboard/introduction.md
@@ -68,45 +68,36 @@ EMQX Dashboard 是一个 Web 应用程序，默认监听 `18083` 端口。下载
 
 使用此登录方式的步骤如下：
 
-1. 调用 `/login` 接口，获取登录返回的 token 及相关信息。
-
-2. 手动添加登录时使用的用户名（该字段不包含在接口返回中）。
-
-3. 将数据整理成如下 JSON 结构：
-
-   ```json
-   {
-     "license": {
-       "edition": "ee"
-     },
-     "role": "administrator",
-     "token": "xxx.jwt.token",
-     "version": "5.5.0-g0fef19f8",
-     "username": "admin"
-   }
-   ```
+1. 使用 `/login` 接口获取身份验证 token。由于返回结果中不包含用户名，你需要手动将用户名添加到 JSON 数据中，再进行编码。
 
-4. 将 JSON 字符串进行 Base64 编码。
+   你可以通过以下命令一步完成所有操作，包括请求 token、添加用户名，以及将结果进行 Base64 编码：
 
-5. 将编码后的字符串通过 `login_meta` 参数附加到 Dashboard 的访问 URL 中。
+   ```
+   curl -s -X POST "http://127.0.0.1:18083/api/v5/login" \
+     -H 'accept: application/json' \
+     -H 'Content-Type: application/json' \
+     -d '{"username": "admin","password": "public"}' | jq '.username = "admin"' | base64
+   ```
 
-#### 示例 URL
+2. 构造登录 URL。将编码后的字符串嵌入到 Dashboard URL 的 `login_meta` 查询参数中。例如：
 
-**5.6.0 以下版本**：
+   对于 **EMQX 5.6.0 之前的版本**：
 
-```bash
-http://localhost:18083?login_meta=BASE64_ENCODED_STRING
-```
+   ```bash
+   http://localhost:18083?login_meta=BASE64_ENCODED_STRING
+   ```
 
-将默认跳转至集群总览页面。
+   该方式会跳转至默认的集群概览页面。
 
-**5.6.0 及以上版本**，可指定跳转页面：
+   对于 **EMQX 5.6.0 及以上版本**：
 
-```bash
-http://localhost:18083/#/dashboard/overview?login_meta=BASE64_ENCODED_STRING
-```
+   ```bash
+   http://localhost:18083/#/dashboard/overview?login_meta=BASE64_ENCODED_STRING
+   ```
+
+   该方式支持在登录后跳转到指定页面。
 
-通过该方式，可以为用户提供无需手动登录的便捷访问体验。请确保妥善管理 token 的安全性，建议设置合理的过期时间和访问权限范围。
+通过 URL Token 登录的方式，可以为用户提供无需手动登录的便捷访问体验。请确保妥善管理 token 的安全性，建议设置合理的过期时间和访问权限范围。
 
 ### 忘记密码
 

From 78c87865238335d9ac2854f6ae6ac95596fb5c3d Mon Sep 17 00:00:00 2001
From: Meggielqk <126552073+Meggielqk@users.noreply.github.com>
Date: Thu, 3 Jul 2025 10:01:36 +0800
Subject: [PATCH 3/3] Update zh_CN/dashboard/introduction.md

---
 zh_CN/dashboard/introduction.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/zh_CN/dashboard/introduction.md b/zh_CN/dashboard/introduction.md
index 3c18616c6..f7114983a 100644
--- a/zh_CN/dashboard/introduction.md
+++ b/zh_CN/dashboard/introduction.md
@@ -97,7 +97,7 @@ EMQX Dashboard 是一个 Web 应用程序，默认监听 `18083` 端口。下载
 
    该方式支持在登录后跳转到指定页面。
 
-通过 URL Token 登录的方式，可以为用户提供无需手动登录的便捷访问体验。请确保妥善管理 token 的安全性，建议设置合理的过期时间和访问权限范围。
+通过 URL 携带 token 登录的方式，可以为用户提供无需手动登录的便捷访问体验。请确保妥善管理 token 的安全性，建议设置合理的过期时间和访问权限范围。
 
 ### 忘记密码