From c92598a401bbfd09556fd651491df933580109c7 Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Thu, 26 Sep 2024 14:45:14 +0800 Subject: [PATCH 1/3] update(Client-Info authen): Add Dashboard configurations --- en_US/access-control/authn/cinfo.md | 25 ++++++++++++++----- en_US/access-control/authn/kerberos.md | 14 ++++++----- zh_CN/access-control/authn/cinfo.md | 33 +++++++++++++++++++++----- zh_CN/access-control/authn/kerberos.md | 14 ++++++----- 4 files changed, 62 insertions(+), 24 deletions(-) diff --git a/en_US/access-control/authn/cinfo.md b/en_US/access-control/authn/cinfo.md index 1b84ef771..d89ae75d2 100644 --- a/en_US/access-control/authn/cinfo.md +++ b/en_US/access-control/authn/cinfo.md @@ -1,8 +1,25 @@ # Client-Info Authentication -Client-info authentication (`cinfo` type) is a lightweight authentication mechanism that verifies client properties and attributes against user-defined rules. These rules make use of the Variform expressions to define matching conditions and determine the authentication outcome when a match is found. For example, to quickly block clients without a username, you can use the condition `str_eq(username, '')` with a result of `deny`. +Client-Info authentication (`cinfo` type) is a lightweight authentication mechanism that verifies client properties and attributes against user-defined rules. These rules make use of the Variform expressions to define matching conditions and determine the authentication outcome when a match is found. For example, to quickly block clients without a username, you can use the condition `str_eq(username, '')` with a result of `deny`. -The authenticator configuration looks like below: +## Configure Client-Info Authentication via Dashboard + +In the EMQX Dashboard, navigate to **Access Control** -> **Authentication** in the left menu to enter the **Authentication** page. Click **Create** at the top right corner, then select **Client Info** as the **Mechanism**, Client-Info authentication does not require selecting a backend, so you can proceed by clicking **Next** to enter the **Configure Parameters** step. + +1. Click **Add** in the **Checks**. + - In the **Match Conditions** input box, enter the Variform expression used to match client information. If there are multiple expressions, enter each on a new line. When all expressions return `true`, the authenticator will return the relevant result; otherwise, the current check will be skipped. The following variables are supported in the expressions: + - `username`: Username + - `clientid`: Client ID + - `client_attrs.*`: Client Attributes + - `peerhost`: Client IP + - `cert_subject`: TLS Certificate Subject + - `cert_common_name`: TLS Certificate Common Name + - Select `allow`, `ignore`, or `deny` from the **Result** dropdown menu. +2. Click **Create** to complete the authentication configuration. + +## Configure Client-Info Authentication via Configuration Items + +Below is a configuration example for the Client-Info authenticator: ```bash authentication = [ @@ -37,7 +54,3 @@ More match expression examples: - Match clients whose attribute `client_attrs.group` is not `g0`: `str_neq(client_attrs.group, 'g0')` - Match client IDs that start with the zone name:`regex_match(clientid, concat(['^', zone, '.+$']))` -## Configure Client-Info Authentication in Dashboard - - - diff --git a/en_US/access-control/authn/kerberos.md b/en_US/access-control/authn/kerberos.md index 38aac49c0..b7532591f 100644 --- a/en_US/access-control/authn/kerberos.md +++ b/en_US/access-control/authn/kerberos.md @@ -54,17 +54,19 @@ EMQX can only support keytab files at the default location. You can configure th In the EMQX Dashboard, navigate to **Access Control** -> **Authentication** in the left menu to enter the **Authentication** page. Click **Create** at the top right corner, then select **GSSAPI** as the **Mechanism**, and **Kerberos** as the **Backend**. Click **Next** to go to the **Configuration** step. -Configure the following fields: +1. Configure the following fields: -- **Principal**: Set Kerberos principal for the server to define the server's identity within the Kerberos authentication system. For example, `mqtt/cluster1.example.com@EXAMPLE.COM`. + - **Principal**: Set Kerberos principal for the server to define the server's identity within the Kerberos authentication system. For example, `mqtt/cluster1.example.com@EXAMPLE.COM`. - Note: The realm in use must be configured in `/etc/krb5.conf` on EMQX nodes. + Note: The realm in use must be configured in `/etc/krb5.conf` on EMQX nodes. -- **Keytab File**: Specify the path to the Kerberos keytab file. - Note: The keytab file must be located on the EMQX nodes, and the user running the EMQX service must have read permissions for the file. + - **Keytab File**: Specify the path to the Kerberos keytab file. -Click **Create** to complete the configuration. + Note: The keytab file must be located on the EMQX nodes, and the user running the EMQX service must have read permissions for the file. + + +2. Click **Create** to complete the configuration. ## Configure via Configuration Items diff --git a/zh_CN/access-control/authn/cinfo.md b/zh_CN/access-control/authn/cinfo.md index d27229174..4f344debe 100644 --- a/zh_CN/access-control/authn/cinfo.md +++ b/zh_CN/access-control/authn/cinfo.md @@ -2,7 +2,33 @@ Client-info 认证（`cinfo` 类型）是一种轻量级的认证机制，它通过检查客户端的属性和特性，依据用户定义的规则进行验证。这些规则使用 Variform 表达式来定义匹配条件，并在找到匹配时决定认证结果。例如，要快速阻止没有用户名的客户端，可以使用条件 `str_eq(username, '')`，并将结果设置为 `deny`。 -认证器配置如下： +## 通过 Dashboard 配置 Client-Info 认证 + +在 EMQX Dashboard 中，导航到左侧菜单中的**访问控制** -> **认证**，进入**认证**页面。点击右上角的**创建**，然后选择 **Client Info** 作为**认证方式**，Client Info 认证无需选择数据源，因此您可以继续点击**下一步**进入**配置参数**步骤。 + +1. 在**检查列表**中点击**添加**。 + + - 在**匹配条件**输入框中输入用于匹配客户端信息的 Variform 表达式。当有多个表达式时需分行输入，每行一个表达式。当所有表达式返回 `true` 时，认证器返回相关结果；否则将跳过当前检查。表达式中支持以下变量： + + - `username`: 用户名 + + - `clientid`: 客户端 ID + + - `client_attrs.*`: 客户端属性 + + - `peerhost`: 客户端 IP + + - `cert_subject`: TLS 证书主题 + + - `cert_common_name`: TLS 证书通用名称。 + + - 从**匹配结果**下拉框中选择 `allow`, `ignore` 或者 `deny`。 + +2. 点击**创建**完成认证配置。 + +## 通过配置项配置 Client-Info 认证 + +认证器配置示例： ```bash authentication = [ @@ -36,8 +62,3 @@ authentication = [ - 匹配密码为环境变量 `EMQXVAR_SECRET` 与客户端 ID 连接后的 `sha1` 哈希值的客户端：`str_eq(password, hash(sha1, concat([clientid, getenv('SECRET')])))` - 匹配客户端属性 `client_attrs.group` 不为 `g0` 的客户端：`str_neq(client_attrs.group, 'g0')` - 匹配客户端 ID 以 zone 名称开头的客户端：`regex_match(clientid, concat(['^', zone, '.+$']))` - -## 通过 Dashboard 配置 Clinet-info 认证 - - - diff --git a/zh_CN/access-control/authn/kerberos.md b/zh_CN/access-control/authn/kerberos.md index 65556f190..95611cfa0 100644 --- a/zh_CN/access-control/authn/kerberos.md +++ b/zh_CN/access-control/authn/kerberos.md @@ -53,17 +53,19 @@ EMQX 只能支持默认位置的密钥表文件。您可以使用环境变量 `K 在 EMQX Dashboard 中，导航到左侧菜单中的**访问控制** -> **认证**，进入**认证**页面。点击右上角的**创建**，然后选择 **GSSAPI** 作为**认证方式**，选择 **Kerberos** 作为**数据源**，点击**下一步**进入**配置参数**步骤。 -配置以下字段： +1. 配置以下字段： -- **主体**：设置服务器的 Kerberos 主体，用于定义服务器在 Kerberos 身份验证系统中的身份。例如，`mqtt/cluster1.example.com@EXAMPLE.COM`。 + - **主体**：设置服务器的 Kerberos 主体，用于定义服务器在 Kerberos 身份验证系统中的身份。例如，`mqtt/cluster1.example.com@EXAMPLE.COM`。 - 注意：使用的领域必须在 EMQX 节点上的 `/etc/krb5.conf` 中配置。 + 注意：使用的领域必须在 EMQX 节点上的 `/etc/krb5.conf` 中配置。 -- **密钥表文件**：指定 Kerberos 密钥表文件的路径。 - 注意：密钥表文件必须位于 EMQX 节点上，并且运行 EMQX 服务的用户必须对该文件具有读取权限。 + - **密钥表文件**：指定 Kerberos 密钥表文件的路径。 -点击**创建**完成配置。 + 注意：密钥表文件必须位于 EMQX 节点上，并且运行 EMQX 服务的用户必须对该文件具有读取权限。 + + +2. 点击**创建**完成配置。 ## 通过配置项进行配置 From 3d5575f9a8848e73f54f0c09b8efc9a631c56671 Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Sun, 29 Sep 2024 11:06:59 +0800 Subject: [PATCH 2/3] Update zh_CN/access-control/authn/cinfo.md --- zh_CN/access-control/authn/cinfo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zh_CN/access-control/authn/cinfo.md b/zh_CN/access-control/authn/cinfo.md index 4f344debe..718f916b3 100644 --- a/zh_CN/access-control/authn/cinfo.md +++ b/zh_CN/access-control/authn/cinfo.md @@ -18,7 +18,7 @@ Client-info 认证（`cinfo` 类型）是一种轻量级的认证机制，它通 - `peerhost`: 客户端 IP - - `cert_subject`: TLS 证书主题 + - `cert_subject`: TLS 证书主体 - `cert_common_name`: TLS 证书通用名称。 From 46ac0f6d38e0777d8f5d37344b1182db2e8df693 Mon Sep 17 00:00:00 2001 From: Meggielqk <126552073+Meggielqk@users.noreply.github.com> Date: Mon, 30 Sep 2024 11:14:36 +0800 Subject: [PATCH 3/3] Update zh_CN/access-control/authn/cinfo.md Co-authored-by: zmstone --- zh_CN/access-control/authn/cinfo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zh_CN/access-control/authn/cinfo.md b/zh_CN/access-control/authn/cinfo.md index 718f916b3..d37d0eb6e 100644 --- a/zh_CN/access-control/authn/cinfo.md +++ b/zh_CN/access-control/authn/cinfo.md @@ -18,7 +18,7 @@ Client-info 认证（`cinfo` 类型）是一种轻量级的认证机制，它通 - `peerhost`: 客户端 IP - - `cert_subject`: TLS 证书主体 + - `cert_subject`: TLS 证书主题，即专有名称（DN）。 - `cert_common_name`: TLS 证书通用名称。