帮你快速理解、总结文档立即下载

使用外部 HTTP 服务认证

最近更新时间:2026-08-06 11:10:01
我的收藏

概述

消息队列 MQTT 版支持通过对接外部第三方的 HTTP 服务进行客户端认证和简单的鉴权。客户端在进行连接(发送 Connect Packet)时,MQTT 使用客户端/证书的信息(例如用户名,密码等)构造 HTTP 请求,请求到达指定的 HTTP 认证服务后,MQTT 会根据该 HTTP 请求的返回结果来判断认证是否通过。如果认证通过,则允许该客户端连接服务端;如果认证不通过,则拒绝该客户端的连接。

认证原理

当 MQTT 客户端连接到 MQTT 时,MQTT 作为请求客户端需要按照 "API" 要求的格式构造并向 HTTP 服务发起请求,而 HTTP 服务需要按照 "客户端" 的要求返回结果,HTTP 响应状态码 (HTTP Status Code) 被用于判断认证请求是否成功。HTTP 认证服务需要满足以下条件:
HTTP 响应的编码格式 content-type 必须是 application 或者 json
认证结果由 body 中的 result 标示,可选 allowdenyignore
是否为超级用户由 body 中的 is_superuser 标示,可选 truefalse
认证结果应通过 Status Code 200204 进行返回。
其他响应码将被认为 HTTP 认证请求执行失败,例如 4xx5xx 等。此时认证结果使用缺省值 ignore,继续执行认证链。如果当前的 HTTP 认证器是链上的最后一个认证器,则认证失败,客户端将被拒绝连接。
响应示例如下:
HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
"result": "allow", // "allow" | "deny" | "ignore"
"client_attrs": {
"role": "admin",
"sn": "10c61f1a1f47"
}
"expire_at": 1654254601, // 可选,表示当前认证策略的过期时间
"acl": // 可选,用于使用既有的HTTP认证服务支持简单的授权,授权策略将会被缓存到MQTT服务端,再次触发时更新
[
{
"effect": "allow",
"action": ["publish","subscribe","connect"],
"topic": "topic/AA/#",
"qos": [1]
},
{
"effect": "deny",
"action": ["publish","connect"],
"topic": "topic/BB"
}
]
}

操作步骤

对接公网认证服务
对接 VPC 内认证服务
1. 登录 MQTT 控制台
2. 在左侧导航栏单击资源管理 > 集群管理,选择好地域后,单击目标集群的“ID”,进入集群基本信息页面。
3. 在集群基本信息页面,选择认证管理页签,二级页签选择外部 HTTP 认证,单击创建认证
4. 在弹出的配置表单中,依次填写以下参数:
参数
说明
网络类型
选择 公网。
终端节点服务
选择或创建 VPC 终端节点服务(vpcsvc-xxx)。VPC 网络模式下必须完成此项配置。
请求方式
选择 HTTP 请求方式,可选值:POST, GET
服务地址
输入 HTTP(S) 服务的 URL。
Headers
HTTP 请求头配置,可添加多行键值对。值(Value)支持常量和模板变量替换,格式为 ${变量名称},输入 ${ 可触发提示。示例:Content-type = application/json。
启用 User Properties 透传
开关项。开启后,MQTT 5.0 客户端 CONNECT 报文中的所有 User Properties 将自动添加到 HTTP 请求头中。
Body
请求体模板,键值对形式。在填写值(value)时支持使用常量和模板变量替换,格式为"${变量名称}",通过输入"${"可以触发提示。
最大请求并发数
设置最大请求并发数,范围 1–10,默认 8。
连接超时时间
设置连接超时等待时长,范围 1–30 秒,默认 10 秒。
请求超时时间
设置请求超时等待时长,范围 1–30 秒,默认 10 秒。
说明
备注信息,不超过 128 个字符。
5. 单击确认完成创建。创建完成后,可以单击右上方的

调试。

1. 登录 MQTT 控制台
2. 在左侧导航栏单击资源管理 > 集群管理,选择好地域后,单击目标集群的“ID”,进入集群基本信息页面。
3. 在集群基本信息页面,选择认证管理页签,二级页签选择外部 HTTP 认证,单击创建认证
4. 在弹出的配置表单中,依次填写以下参数:
参数
说明
网络类型
选择 VPC 网络。
授权 MQTT 服务端通过 VPC 网络访问 HTTP 认证服务
勾选此复选框以启用 VPC 内网访问。
终端节点服务
选择已有或创建 VPC 终端节点服务(vpcsvc-xxx),VPC 网络模式下必须完成此项配置。
请求方式
选择 HTTP 请求方式,可选值:POST, GET
服务地址
输入 HTTP(S) 认证服务的 URL。
VPC 模式下暂不支持私有域名认证服务,且不支持复用自建 CA 证书(若认证服务使用 HTTPS,将因证书不受信任而导致调用失败。)
Headers
HTTP 请求头配置,可添加多行键值对。值(Value)支持常量和模板变量替换,格式为 ${变量名称},输入 ${ 可触发提示。示例:Content-type = application/json。
启用 User Properties 透传
开关项。开启后,MQTT 5.0 客户端 CONNECT 报文中的所有 User Properties 将自动添加到 HTTP 请求头中。
Body
请求体模板,键值对形式。在填写值(value)时支持使用常量和模板变量替换,格式为"${变量名称}",通过输入"${"可以触发提示。
最大请求并发数
设置最大请求并发数,范围 1–10,默认 8。
连接超时时间
设置连接超时等待时长,范围 1–30 秒,默认 10 秒。
请求超时时间
设置请求超时等待时长,范围 1–30 秒,默认 10 秒。
说明
备注信息,不超过 128 个字符。
5. 单击确认完成创建。创建完成后,可以单击右上方的

进行调试。


模板变量

客户端变量字段

变量名/Variable
语义
InstanceId
MQTT 实例 ID
ClientId
MQTT Client ID
Username
MQTT 客户端连接 Username
Password
MQTT 客户端连接 Password
ClientIp
MQTT 客户端 IP 地址
Certificate.Pem
客户端证书的 PEM 格式内容
Certificate.ChainSn
证书链的序列号

证书主题字段

变量名/Variable
语义
Certificate.Subject.Organization
证书主题 - 组织名称
Certificate.Subject.OrganizationalUnit
证书主题 - 组织单元
Certificate.Subject.State
证书主题 - 州/省
Certificate.Subject.CommonName
证书主题 - 通用名称
Certificate.Subject.SerialNumber
证书主题 - 序列号
Certificate.Subject.Title
证书主题 - 头衔
Certificate.Subject.Surname
证书主题 - 姓氏
Certificate.Subject.GivenName
证书主题 - 名字
Certificate.Subject.Initials
证书主题 - 缩写
Certificate.Subject.Pseudonym
证书主题 - 别名
Certificate.Subject.GenerationQualifier
证书主题 - 代际限定符
Certificate.Subject.DistinguishedNameQualifier
证书主题 - 可辨别名称限定符
Certificate.Subject.Country
证书主题 - 国家/地区代码

证书颁发者字段

变量名/Variable
语义
Certificate.Issuer.Organization
证书颁发者 - 组织名称
Certificate.Issuer.OrganizationalUnit
证书颁发者 - 组织单元
Certificate.Issuer.State
证书颁发者 - 州/省
Certificate.Issuer.CommonName
证书颁发者 - 通用名称
Certificate.Issuer.SerialNumber
证书颁发者 - 序列号
Certificate.Issuer.Title
证书颁发者 - 头衔
Certificate.Issuer.Surname
证书颁发者 - 姓氏
Certificate.Issuer.GivenName
证书颁发者 - 名字
Certificate.Issuer.Initials
证书颁发者 - 缩写
Certificate.Issuer.Pseudonym
证书颁发者 - 别名
Certificate.Issuer.GenerationQualifier
证书颁发者 - 代际限定符
Certificate.Issuer.DistinguishedNameQualifier
证书颁发者 - 可辨别名称限定符
Certificate.Issuer.Country
证书颁发者 - 国家/地区代码

备用名称字段

变量名/Variable
语义
Certificate.Subject.AlternativeName.RFC822Name
主题备用名称 - 电子邮件地址
Certificate.Subject.AlternativeName.DNSName
主题备用名称 - DNS 域名
Certificate.Subject.AlternativeName.DirectoryName
主题备用名称 - 目录名称
Certificate.Subject.AlternativeName.UniformResourceIdentifier
主题备用名称 - 统一资源标识符
Certificate.Subject.AlternativeName.IPAddress
主题备用名称 - IP 地址
Certificate.Issuer.AlternativeName.RFC822Name
颁发者备用名称 - 电子邮件地址
Certificate.Issuer.AlternativeName.DNSName
颁发者备用名称 - DNS 域名
Certificate.Issuer.AlternativeName.DirectoryName
颁发者备用名称 - 目录名称
Certificate.Issuer.AlternativeName.UniformResourceIdentifier
颁发者备用名称 - 统一资源标识符
Certificate.Issuer.AlternativeName.IPAddress
颁发者备用名称 - IP 地址