How to make Access Control Lists (ACL) work for Mosquitto MQTT Broker with Auth Plugin?
If you planning to strengthening your MQTT service, then access control lists (ACL) are mandatory. Mosquitto broker supports this ACL feature through auth plugins.
One versatile auth-plugin for mosquitto that you should consider using is https://github.com/jpmens/mosquitto-auth-plug. It is very flexible, in that it can support multiple backends as auth provider databases, ranging from CDB, Redis to MySQL and Http. However, getting it compiled and making it start to work is not that straight forward or easy. Hence, this post. It gives some starting point to our students who are venturing into Mosquitto Authentication systems to get started.
Building the Mosquitto-Auth-Plugin
The below steps help you for Ubuntu or its variants. Similar steps should get you going with CentOS or other variants if you replace the apt-get commands with their equivalents, such as yum etc.
- Install required helper and developer packages first
- sudo apt-get install libc-ares-dev libcurl4-openssl-dev libmysqlclient-dev
- Get Mosquitto source and build it
- Get source from: http://mosquitto.org/download/
- tar xvzf mosquitto-1.3.5.tar.gz
- cd mosquitto-1.3.5
- make mosquitto
- sudo make install
- Get mosquitto-auth-plug source and create a suitable configuration file
- git clone https://github.com/jpmens/mosquitto-auth-plug.git
- cd mosquitto-auth-plug
- cp config.mk.in config.mk
- Edit the created config.mk file to suit your needs
- vi config.mk
- Install the appropriate backend developer files (e.g. redis backend)
- git clone https://github.com/redis/hiredis.git
- make && make install
- Inside the mosquitto-auth-plug directory use the make command to build the plugin and move it next to mosquitto.conf file
- mv auth-plug.so /etc/mosquitto/
- Edit the Mosquitto configuration file
- mv /etc/mosquitto/mosquitto.conf.example /etc/mosquitto/mosquitto.conf
- vi /etc/mosquitto/mosquitto.conf
Editing the Mosquitto configuration for enabling Auth Plugin
Inside your mosquitto.conf file you should indicate the auth-plugin options to let the mosquitto MQTT broker know that you are planning on using an auth-plugin and where it is located on the disk.
Note: Mosquitto MQTT broker usually runs under the identify of an user named mosquitto. So, you should ensure the path to auth-plug.so is accessible to the mosquitto user. You can set permissions using chown and/or chmod commands.
Edit the /etc/mosquitto/mosquitto.conf file to have its content look something like below (you should search for auth_plugin field in that file):
auth_opt_userquery SELECT pw FROM users WHERE username = ‘%s’
auth_opt_superquery SELECT COUNT(*) FROM users WHERE username = ‘%s’ AND super = 1
auth_opt_aclquery SELECT topic FROM acls WHERE (username = ‘%s’) AND (rw >= %d)
Read the documentation at https://github.com/jpmens/mosquitto-auth-plug to know more about what these fields are how to customize them.
Testing the ACL workings with Mosquitto Broker
Once you have edited the mosquitto configuration file to indicate the auth-plugin presence and its backend options, you are ready to deploy it. But before that you need to actually create the user and acl databases in your chosen backend database. In the below few steps are illustrated for mysql as an example database, but the steps should be similar for other databases too.
- As a first step, you want to create tables inside your chosen backend database. For mysql you can do this easily using the sample sql script in the examples directory of mosquitto-auth-plug source code
- Use the np application found in the mosquitto-auth-plug directory to generate the PBKDF2 strings for passwords
- Create new user records with generated PBKDF2 strings in the mysql user table
- Edit the acl table to add new topics and restrictions for the created users
- Start the mosquitto broker with the modified configuration
- /usr/local/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf
- Run a sample sub instance
- mosquitto_sub -t “topic” -u userName -P password
- Run a sample pub instance
- mosquitto_pub -t ‘topic’ -m message -u userName -P password
Points to remember:
- You never store actual passwords in the backend databases. Only the PBKDF2 strings of the passwords.
- When you are starting mosquitto_sub and mosquitto_pub you need to use original passwords (and not PBKDF2 strings).
- PBKDF2 strings are not reversible – that is, for the same password you are not guaranteed to get the same PBKDF2 string every time. They change. Which means, from PBKDF2 string you cannot get back your original password – so you have to remember your passwords (and not rely upon the database to get them back).