HTTP 授权

EMQX 支持基于 HTTP 应用进行授权。此时，用户需在外部自行搭建一个 HTTP 应用作为数据源，EMQX 将向 HTTP 服务发起请求并根据 HTTP API 返回的数据判定授权结果，从而实现复杂的授权逻辑。

提示

Serverless 部署不支持 HTTP 授权。

HTTP 授权原理

授权过程类似一个 HTTP API 调用，EMQX 作为请求客户端需要按照 "API" 要求的格式构造并向 HTTP 服务发起请求，而 HTTP 服务需要按照 "客户端" 的要求返回结果：

• 响应编码格式 content-type 必须是 application/json。
• 授权结果通过 body 中的 result 标示，可选 allow、deny。
• 如果返回的 HTTP 状态码为 204，认证结果标示为允许发布或订阅。
• 如果 HTTP 状态码为 200 ，但响应体未按照预期格式返回（例如 result 字段缺失，或其值既不是 allow 也不是 deny），则该次授权结果将被视为 ignore。在未开启白名单模式的情况下，客户端将被允许发布和订阅任意主题，这可能导致未授权访问与数据暴露风险。
• 除了 200 和 204 以外的其他 HTTP 状态码都会被标记为ignore。例如当 HTTP 服务不可用或鉴权接口异常时，在未开启白名单模式的情况下，客户端将被允许发布和订阅任意主题，可能导致未授权访问与数据暴露风险。

响应示例：

HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow" | "deny" 
}

配置 HTTP 授权

在部署中点击 访问控制 -> 授权 -> 扩展授权，选择 HTTP 授权，点击配置授权。

进行身份授权时，EMQX Cloud 将使用当前客户端信息填充并发起用户配置的授权查询请求，查询出该客户端在 HTTP 服务器端的授权数据。

您可根据如下说明完成相关配置：

• 请求方式：选择 HTTP 请求方式，可选值： POST 或 GET。

  TIP

  推荐使用 POST 方法。 使用 GET 方法时，一些敏感信息（如纯文本密码）可能通过 HTTP 服务器日志记录暴露。此外，对于不受信任的环境，请使用 HTTPS。

• URL：输入 HTTP 服务的 URL 地址。

  • URL 地址必须以 http:// 或 https:// 开头。

  • 避免在域名中使用占位符。

  • 您可以在 URL 路径中使用以下占位符：

    • ${clientid}

    • ${username}

    • ${password}

    • ${peerhost}

    • ${cert_subject}

    • ${cert_common_name}

• 请求头（可选）：HTTP 请求头配置。可以添加多个请求头。

• OAuth2 客户端凭证（可选）：如果外部 HTTP 授权服务要求 EMQX 在发送授权请求前进行认证，启用 OAuth2 客户端凭证。此选项仅适用于运行 EMQX v6.1.4 或更高版本的部署。有关配置详情，参见配置 OAuth2 客户端凭证认证。

• 连接配置：在此部分进行并发连接、连接超时等待时间、最大 HTTP 请求数以及请求超时时间。

• 启用 TLS：配置是否启用 TLS。

• 连接池大小（可选）：整数，指定从 EMQX 节点到外部 HTTP Server 的并发连接数；默认值：8。

• 连接超时（可选）：填入连接超时等待时长，可选单位：小时、分钟、秒、毫秒。

• HTTP 管道（可选）：正整数，指定无需等待响应可发出的最大 HTTP 请求数；默认值：100。

• 请求超时（可选）：填入连接超时等待时长，可选单位：小时、分钟、秒、毫秒。

• 请求体：请求模板，对于 POST 请求，它以 JSON 形式在请求体中发送。对于 GET 请求，它被编码为 URL 中的查询参数（Query String）。映射键和值可以使用占位符。

TIP

• 如果当前部署为专有版，需创建 VPC 对等连接，服务器地址填写内网地址。
• 如果当前部署为 BYOC 版，需在您的公有云控制台中创建 VPC 对等连接，具体请参考 创建 BYOC 部署 - VPC 对等连接配置 章节。服务器地址填写内网地址。
• 若提示 Init resource failure! 请检查服务器地址是否无误、安全组是否开启。

请求格式与返回结果

当客户端发起订阅、发布操作时，HTTP 授权器会根据配置的请求模板构造并发送请求到外部 Web 服务（授权服务）。用户需要在请求模版中实现授权检查逻辑并确保授权检查结果能按要求返回，EMQX 根据响应结果判断是否具备权限。

请求格式

根据授权服务要求而定，可以使用 JSON 格式，支持在 URL 与请求体中使用以下占位符：

• ${clientid}: 客户端的 ID
• ${username}: 客户端登录时用的用户名
• ${peerhost}: 客户端的源 IP 地址
• ${proto_name}: 客户端使用的协议名称。例如 MQTT，CoAP 等
• ${mountpoint}: 网关监听器的挂载点（主题前缀）
• ${action}: 当前执行的动作请求，例如 publish，subscribe
• ${topic}: 当前请求想要发布或订阅的主题（或主题过滤器）
• ${qos}: 当前请求想要发布或订阅的消息 QoS
• ${retain}: 当前请求想要发布的消息是否为保留消息

响应格式

授权服务完成检查后，返回符合以下要求的响应：

• 响应编码格式 content-type 必须是 application/json。
• 如果返回的 HTTP 状态码为 200，授权结果通过 Body 中的 result 标示，可选值为：
  • allow：允许发布或订阅
  • deny：禁止发布或订阅
• 如果返回的 HTTP 状态码为 204，授权结果标示为允许发布或订阅。
• 除了 200 和 204 以外的其他 HTTP 状态码均标示为 ignore。例如当 HTTP 服务不可用或鉴权接口异常时，在未开启白名单模式的情况下，客户端将被允许发布和订阅任意主题，可能导致未授权访问与数据暴露风险。 响应示例：

HTTP/1.1 200 OK
Headers: Content-Type: application/json
...
Body:
{
    "result": "allow" | "deny"
}

TIP

推荐使用 POST 方法。 使用 GET 方法时，一些敏感信息可能通过 HTTP 服务器日志记录暴露。 对于不受信任的环境，应使用 HTTPS。

配置 OAuth2 客户端凭证认证

对于运行 EMQX v6.1.4 或更高版本的部署，HTTP 授权支持 OAuth2 客户端凭证。启用此选项后，EMQX 从配置的 Token 端点获取、缓存并自动刷新 Access Token。EMQX 向外部 HTTP 授权服务发送请求时，会通过 Authorization: Bearer <access_token> 请求头携带该 Token。

开启 OAuth2 客户端凭证，然后配置以下选项：

配置项	说明
Token 端点	必填。用于请求 Access Token 的 OAuth2 授权服务器端点。URL 必须使用 HTTP 或 HTTPS，且不能包含用户信息。
客户端 ID	必填。请求 Access Token 时使用的 OAuth2 客户端 ID。
客户端密钥	必填。请求 Access Token 时使用的 OAuth2 客户端密钥。
授权范围	可选。请求 Access Token 时使用的 OAuth2 授权范围。
Token 请求超时	向 Token 端点发送 HTTP 请求的超时时间。默认值为 5 秒。
Token 端点 TLS	为 Token 端点连接配置 TLS 相关参数。此设置独立于用于控制外部 HTTP 授权服务连接的启用 TLS设置。

EMQX 会向 Token 端点发送一个内容类型为 application/x-www-form-urlencoded 的 POST 请求。请求体包含 grant_type、client_id、client_secret 以及可选的 scope。Token 端点必须返回 HTTP 200 响应，且响应体为包含 access_token 的 JSON。响应体也可以返回 token_type 和 expires_in。如果返回 token_type，其值必须为 Bearer；如果返回 expires_in，其值必须为正整数。

重要提示

• 启用 OAuth2 后，不要为 HTTP 授权配置 Authorization 请求头。此请求头与 EMQX 自动生成的 Bearer 认证请求头冲突，EMQX 会拒绝该配置。
• Token 端点必须接受通过请求体表单字段传递的客户端 ID 和客户端密钥。不支持使用 HTTP Basic Authorization 请求头对 Token 端点进行认证。