EMQ X MQTT broker HTTP authentication plugin tutorial

Before reading this tutorial, we suppose that you already known some basic MQTT and EMQ X MQTT broker knowledge.

emqx_auth_http will throw authentication and access control event for each MQTT client to the user's own WebServer, to implement authentication and ACL. The architecture logic is:

emqx_auth_http.png

The events that emqx_auth_http mainly process are :

  1. Authentication: Whenever the MQTT client receives a CONNECT request, EMQ X MQTT broker will fill the parameter (such as ClientId, Username, and Password, etc) brought by the client to the HTTP parameter, and then will initiate a request to the Web Services the user-configured themselves. If successful request, allowing this MQTT client to connect.
  2. ACL: Whenever the MQTT client implements the PUBLISH and SUBSCRIBE operation, EMQ X will fill the parameter (such as ClientId and topic, etc) to the HTTP parameter, and then will initiate an ACL request to the Web Services the user-configured themselves. If successful request, allowing this PUBLISH/SUBSCRIBE.

Actually, in the EMQ X cluster, emqx_auth_http is just a simple and stateless HTTP Client for the user's Web Service. emqx_auth_http only sends the internal EMQ X login authentication and ACL control requests to the user's Web Services, and did some logic processing.

Introduction to the plugin configuration items

The following content list the default configuration file of this plugin 3.1.0, although there is a lot of content, only configured three HTTP Request parameters.

  • MQTT client access authentication(auth_req)
  • Judging whether is a superuser(super_req)
  • ACL request(acl_req)

We will take the authentication as an example. Every configuration item represents:

Configuration Item Description
auth.http.auth_req configuring the URL path address the auth_req request needs
auth.http.auth_req.method configuring the HTTP Method the auth_req uses, only support GET/POST/PUT
auth.http.auth_req.params configuring parameter list of auth_req request

As for params item, it supports various parameter placeholders. The comment of the configuration file included the meanings of the placeholder. For example:

auth.http.auth_req.params = clientid=%c,username=%u,password=%P

It means that the auth_req includes three parameters. The keys of these three parameters are clientid, username and password respectively. When accessing the client, the values of these keys will be replaced by the real values of ClientId, Username, and Password.

All default configurations are:

##--------------------------------------------------------------------
## Authentication request.
##
## Variables:
##  - %u: username
##  - %c: clientid
##  - %a: ipaddress
##  - %P: password
##  - %cn: common name of client TLS cert
##  - %dn: subject of client TLS cert
##
## Value: URL
auth.http.auth_req = http://127.0.0.1:8991/mqtt/auth
## Value: post | get | put
auth.http.auth_req.method = post
## Value: Params
auth.http.auth_req.params = clientid=%c,username=%u,password=%P

##--------------------------------------------------------------------
## Superuser request.
##
## Variables:
##  - %u: username
##  - %c: clientid
##  - %a: ipaddress
##
## Value: URL
auth.http.super_req = http://127.0.0.1:8991/mqtt/superuser
## Value: post | get | put
auth.http.super_req.method = post
## Value: Params
auth.http.super_req.params = clientid=%c,username=%u


##--------------------------------------------------------------------
## ACL request.
##
## Variables:
##  - %A: 1 | 2, 1 = sub, 2 = pub
##  - %u: username
##  - %c: clientid
##  - %a: ipaddress
##  - %t: topic
##
## Value: URL
auth.http.acl_req = http://127.0.0.1:8991/mqtt/acl
## Value: post | get | put
auth.http.acl_req.method = get
## Value: Params
auth.http.acl_req.params = access=%A,username=%u,clientid=%c,ipaddr=%a,topic=%t

How to return

After understanding how to configure the emqx_auth_http plugin, the rest key thing is how to let the Webserver returning succeeded or failed.

Authentication

Authentication successed:

HTTP Status Code: 200

Ignore this authentication:

HTTP Status Code: 200
Body: ignore

Error:

HTTP Status Code: Except 200

The super user

Confirmed super user:

HTTP Status Code: 200

Non-super user:

HTTP Status Code: Except 200

ACL authentication

Allow PUBLISH/SUBSCRIBE:

HTTP Status Code: 200

Ignore this authentication:

HTTP Status Code: 200
Body: ignore

Refuse this PUBLISH/SUBSCRIBE:

HTTP Status Code: Except 200

The streaming database built for IoT data storage and real-time processing.

Fully managed MQTT 5.0 IoT cloud, start a 180-day free trial.

Related Links

MQTT X v1.3.0 was officially released - Cross-platform MQTT 5.0 desktop test client

[MQTT X](https://mqttx.app) is a cross-platform MQTT 5.0 desktop test client provided by the world's leading open source IoT middleware provider [EMQ](https://emqx.io) , which supports macOS, Linux, Windows. The user interface of **MQTT X** simplifies the operation logic of the page with the pattern of chatting software. Users can quickly create multiple simultaneous-online MQTT clients to test the connection/publish/subscribe functions of MQTT/TCP, MQTT/TLS and other MQTT protocol features.

EMQ X Newsletter 202104

In April, EMQ X 4.3-beta.5 release summed up all the fixes has to be done before 4.3.0 release. This allowed us to gradually shift our focuses towards 5.0 development.

Retained message and message expiration interval of EMQ X MQTT 5.0 broker

The message retention function of [EMQ X MQTT Broker](https://emqx.io) is implemented by the `emqx_retainer` plugin, which is enabled by default. By modifying the configuration of the` emqx_retainer` plugin, you can adjust the EMQ X Broker's retention message Location, restrict the number of retained messages and maximum payload length, and adjust the expiration time of retained messages.