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 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 mosquitto-auth-plug source and create a suitable configuration file
  • Edit the created file to suit your needs
    • vi
  • Install the appropriate backend developer files (e.g. redis backend)
  • Inside the mosquitto-auth-plug directory use the make command to build the plugin and move it next to mosquitto.conf file
    • make
    • mv /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 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_plugin /etc/mosquitto/

auth_opt_backends mysql


auth_opt_redis_port 12885


auth_opt_port 3306

auth_opt_dbname sql366410

auth_opt_user sql366410

auth_opt_pass nX4*jZ3%

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)

auth_opt_anonusername AnonymouS

Read the documentation at 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.

  1. 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
  2. Use the np application found in the mosquitto-auth-plug directory to generate the PBKDF2 strings for passwords
  3. Create new user records with generated PBKDF2 strings in the mysql user table
  4. Edit the acl table to add new topics and restrictions for the created users
  5. Start the mosquitto broker with the modified configuration
    • /usr/local/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf
  6. Run a sample sub instance
    • mosquitto_sub -t “topic” -u userName -P password
  7. 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).



  • csuarezgfx

    great tutorial thank you. I think I finally got it to work. Would you consider walking us through the pub/sub commands using the auth-plug. I think you could make a great tutorial demonstrating how it works, when it works and when it could possibly give you unexpected responses.

  • csuarezgfx

    These lines in your config file will cause this error when trying to authenticate:

    1444251139: |– mosquitto_auth_unpwd_check(S1)
    1444251139: |– ** checking backend mysql
    You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near ‘��S1’’ at line 1

    config lines:
    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)

    all you have to do is replace the curly single quotes with the keyboard straight single quotes and make sure that the final %d also has single quotes:

    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’)

    Thank you for the tutorial

  • My-Classes

    Thank you for the comment. Yes, the quotes are due to the HTML editor transcription and correcting them as you suggested should work.

    Wish you the best

  • yuvraj

    can u just give the after installation process work … after i have installed what are the parameters that i should work upon and how ..becos i’am getting confused in that part only username ,password ,database generation
    ,then what if i have sensors attached and want to transfer the sensor data with the whole implementation process … can u help me out in this regard

  • yuvraj

    in Edit the Mosquitto configuration what is mosquitto.conf.example

    here mosquitto.conf.exmple …what is this can u clarify me ??
    becos im trying to find it in my pi but its saying its missing

  • yuvraj

    can we use this process to get sensor data .. if yes then how can we do it ….. i’am using and dht11 sensor …. how to get this whole process

  • My-Classes

    Hello Yuvraj, if your sensor is capable of sending data to MQTT, then the rest of the flow is same. To get data from the sensor, you may have to interface it with relevant software that can read the signals / data from the sensors and then relay it back to MQTT.

  • yuvraj

    softwares like ccan u suggest few

  • yuvraj

    weell i mnot able to do these steps kindly tell me and explain me ….. i have tried several times but no sucess so tell me perfect step each and everything …… if possible