扩展认证

扩展认证帮助用户使用自己服务进行认证，支持外部数据库如 MySQL， Redis 作为数据源，或者连接到 HTTP 服务做认证鉴权。

提示

Serverless 部署不支持扩展认证功能。

扩展认证数据源

HTTP 认证

MySQL 认证

PostgreSQL 认证

Redis 认证

JWT 认证

TIP

最多支持创建两个扩展认证数据源。

认证器调用条件

对于运行 EMQX 6.1 或更高版本的部署，可以为每个扩展认证器配置调用条件，用于判断是否应调用该认证器来认证当前客户端。调用条件是一个 Variform 表达式，可基于客户端属性信息进行逻辑判断。如果表达式的计算结果不是字符串值 'true'，EMQX 将跳过当前认证器，并继续使用认证链中的下一个已启用认证器进行认证。

调用条件可以在认证链中实现条件认证逻辑。例如，可以根据客户端的连接信息或属性应用不同的认证器，使 EMQX 仅在适当的情况下调用认证器，避免向外部系统发送不必要的请求。

调用条件中支持的客户端属性

调用条件中支持以下客户端属性：

• username：客户端的用户名。
• password：客户端的密码。
• clientid：客户端 ID。
• client_attrs.*：客户端的自定义属性。
• cert_common_name：客户端 TLS 证书中的公用名称（CN）。
• cert_subject：客户端 TLS 证书中的主体字段。
• peersni：TLS 客户端发送的服务器名称指示（SNI）。
• listener：监听器 ID，例如 ssl:default。

配置调用条件

创建或编辑 HTTP、MySQL、PostgreSQL、Redis、JWT 或 JWKS 认证器时，在调用条件中输入 Variform 表达式。此配置为可选项。配置表达式时，其长度必须为 1 到 256 个字符。如果将此配置留空或清空已有表达式，EMQX 将根据认证器在认证链中的位置调用该认证器，不再评估额外的调用条件。

以下示例说明如何控制是否调用认证器：

• 仅当客户端通过 ssl:default 监听器连接时调用认证器：

  str_eq(listener, 'ssl:default')

• 当用户名为空时跳过认证器：

  not(is_empty_val(username))

如果表达式无效，无法保存配置，最后一次有效配置仍然生效。请根据 Cloud Console 显示的错误修正表达式，然后重试。有关调用条件和表达式语法的更多信息，参见 EMQX 文档中的认证器调用条件。

认证排序

添加了扩展认证数据源之后，用户可以对认证数据源做排序。部署将按照从左到右的顺序进行认证，默认的认证链顺序为默认认证 -> 扩展认证。

• 如果认证成功，终止认证链并允许客户端接入。
• 如果认证失败，终止认证链并禁止客户端接入。
• 如果当前数据源未能匹配，将进入下一个认证源进行认证。

如何创建认证链

您可以在部署页面的访问控制 -> 客户端认证 -> 扩展认证中创建认证链。当配置并连接了扩展认证数据源后，您将在页面上看到排序设置区域。

1. 点击认证排序，进入认证顺序设置页面。
2. 拖动认证数据源的图标，左右排列进行认证顺序的编排。
3. 排序完成后，点击确认保存更改。

外部资源缓存

提示

外部资源缓存功能适用于 EMQX 5.9 及以上版本的专有版部署。

EMQX Cloud 支持对来自外部后端（如 MySQL 或 Redis）的认证结果进行缓存。该缓存机制可提升认证查询的性能，减少在高吞吐量场景下对外部资源的重复访问。

注意

外部资源缓存仅适用于扩展认证数据源。对于默认的密码认证，EMQX 不使用该缓存机制。

外部资源缓存的工作原理

外部资源缓存用于存储客户端认证的结果，这些结果在整个集群中的所有客户端会话之间共享，有效避免重复访问外部认证后端。

认证流程如下：

1. 客户端连接并触发认证操作。
2. EMQX Cloud 首先在缓存中查找是否已有对应的认证结果：
   • 如果找到了有效的结果，则视为缓存命中，无需访问外部后端。
   • 如果未找到缓存结果，则视为缓存未命中，EMQX Cloud 会向外部后端发起查询。
3. 从后端返回的认证结果将被存入缓存，用于后续请求，并计入缓存写入指标。

该机制有助于降低认证延迟、减少外部资源调用，并在高负载下维持系统响应能力。

启用和配置外部资源缓存

您可以在部署页面的访问控制 -> 客户端认证 -> 扩展认证中启用并配置外部资源缓存。当扩展认证数据源已配置并连接后，页面将显示缓存设置区域。

1. 点击外部资源缓存设置打开侧边栏面板。
2. 在面板中点击启用外部资源缓存开关以开启或关闭缓存功能。
3. 启用后，可配置以下缓存参数：
   • 最大缓存数量：每个节点可缓存的最大条目数。默认值：1,000,000。
   • 最大内存：缓存可占用的最大内存。默认值：100 MB。
   • 缓存过期时间：每条缓存项的有效时长。默认值：1 分钟。
4. 点击更新应用配置。

监控外部资源缓存状态

若要实时查看缓存指标和使用情况：

1. 将鼠标悬停在外部资源缓存设置右侧的箭头上；
2. 点击外部资源缓存状态，弹出侧边栏查看实时缓存指标。

可查看的缓存指标包括：

• 内存占用：当前缓存占用的总内存。
• 缓存条目数：当前存储的缓存认证结果总数。
• 缓存命中：EMQX Cloud 成功在缓存中找到有效结果，避免访问外部后端的次数。
  • 展示数据包括：当前速率、5 分钟平均值、最大速率
• 缓存未命中：EMQX Cloud 未能在缓存中找到结果，因而查询外部后端的次数。
  • 展示数据包括：当前速率、5 分钟平均值、最大速率
• 缓存插入：在未命中后新增写入缓存结果的次数。
  • 展示数据包括：当前速率、5 分钟平均值、最大速率

您可以通过面板右上角的按钮刷新或重置这些统计数据。