客户端认证

FlowMQ 提供统一的客户端认证能力，所有协议（MQTT、Kafka、AMQP、NATS）共享同一套账号与凭据体系。

认证默认开启，初始状态下没有为任何协议配置认证器，此时客户端可匿名访问，确保开箱即用。管理员可随时创建认证器、将其绑定到对应协议，按需收紧安全策略。

认证器

认证器是执行凭据校验的组件。FlowMQ 支持以下认证器类型：

类型	说明	状态
密码认证（password）	用户名/密码认证，凭据存储于 FlowMQ 内部	可用
Webhook	将认证请求转发至外部 HTTP 服务，由业务系统决定是否放行（见 Webhook 认证）	可用
X.509 证书	基于客户端 TLS 证书（mTLS）进行身份识别	规划中
OIDC	对接 OpenID Connect / OAuth2，验证 JWT 令牌	规划中
LDAP	对接 LDAP / Active Directory	规划中

管理员可以创建任意数量的认证器实例，每个实例由类型 + 名称唯一标识，并分别为每个协议指定使用哪一个。

各协议的凭据承载方式：

协议	认证方式
MQTT	`CONNECT` 报文中的 `username` / `password`
Kafka	SASL/PLAIN（暂不支持 SCRAM）
AMQP	SASL PLAIN
NATS	`CONNECT` 命令中的认证信息

协议与认证器的绑定

每个协议最多绑定一个认证器。当某个协议绑定了认证器时，该协议的所有连接都必须通过对应的凭据校验；未绑定认证器的协议则允许匿名访问。

这种模型让管理员可以按协议独立配置认证策略。例如，对外的 MQTT 接入使用 Webhook 对接业务系统，内部的 Kafka 接入使用内置的用户名/密码认证，而 NATS 保持匿名开放。

匿名访问

如果某个协议没有绑定认证器，客户端无需提供凭据即可连接，FlowMQ 会以匿名身份接受该连接。这保证了未配置认证器的协议不会被意外中断。

如需强制所有连接必须认证，请为每个对外开放的协议都绑定一个认证器。

多租户与命名空间隔离

FlowMQ 通过**命名空间（namespace）**支持多租户：在一套共享集群上，不同租户的账号、凭据与授权策略互相隔离、彼此不可见。

是否启用命名空间隔离取决于部署形态：

多租户共享部署：开启命名空间隔离，每个租户拥有独立的命名空间。客户端连接在建立时被归入某个命名空间——FlowMQ 主要依据 TLS SNI 推导（约定 SNI 形如 <namespace>.<host>，取首个标签作为命名空间名），也支持按用户名或认证主体（principal）的约定推导。连接归属的命名空间决定了它在哪一份用户库中完成认证、受哪一组授权策略约束。
单租户独享部署：不启用命名空间隔离，所有连接都归属同一个 default 命名空间，使用同一份用户库。这是独享部署的常规形态。

关于 default 命名空间

default 是未启用命名空间隔离时使用的默认命名空间，对应单一的共享用户库。它是保留名称：客户端不能显式选择它，管理 API 也不能创建或删除它。

命名空间隔离只对密码（password）认证器生效：password 认证器按命名空间隔离各租户的用户库；Webhook 等对接外部系统的认证方式在全局范围内工作，由外部系统区分身份，不参与命名空间隔离。

Webhook 认证

Webhook 认证器把凭据校验交给外部 HTTP 服务：每次连接认证时，FlowMQ 向配置的地址发起一次请求，由业务系统返回放行或拒绝，并可附带身份标识与属性。它适合复用已有账号体系，或在认证时动态下发用于授权的属性。Webhook 目前只处理用户名/密码类凭据。

请求：向 url 发起 HTTP POST，请求体为 JSON。未配置 body 模板时，默认请求体为：

json

{
  "username": "<用户名>",
  "password": "<密码>",
  "clientId": "<协议层客户端标识>",
  "clientIP": "<客户端 IP>",
  "protocol": "<mqtt | kafka | amqp | nats>"
}

响应：204 直接放行；200 由响应体决定，须为非空 JSON；其余状态码（<200 或 >=300）拒绝。200 时按如下解析：

result（必填）："success" 放行，其他（含 "fail"）拒绝。
身份标识：按 responseMapping.principalId（默认 $.user_id）提取，取不到则回退到用户名、再回退到 clientId。
属性：按 responseMapping.attributes（默认 $.attributes）提取，须为对象；这些属性会写入身份，供授权策略按 ABAC 匹配或在资源名中以 ${principal.attributes.<名称>} 引用。

配置项（一段 JSON）：

字段	必填	默认值	说明
`url`	是	—	`http://` 或 `https://` 地址
`timeoutSeconds`	否	`5`	单次请求超时（秒）
`headers`	否	`{}`	附加请求头，值支持占位符
`body`	否	`{}`	自定义请求体模板；为空时用默认请求体
`responseMapping.principalId`	否	`$.user_id`	提取身份标识的 JSON 路径
`responseMapping.attributes`	否	`$.attributes`	提取属性对象的 JSON 路径

url、headers 值与 body 模板中可用占位符 ${username}、${password}、${clientid}、${peerhost}、${protocol}，在认证时展开（url 中的值会做 URL 编码）。

配置示例：

json

{
  "url": "https://auth.example.com/verify",
  "timeoutSeconds": 3,
  "headers": { "Authorization": "Bearer my-service-token" },
  "responseMapping": { "principalId": "$.data.id", "attributes": "$.data.attrs" }
}

可在 Dashboard 创建 Webhook 认证器并绑定到协议，也可调用管理 API：POST /v1/authentication/authenticators 创建实例（type 为 webhook，config 为上述 JSON 序列化后的字符串），再用 PUT /v1/authentication/config 绑定到对应协议。

Dashboard 操作

在 Dashboard 的 Authentication 页面可以：

创建、编辑和删除认证器实例
为每个协议绑定或解绑认证器
对密码认证器执行用户管理（创建用户、修改密码、删除用户）

客户端认证

客户端认证 ​

认证器 ​

协议与认证器的绑定 ​

匿名访问 ​

多租户与命名空间隔离 ​

Webhook 认证 ​

Dashboard 操作 ​

客户端认证

认证器

协议与认证器的绑定

匿名访问

多租户与命名空间隔离

Webhook 认证

Dashboard 操作