客户端属性

客户端属性是 EMQX 提供的一种机制，允许开发人员根据不同的应用场景需求，为 MQTT 客户端设置额外的属性。这些属性可以用于 EMQX 的认证授权、数据集成和 MQTT 扩展功能等功能中，在实现灵活开发中发挥重要作用。通过利用客户端元数据，此功能还支持 MQTT 客户端识别的灵活模板化，这对于个性化客户端配置和简化的认证过程至关重要，增强了开发工作的适应性和效率。

工作流程

客户端属性的设置、存储和使用流程如下：

1. 设置客户端属性：

当客户端成功连接到 EMQX 时，EMQX 会触发连接与认证事件，并在此过程中根据预先定义的配置来设置客户端属性。

2. 客户端属性存储与销毁：

一旦设定了属性，它们会以键值对的形式存储在客户端会话的 client_attrs 字段中。当客户端会话结束时，这些属性会被删除。

对于保留会话，客户端接管时，会替换覆盖会话中已有的客户端属性。除此之外，无法通过其他方式修改或删除客户端属性。

3. 使用客户端属性：

EMQX 的其他功能允许在相关配置项中使用 ${client_attrs.NAME} 占位符，动态提取属性值，并将其配置或数据的一部分来使用。

设置客户端属性

当客户端成功连接到 EMQX 时，EMQX 会触发连接和认证事件，并根据预先定义的配置来设置客户端属性。目前支持以下两种设置方式：

从客户端元数据中提取
在客户端认证过程中设置

从客户端元数据中提取

通过预设的配置，从客户端连接时的用户名、客户端 ID 等元数据中提取并处理生成子串，并将其设置为客户端属性。这个过程是在认证之前发生的，确保了属性可以在认证过程中使用。您可以通过配置文件或 Dashboard 配置客户端属性功能。

想要在 Dashboard 中配置客户端属性，点击左侧导航中的管理 -> MQTT 配置，在客户端属性配置中点击添加，填写属性名称和属性表达式。

客户端属性设置

其中，属性为属性的名称，属性表达式为属性的提取配置。

属性表达式支持使用 Variform 表达式以及其中的预定义的函数对值进行动态处理。例如:

要提取由点分隔的客户端 ID 的前缀：nth(1, tokens(clientid, '.'))
要截取用户名部分信息：substr(username, 0, 5)

对应的配置文件如下：

bash

mqtt {
    client_attrs_init = [
        {
            expression = "nth(1, tokens(clientid, '.'))"
            set_as_attr = clientid_prefix
        },
        {
            expression = "substr(username, 0, 5)"
            set_as_attr = sub_username
        }
    ]
}

在属性表达式中支持配置以下值：

clientid：客户端 ID
username：用户名
cn：TLS 证书的 CN 字段
dn：TLS 证书的 DN 字段
user_property.*：从 MQTT CONNECT 数据包的 User-Property 中提取属性值，例如 user_property.foo
zone：继承自 MQTT 监听器的 zone 名称

更多客户端属性配置的详细信息，请参见 EMQX 开源版配置手册和 EMQX 企业版配置手册。

在客户端认证过程中设置

在客户端认证过程中，可以通过认证器返回的信息设置客户端属性，目前支持：

JWT 认证：签发 Token 时，在 Payload 中通过 client_attrs 字段设置客户端属性。
HTTP 认证：在认证成功的 HTTP 响应中，通过 client_attrs 字段设置客户端属性。

属性的键值均要求是字符串。这种方式允许根据认证结果动态地设置属性，增加了使用的灵活性。

合并认证数据

当同时通过 2 种设置方式，或使用多个认证器设置客户端属性时，EMQX 会按照属性名称以及设置的先后顺序对属性进行合并：

从客户端元数据中提取的属性将被认证器中设置的属性覆盖。
认证链中多个认证器设置属性时，后设置的属性将覆盖前面的属性。