add entra id sso

en_US/dashboard/sso-oidc.md

@@ -10,13 +10,67 @@ Be familiar with the basic concepts of [Single Sign-On (SSO)](./sso.md).
 
 ## Supported OIDC provider
 
-The EMQX Dashboard can integrate with identity services that support the OIDC protocol to enable OIDC-based SSO, such as [Okta](https://www.okta.com/).
+The EMQX Dashboard can integrate with identity services that support the OIDC protocol to enable OIDC-based SSO, such as:
+
+- [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id)
+- [Okta](https://www.okta.com/)
+
+## Configure SSO by Integrating with Microsoft Entra ID
+
+This section guides you on how to use Microsoft Entra ID as an Identity Provider (IdP) and configure SSO. You need to complete configurations on both the Microsoft and EMQX Dashboard sides.
+
+### Step 1: Enable OIDC in the EMQX Dashboard
+
+1. In the EMQX Dashboard, navigate to **System** -> **SSO**.
+2. Click the **Enable** button on the **OIDC** card.
+
+### Step 2: Register an Application to Integrate with Microsoft Entra ID
+
+1. Log in to the [MS Azure Portal](https://portal.azure.com/) as an administrator.
+
+2. Go to **Microsoft Entra ID** -> **Enterprise Applications** -> **New Application** and click **Create your own application**.
+
+   <img src="./assets/entra_id_create_own_app.png" alt="entra_id_create_own_app" style="zoom:50%;" />
+
+3. Enter the application name, for example, `EMQX Dashboard`, select **Register an application to integrate with Microsoft Entra ID (App you're developing)**, and click **Create**.
+
+   <img src="./assets/entra_id_oidc_app_parameters.png" alt="entra_id_oidc_app_parameters" style="zoom:50%;" />
+
+4. On the **Register an application** page, select which account types you want to be supported, and configure **Redirect URL** using the information provided by the EMQX Dashboard in **Step 1**:
+
+   - **Redirect URL**: Select `Web` and enter the **Sign-in Redirect URI** provided in the Dashboard, such as `http://localhost:18083/api/v5/sso/oidc/callback`.
+
+5. Go to **Certificates and Secrets** -> **Client secrets** tab, click **New client secret**, enter a description, select an expiration period, and click **Add**. Copy the generated secret value, as you will need it in **Step 3**.
+
+### Step 3: Complete the EMQX Dashboard Configuration
+
+1. On the configuration page, enter the following information:
+   - **Provider**: Leave `Generic`.
+
+   - **Issuer URL**: This corresponds to **OpenID Connect metadata document**, which you can find in the **Endpoints** tab of application overview page in **Step 2**, but without `/.well-known/openid-configuration` part because EMQX adds this automatically, e.g.`https://login.microsoftonline.com/<tenant_id>/v2.0`, where `<tenant_id>` is your Directory (tenant) ID.
+
+   - **Client ID**: This corresponds to **Application (client) ID** found on the application overview page in **Step 2**.
+
+     <img src="./assets/entra_id_oidc_app_config.png" alt="entra_id_oidc_app_config" style="zoom:50%;" />
+
+   - **Client Secret**: Use the secret value generated in **Step 2**.
+
+   - **Dashboard Address**: Enter the base URL where users can access the Dashboard, such as `http://localhost:18083`. This address will be automatically combined to generate the **SSO Address** and **Metadata Address** for configuration on the IdP side.
+
+     <img src="./assets/entra_id_oidc_dashboard.png" alt="entra_id_oidc_dashboard" style="zoom:50%;" />
+
+2. Click **Update** to finish the configuration.
 
 ## Configure SSO by Integrating with Okta 
 
 This section guides you on how to use Okta as an Identity Provider (IdP) and configure SSO. You need to complete configurations on both the Okta and EMQX Dashboard sides.
 
-### Step 1: Add an OIDC Application to Okta's Application Catalog
+### Step 1: Enable OIDC in the EMQX Dashboard
+
+1. In the EMQX Dashboard, navigate to **System** -> **SSO**.
+2. Click the **Enable** button on the **OIDC** card.
+
+### Step 2: Add an OIDC Application to Okta's Application Catalog
 
 1. Log in to Okta as an administrator and go to the **Okta Admin Console**.
 
@@ -26,27 +80,24 @@ This section guides you on how to use Okta as an Identity Provider (IdP) and con
 
 4. On the **General Settings** tab, enter your application name, for example, `EMQX Dashboard`. Click **Next**.
 
-5. On the **LOGIN** tab, configure the settings using the information provided by the EMQX Dashboard in **Step 2**:
+5. On the **LOGIN** tab, configure the settings using the information provided by the EMQX Dashboard in **Step 1**:
 
-   - **Sign-in redirect URIs**: Enter the **Sign-in Redirect URI** provided in the Dashboard, such as `http://localhost:18083/api/v5/sso/oidc/callback`. You can update this URI later after completing **Step 2** if needed.
+   - **Sign-in redirect URIs**: Enter the **Sign-in Redirect URI** provided in the Dashboard, such as `http://localhost:18083/api/v5/sso/oidc/callback`.
    - Additional settings are optional and can be configured according to your specific requirements.
 
 6. Review the settings and click **Save**.
 
 For more detailed instructions, refer to the [Okta documentation](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm).
 
-### Step 2: Enable OIDC in the EMQX Dashboard
+### Step 3: Complete the EMQX Dashboard Configuration
 
-1. In the EMQX Dashboard, navigate to **System** -> **SSO**.
-2. Click the **Enable** button on the **OIDC** card.
-3. On the configuration page, enter the following information:
+1. On the configuration page, enter the following information:
    - **Provider**: Choose `Okta` or select `Generic` for other providers.
    - **Issuer URL**: This is the URL of your Okta authorization server, e.g., `https://example-org.okta.com`.
-   - **Client ID**: Copy it from the application created in **Step 1**.
-   - **Client Secret**: Copy it from the application created in **Step 1**.
+   - **Client ID**: Copy it from the application created in **Step 2**.
+   - **Client Secret**: Copy it from the application created in **Step 2**.
    - **Dashboard Address**: Enter the base URL where users can access the Dashboard, such as `http://localhost:18083`. This address will be automatically combined to generate the **SSO Address** and **Metadata Address** for configuration on the IdP side.
-
-4. Click **Update** to finish the configuration.
+2. Click **Update** to finish the configuration.
 
 ## Login and User Management
 

en_US/dashboard/sso-saml.md

@@ -12,11 +12,56 @@ Be familiar with the basic concepts of [Single Sign-On (SSO)](./sso.md).
 
 The EMQX Dashboard can integrate with identity services that support the SAML 2.0 protocol to enable SAML-based SSO, such as:
 
+- [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id)
 - [Okta](https://www.okta.com/)
 - [OneLogin](https://www.onelogin.com/)
 
 Other identity providers are in the process of integration and will be supported in future versions.
 
+## Configure SSO by Integrating with Microsoft Entra ID
+
+This section guides you on how to use Microsoft Entra ID as an Identity Provider (IdP) and configure SSO. You need to complete configurations on both the Microsoft and EMQX Dashboard sides.
+
+### Step 1: Enable SAML SSO in EMQX Dashboard
+
+1. Go to **System** -> **SSO** in the Dashboard.
+2. Click the **Enable** button on the **SAML 2.0** card.
+3. On the configuration page, enter the following information:
+   - **Dashboard Address**: Ensure users can access the actual access address of the Dashboard, without specifying a specific path. For example, `http://localhost:18083`. This address will be automatically concatenated to generate the **SSO Address** and **Metadata Address** for IdP-side configuration.
+   - **SAML Metadata URL**: Leave it temporarily blank and wait for Step 2 configuration.
+
+### Step 2: Register an Application to Integrate with Microsoft Entra ID
+
+1. Log in to the [MS Azure Portal](https://portal.azure.com/) as an administrator.
+
+2. Go to **Microsoft Entra ID** -> **Enterprise Applications** -> **New Application** and click **Create your own application**.
+
+   <img src="./assets/entra_id_create_own_app.png" alt="entra_id_create_own_app" style="zoom:50%;" />
+
+3. Enter the application name, for example, `EMQX Dashboard`, select **Integrate any other application you don't find in the gallery (Non-gallery)**, and click **Create**.
+
+   <img src="./assets/entra_id_saml_app_parameters.png" alt="entra_id_saml_app_parameters" style="zoom:50%;" />
+
+4. Click **Assign users and groups** to assign users and groups who can access the EMQX Dashboard application.
+5. Go to the **Single sign-on** tab, select **SAML**, and click the **Edit** button in the **Basic SAML Configuration** section.
+6. Configure the following information provided in the Dashboard in Step 1:
+
+   - **Identifier (Entity ID)**: Enter the **Metadata Address** provided in the Dashboard, for example, `http://localhost:18083/api/v5/sso/saml/metadata`.
+   - **Reply URL (Assertion Consumer Service URL)**: Enter the **SSO Address** provided in the Dashboard, for example, `http://localhost:18083/api/v5/sso/saml/acs`.
+
+   Other information is optional and can be configured based on your actual requirements.
+7. Click **Save** to save the configuration.
+
+### Step 3: Complete EMQX Dashboard Configuration
+
+1. In Microsoft Entra ID, go to the **Single sign-on** tab of the created application, and copy **App Federation Metadata Url** in the **Token Signing Certificate** section.
+
+   <img src="./assets/entra_id_saml_metadata_url.png" alt="entra_id_saml_metadata_url" style="zoom:50%;" />
+
+2. In the Dashboard, paste the copied URL into the **SAML Metadata URL** in Step 1.
+
+3. Click **Update** to finish the configuration.
+
 ## Configure SSO by Integrating with Okta 
 
 This section guides you on how to use Okta as an Identity Provider (IdP) and configure SSO. You need to complete configurations on both the Okta and EMQX Dashboard sides.

zh_CN/dashboard/sso-oidc.md

@@ -10,7 +10,56 @@
 
 ## 支持的 OIDC 身份服务
 
-EMQX Dashboard 可以与支持 OIDC 协议的身份服务集成，以启用基于 OIDC 的单点登录，例如 [Okta](https://www.okta.com/)。
+EMQX Dashboard 可以与支持 OIDC 协议的身份服务集成，以启用基于 OIDC 的单点登录，例如
+
+- [Microsoft Entra ID](https://www.microsoft.com/zh-cn/security/business/identity-access/microsoft-entra-id)
+- [Okta](https://www.okta.com/)
+
+## 通过集成 Microsoft Entra ID 配置 SSO
+
+本节将指导你如何使用 Microsoft Entra ID 作为身份提供商（IdP）并配置 SSO。您需要分别完成 IdP 侧与 EMQX Dashboard 侧的配置。
+
+### 步骤 1：在 EMQX Dashboard 中启用 OIDC
+
+1. 在 EMQX Dashboard 中，导航到**系统设置** -> **单点登录**。
+2. 点击 **OIDC** 卡片上的**启用**按钮。
+
+### 步骤 2：注册一个应用以集成 Microsoft Entra ID
+
+1. 以管理员身份登录 [MS Azure Portal](https://portal.azure.com/)。
+
+2. 进入 **Microsoft Entra ID** -> **企业应用程序** -> **新建应用程序**并点击**创建你自己的应用程序**。
+
+   <img src="./assets/entra_id_create_own_app.png" alt="entra_id_create_own_app" style="zoom:50%;" />
+
+3. 输入应用名称，例如 `EMQX Dashboard`，选择**注册应用程序以将其与 Microsoft Entra ID (你正在部署的应用)集成**，然后点击**创建**。
+
+   <img src="./assets/entra_id_oidc_app_parameters.png" alt="entra_id_oidc_app_parameters" style="zoom:50%;" />
+
+4. 在**注册应用程序**页面中，选择你希望支持的账户类型，并根据 EMQX Dashboard 在**步骤 1** 中提供的信息配置**重定向 URL**：
+
+   - **重定向 URL**：选择 `Web` 并输入 Dashboard 提供的**登录重定向地址**，例如 `http://localhost:18083/api/v5/sso/oidc/callback`。
+
+5. 进入**证书和密码** -> **客户端密码**标签页，点击**新建客户端密码**，输入描述信息，选择过期时间，并点击**添加**。复制生成的密码值，因为你将在**步骤 3**中用到它。
+
+### 步骤 3：完成 EMQX Dashboard 配置
+
+1. 在配置页面中，输入以下信息：
+   - **提供商**：保持为 `通用`。
+
+   - **签发者 URL**：对应 **OpenID Connect 元数据文档**，你可以在**步骤 2** 的应用概览页面的**终结点**标签中找到它，但需要去掉 `/.well-known/openid-configuration` 部分，因为 EMQX 会自动添加，例如 `https://login.microsoftonline.com/<tenant_id>/v2.0`，其中 `<tenant_id>` 是你的 目录(租户) ID。
+
+   - **Client ID**：对应**步骤 2** 中应用概览页面上的**应用程序(客户端) ID**。
+
+     <img src="./assets/entra_id_oidc_app_config.png" alt="entra_id_oidc_app_config" style="zoom:50%;" />
+
+   - **Client Secret**：使用在**步骤 2** 中生成的客户端密码值。
+
+   - **Dashboard 地址**：输入用户可以访问 Dashboard 的基础 URL，例如 `http://localhost:18083`。此地址会被自动组合以生成用于在 IdP 侧配置的 **SSO 地址**和**元数据地址**。
+
+<img src="./assets/entra_id_oidc_dashboard.png" alt="entra_id_oidc_dashboard" style="zoom:50%;" />
+
+2. 点击**更新**以完成配置。
 
 ## 集成 Okta 身份服务配置 SSO
 

zh_CN/dashboard/sso-saml.md

@@ -10,13 +10,62 @@
 
 ## 支持的 SAML 服务
 
-EMQX Dashboard 可以与以下支持 SAML 2.0 协议的身份服务集成，实现基于 SAML 的单点登录：
+EMQX Dashboard 可以与以下支持 SAML 2.0 协议的身份服务集成，实现基于 SAML 的单点登录，例如：
+
+- [Microsoft Entra ID](https://www.microsoft.com/zh-cn/security/business/identity-access/microsoft-entra-id)
 
 - [Okta](https://www.okta.com/)
 - [OneLogin](https://www.onelogin.com/)
 
 其他身份提供商正在适配中，将在后续版本提供。
 
+## 通过集成 Microsoft Entra ID 配置 SSO
+
+本节指导你如何使用 Microsoft Entra ID 作为身份提供方（IdP）并配置 SSO。您需要分别完成 IdP 侧与 EMQX Dashboard 侧的配置。
+
+### 步骤 1：在 EMQX Dashboard 中启用 SAML
+
+1. 在 Dashboard 中进入**系统设置** -> **单点登录**。
+2. 点击 **SAML 2.0** 卡片上的**启用**按钮。
+3. 在配置页面输入以下信息：
+   - **Dashboard 地址**：确保用户可以访问 Dashboard 的实际访问地址，不需要指定具体路径。例如 `http://localhost:18083`。此地址将被自动拼接以生成用于 IdP 侧配置的 **SSO Address** 和 **Metadata Address**。
+   - **SAML 元数据 URL**：暂时留空，等待步骤 2 的配置。
+
+### 步骤 2：注册一个应用以集成 Microsoft Entra ID
+
+1. 以管理员身份登录 [MS Azure Portal](https://portal.azure.com/)。
+
+2. 进入 **Microsoft Entra ID** -> **企业应用程序** -> **新建应用程序**，并点击 **创建你自己的应用程序**。
+
+   <img src="./assets/entra_id_create_own_app.png" alt="entra_id_create_own_app" style="zoom:50%;" />
+
+3. 输入应用名称，例如 `EMQX Dashboard`，选择**集成未在库中找到的任何其他应用程序(非库)**，并点击**创建**。
+
+   <img src="./assets/entra_id_saml_app_parameters.png" alt="entra_id_saml_app_parameters" style="zoom:50%;" />
+
+4. 点击**分配用户和组**以分配可以访问 EMQX Dashboard 应用的用户和组。
+
+5. 进入**单一登录**标签页，选择 **SAML**，并点击**基本 SAML 配置**区域中的**编辑**按钮。
+
+6. 使用步骤 1 中 Dashboard 提供的地址配置以下信息：
+
+   - **标识符 (实体 ID)**：输入 Dashboard 提供的**元数据地址**，例如 `http://localhost:18083/api/v5/sso/saml/metadata`。
+   - **回复 URL (断言使用者服务 URL)**：输入 Dashboard 提供的**单点登录地址**，例如 `http://localhost:18083/api/v5/sso/saml/acs`。
+
+   其他信息为可选项，可根据实际需求进行配置。
+
+7. 点击**保存**保存配置。
+
+### 步骤 3：完成 EMQX Dashboard 配置
+
+1. 在 Microsoft Entra ID 中，进入创建的应用的**单一登录**标签页，并在**令牌签名证书**区域中复制**应用联合元数据 URL**。
+
+   <img src="./assets/entra_id_saml_metadata_url.png" alt="entra_id_saml_metadata_url" style="zoom:50%;" />
+
+2. 在 Dashboard 中，将复制的 URL 粘贴到步骤 1 的 **SAML 元数据 URL** 中。
+
+3. 点击**更新**以完成配置。
+
 ## 集成 Okta 身份服务配置 SSO
 
 本节将指导您如何使用 Okta 作为身份提供商（IdP）并配置单点登录，您需要分别完成身份提供商（IdP）侧与 EMQX Dashboard 侧的配置。