Mosquitto Username and Password Authentication -Configuration and Testing

mqtt-passwords-iconThe Mosquitto MQTT broker can be configured to require client authentication using a valid username and password before a connection is permitted.

The username and password combination is transmitted in clear text, and is not secure without some form of transport encryption.(SSL)

However using username and password authentication does provide an easy way of restricting access to a broker.

Note: The username used for authentication can also be used in restricting access to topics.

In this tutorial we look at how to configure username and password restrictions on the mosquitto broker, and look how it works by looking at some connection examples using simple Python test scripts.

Mosquitto Broker Configuration

All forms of restrictions i.e. client id, username/password, topic etc are implemented on the MQTT broker.

Once implemented on the broker it is up to the client to comply with these restrictions in order to connect, subscribe and publish.

To configure the Mosquitto broker you will need to:

  • Create a password file
  • Edit the mosquitto.conf file to force password use.

To create a password file you need to use the mosquitto_passwd utility that comes with the client tools when installing the mosquitto broker.

There are several ways of doing this:

Method 1

Create a simple text file and enter the username and passwords, one for each line, with the username and password separated by a colon as shown below.


Close the file in the text editor.

Now you need to convert the password file which encrypts the passwords, Go to a command line and type:

mosquitto_passwd -U passwordfile

Now if you open the password file again you should see this:


The passwords file is now ready to use.

Method 2

You create the password file using the command

mosquitto_passwd -c passwordfile user

Note you need to enter a username for this to work. This adds the user to the password file.

You will be prompted to enter a password for the user.

Be careful as the password isn’t echoed and it doesn’t look like it is being accepted but it is.

Now you can use the command

mosquitto_passwd -b passwordfile user password

to add additional users to the file.

The screenshot below shows the process:


You can also delete users from the password file using the command

mosquitto_passwd -D passwordfile user

Important Note: The mosquitto_passwd utility did not work on my Windows XP installation, and I had to use the utility on my Linux installation.

However it did work on windows 7 and 10 but I needed to add the msvcr100.dll file. See Installing the Mosquitto Broker-client scripts

Using the Password file

You will need to copy the password file into the etc\mosquitto folder  ( linux ) or the mosquitto folder(windows) and then edit the mosquitto.conf file to use it.

The two changes you normally make in the mosquiito.conf file are to set allow anonymous to false and to set the password_file path.

It should be noted that since mosquitto v1.5 authentication is no longer a global setting but can be configured on a per listener basis.

However this must be enabled using the per_listener_settings setting at the top of the file.

To enable it use:

per_listener_settings true

mosquitto.conf- Example Settings

allow_anonymous false
password_file c:\mosquitto\passwords.txt #Windows machine

Example Password File

An Example password file called pwfile.example is provided with the installation.

The file has three users:

  • roger
  • sub_client and
  • pub_client.

All three users have a password of password.

Reloading the Password File

If you make a change to the configuration files including the password file you can restart the mosquitto broker.

However on Linux you can reload the configuration files without restarting the broker by using the following:

kill-HUP PID # where PID is the process ID as shown below:


If you look at the console it should show that the conf files have been reloaded


Paho Python MQTT Client Configuration

To connect to a broker that implements username/password restrictions you need to use the helper method username_pw_set() of the Paho client.

This you must call before establishing the connection.

The format is:


Detecting Authentication Errors

If you try to connect to a broker without the correct authentications details the connection will be rejected.

To detect this you will need to examine the on_connect callback.

If you examine the documentation for the on_connect callback method you will see that it accepts 4 parameters.

on_connect(client, userdata, flags, rc):

The rc parameter is the return code and should be 0 for a good connection.

A return code of 5 indicates an authentication error.

Password Connection Examples:

The screenshots below show the results of connecting a client to a broker with incorrect and correct passwords.

The on_connect callback method shown below just prints out the return code and looks like this:

def on_connect(client, userdata, flags, rc):
    print("Connected flags ",str(flags),"result code ",str(rc))[/outline]

Example 1– In the first attempt the broker isn’t configured to require passwords, and so it simply ignores the wrong password.

Example 2– In the second connection attempt the broker is configured to require a username and password, and rejects the connection attempt with the bad password.


Broker Access Control Explained

For username/password control to work correctly then there are two settings that need to be configured on the broker.

They are:

  • allow_anonymous and
  • password_file.


allow_anonymous false
password_file c:\mosquitto\passwords.txt #Windows machine

However the Password File is used (if present) ,even if the broker is set to allow_anonymous access.

The follow table shows how the anonymous access setting and the password file settings affect client access.

Anonymous access Password file Specified Access Restricted
True No No
True Yes Yes See Note 1
False No Yes -see Note 2
False Yes Yes

Note1: If a password file is specified then if the client sends a username/password then it must be valid other wise an authentication error is returned. If it doesn’t send one then none is required and a normal connection results.

Note 2: The client must send a Username and password, but it is not checked. If the client doesn’t send a username/password then and authentication error code is generated.

The following examples illustrate these two examples:

In this example we connect to a broker that allows anonymous access but is configured to use the password file.

You can see that if the client supplies a username/password then it is checked.


In this example we connect to a broker that allows anonymous access and is not configured to use the password file.

You can see that if the client supplies a username and password then it works even if they are invalid.However if it doesn’t supply the username/password then the connection fails..



I have created a video that covers the main point above.

Common Questions and Answers

Q- Can I use the same username and password on multiple clients?

A– Yes you can

Q- Is the username and password encrypted?

A– No not unless you are also using SSL on the connection

Q- Can I configure Mosquitto to use authentication on some ports and not others?

A- Yes since v1.5 Mosquitto supports authentication on a per listener basis but it must first be enabled.

Mosquitto v2-Mosquitto_ctrl

The Mosquitto_ctrl tool was introduced with mosquitto v2 and is used for dynamically making user and ACL changes on a mosquitto broker.

It effective replaces the password and ACL file and settings but is not enabled by default and is only likely to be used when an organisation has a large collection of brokers with many frequent changes. Using the Mosquitto_ctrl Tool


Username and password authentication is common on all computer systems and the Mosquitto MQTT broker supports this authentication mechanism.

To use Password authentication you need to configure the MQTT broker to require it.

The username and password are sent in clear text, and you will need to use TLS to secure it.

It can be configures as a global setting affecting all listeners or on a per listener basis.

Demo Code

Here is the python code that I used to create these examples.

Mosquitto Configuration Tutorials

Other Related Articles and Resources:


Please rate? And use Comments to let me know more


  1. Hi, Steve
    I have a question.
    What is the function of `per_listener_settings `? And what is the `listener` meaning?
    Since if I donot set `per_listener_settings TRUE`, even I set `allow anonymous FALSE`, I can still connect my broker without username/password. So I really want to know the function of `per_listener_settings `.

    Sorry about my English.

    1. mosquitto can listen on multiple ports. So if it is listening on port 1883 and 1884 and using the old version of mosquitto which didn’t have the per listener setting then if allow anonymous was set to False it would affect clients connecting to port 1883 and 1884.
      Now with per_listener set to True you can have allow anonymous for clients connected to 1883 and authentication on 1884
      Does that make sense?

  2. Good day, and firstly thanks for a very informative article.

    I do have a question, more related to ACL.
    I have created 2 users both with relevant passwords in the Password file, and in ACL-file listed user1 to be able to subscribe and publish to eg machine/#
    user2 I would only like to sub to machine/#
    In a nutshell, let’s say there is a switch on machine/switch1 then both user1 and user2 will be able to see the state of switch1. But the intention is for user1 to be able to control the switch, while user 2 will only be able to view the state changes.
    I have as example in acl_file the following:
    user user1
    topic machine/#

    user user2
    topic read machine/#

    Yet with both user password in file and acl, user2 can still also change the state of eg switch1

    1. Can you post the complete ACL file. I tried the ACL file you posted and it works as expected so something must be overriding it.

      1. Apologies, I see while the reply await approval, all the items in the text has lost its returns to next line.

        config file:
        allow_anonymous false
        password_file /etc/mosquitto/passwd
        acl_file /etc/mosquitto/aclfile
        listener 1884

        acl file:
        # This affects access control for clients with no username. topic read $SYS/#
        user reader
        topic read @E07C0E5B/#
        user @E07C0E5B
        topic @E07C0E5B/#
        # This affects all clients. pattern write $SYS/broker/connection/%c/state
        Thanks you for the response.

        1. Have you tested with a simple config file.
          allow_anonymous true
          listener 1884

          When testing security always do on step at a time so if that works test username/password and after that acl.
          you can test acl without passwords by commented out the password file but still send the username/password.

          1. Thank you so much Steve,
            I will revert to a fresh setup, basic config, like in your reply, and then add the acl file with single user first with read only access and test. from there replace that user with user2 for readwrite, and then both.
            Just a question re the first and last line on the acl file:
            “topic read $SYS/#”
            “pattern write $SYS/broker/connection.%c/state”
            These lines do not have relevance on the issue at hand in the manner it is currently structured?

          2. Hi
            the “topic read $SYS/#” should be ok.
            Not sure about the “pattern write $SYS/broker/connection.%c/state” would need to check that so leave it out for the time being

          3. Thanks you so much for taking the time and having the patience with us newbies on the web.
            Managed to get it working correctly, by starting over and following a step by step approach like you suggested starting with allow_anonymous , and adding users, password file, acl etc in small steps.
            Thanks again for a great site.

  3. Hello Steve,

    Does a client get a signal when user credentials is deleted from the broker and the client was already connected to the broker using the same user?


  4. Hi steve, can i have a different user name and pass for every user with a special topic? for example 1000 username , pass and topic

  5. How do I can prevent duplicate login user with the same username?
    In the current state, each client try to connect again and it is bad

  6. Hi Steve,

    Want to set up another listener with username / pw authentication (8884). Using systemctl, it fails.
    Running manually, the same. Curious if you know why this is puking:

    pi@digest:~$ cat /etc/mosquitto/mosquitto.conf
    # Place your local configuration in /etc/mosquitto/conf.d/
    # A full description of the configuration file is at
    # /usr/share/doc/mosquitto/examples/mosquitto.conf.example

    per_listener_settings true

    pid_file /var/run/
    listener 1883
    persistence true
    persistence_location /var/lib/mosquitto/
    log_dest file /var/log/mosquitto/mosquitto.log

    listener 1884
    allow_anonymous false
    password_file /etc/mosquitto/passwords

    listener 8883
    cafile /etc/mosquitto/ca_certificates/ca.crt
    keyfile /etc/mosquitto/certs/server.key
    certfile /etc/mosquitto/certs/server.crt
    require_certificate true
    use_identity_as_username true
    tls_version tlsv1.2

    log_dest syslog
    log_type information
    log_timestamp true

    include_dir /etc/mosquitto/conf.d

    pi@digest:~$ mosquitto -v -c /etc/mosquitto/mosquitto.conf
    Error: Unknown configuration variable “per_listener_settings”.
    Error found at /etc/mosquitto/mosquitto.conf:7.
    Error: Unable to open configuration file.
    pi@digest:~$ sudo tail -f /var/log/syslog
    Nov 27 22:17:54 digest systemd[1]: mosquitto.service: Failed with result ‘exit-code’.
    Nov 27 22:18:04 digest systemd[1]: mosquitto.service: Service hold-off time over, scheduling restart.
    Nov 27 22:18:04 digest systemd[1]: mosquitto.service: Scheduled restart job, restart counter is at 33.
    Nov 27 22:18:04 digest systemd[1]: Stopped Mosquitto MQTT Broker.
    Nov 27 22:18:04 digest systemd[1]: Started Mosquitto MQTT Broker.
    Nov 27 22:18:04 digest mosquitto[3851]: Error: Unknown configuration variable “per_listener_settings”.
    Nov 27 22:18:04 digest mosquitto[3851]: Error found at /etc/mosquitto/mosquitto.conf:7.
    Nov 27 22:18:04 digest mosquitto[3851]: Error: Unable to open configuration file.
    Nov 27 22:18:04 digest systemd[1]: mosquitto.service: Main process exited, code=exited, status=3/NOTIMPLEMENTED
    Nov 27 22:18:04 digest systemd[1]: mosquitto.service: Failed with result ‘exit-code’.
    pi@digest:~$ cat /etc/os-release
    VERSION=”18.04.3 LTS (Bionic Beaver)”
    PRETTY_NAME=”Ubuntu 18.04.3 LTS”

    1. It coul bde that you need to move these lines out of the listener section
      persistence_location /var/lib/mosquitto/
      log_dest file /var/log/mosquitto/mosquitto.log

      also I would always use a local config file when testing

      1. Stevie-wonder! Ordering was indeed the issue. Thank you so much for your attention 🙂
        For future reference, a simplified test config is as follows:
        pid_file /var/run/
        persistence true
        persistence_location /var/lib/mosquitto/
        log_dest file /var/log/mosquitto/mosquitto.log
        per_listener_settings true

        listener 1883

        listener 1884
        allow_anonymous false
        password_file /etc/mosquitto/passwords

        log_dest syslog
        log_type information
        log_timestamp true

        include_dir /etc/mosquitto/conf.d

        Thanks again!

  7. Hi steve,
    I tried the username password authentication but it doesnt seem to work.I am able to publish even if i have entered a wrong username password.My config file includes only allow_authentication false and my passwords file has username and encrypted passwords.I have reloaded the mosquitto.conf file .Where do you think i am going wrong?

        1. Are you sure that you a picking up the conf file what command are you using to start mosquitto and wher eis you conf file located? Are you on windows or linux.

          1. I am using linux.config file is in the location /etc/mosquitto .I use mosquitto -v to start mosquitto.Each time i edit the config file i run the mosquitto -c path_to_config file and then reboot.How do i make sure that its picking up the correct config.I had checked it making an mistake in the config file. mosquitto -v /mosquitto -c path_to_config wouldnt work.

          2. Hi steve,
            Thanku soo much..The questions you asked me really helped me. i was initially using mosquitto -v /mosquitto to start the mosquitto. I tried with sudo service mosquitto start and it works perfectly now !!


  8. Hi Steve, I did the set up of a mosquitto broker on a VPS, with access to one user and works well while in the VPS, if I try to connect from another computer I get no response, a timeout or no route to host message. I am guessing a DNS issue, but wanted to know if you have encountered a similar problem when trying to connect to a Mosquitto instance in a VPS from other devices. Thanks

    1. I would suspect that the ports are being blocked. I did a setup on an Amazon server instance and found they were all blocked by default.

      1. how do you suggest we can do this in application layer, or we can’t do it at all? Because I have seen cloudmqtt has this feature

        1. Cloudmqtt use a different mosquitto instance as far as I can tell but I will look at it again

  9. Hi Steve,
    I use username and password authentication in Mosquitto
    When i receive new published message,Can i know who username publish message?
    Example does Jack publish message or Rack

  10. Hi Steve, I would like to include a picture to my Node-Red Dashboard that subscribes to Mosquitto MQTT topics that currently shows Temperature and Humidity of the room the microcontroller is installed.

    For that I addapted a script that can be found at: to use Mosquitto instead of

    There are instructions to increase buffer size at PubSubClient.h as below:
    #define MQTT_MAX_PACKET_SIZE 1530
    But it has no effect at all for my problem.

    I have verified on the debug code on the link below that it prints the image buffer (in Hex) successfully at the Serial monitor of the microcontroller.

    I have also verified using WIRESHARK at the Ubuntu/Mosquitto server that only the first 8 bytes “FFD8FFE0” of the image taken do arrive to Mosquitto. I also found that this 8 bytes heading indicates it is a JPG image.

    Now I am trying to find out if the rest of the image (more than 2Kbytes in most cases) is lost at the ESP32CAM side or just ignored by Mosquitto for some buffering limitations.

    The printout of the debug and sketch are large and to avoid polluting your page I provide the link in case you have the time to take a look on it:

    Any assistance welcome.

    1. Hi
      I haven’t done much with arduino and C but I did get a pub/sub script running on arduino a while back and seem to remember a buffer limit of 128 bytes.
      I would assume that you would need to loop thought he image file sending 100bytes each time and then reassemble it at the other end.
      I did a similar thing with python
      As a matter of interest couldn’t you just send the temperature value rather than an image

      1. Dear Steve, thanks for your prompt response.
        I will investigate the link you provided.
        If nothing works sending the image in small pieces may be the solution.

        The reasons I want to send the picture as well is that it provides for a view of the environment on the room where the sensors are and second, it is a comercial solution and it looks nicer to have an overview of what is going on.

        Thanks again for your time

    2. i have entered my username and password to connect to the broker for lohin,even thought i entered the wrong password and username i am logging in .tell mi solution

  11. Hi Steve,

    1) I have followed your instructions and created a password.txt file
    cat /etc/mosquitto/conf.d/passwords.txt
    will display the long encrypted password

    2) I have found two mosquito.conf files on my system ( mosquitto is running on a QNAP in Container Station )
    find -name “mosquitto.conf” -print

    3) I have added two lines in both mosquito.conf files
    allow_anonymous false
    password_file /etc/mosquitto/conf.d/passwords.txt

    4) I stopped and restarted my mosquito app

    No difference
    I am still able to connect and publish anonymously (I am using MQTT.fx)

    Any idea ?
    Thanks for reading my comment,

    1. I would suspect that it isn’t picking up the conf file. Put an error in the file e.g
      allowanon false

      and see if it shows when you try starting.
      alternatively load it from the command line
      mosquitto -c conffile

      let me know what happens and use the ask steve page to send me the file

  12. How we can implement authentication to secure mqtt connection between client and server (say, nodemcu and raspberry)? and is it possible to implement without using third party cloudmqtt servers

    1. What mqtt broker are you using. If it is mosquitto then it supports basic authentication.

  13. Hi steve,

    I am using Mainflux – 3rd party IoT platform. I want to connect the paho mqtt client to the mainflux. Mainflux accepts token based authorization. How to pass the authorization token in the client.connect command?

    1. According to the github page it is sent as the password

      To use MQTT adapter you should use channels//messages. Client key should be passed as user’s password. If you want to use MQTT over WebSocket, you could use Paho client:


          1. I’m not a security expert but the encryption can be made as secures as SSl so just as secure. There is no verification on Broker so you could be using a none trusted broker but I’m not sure that is a problem as the message is encrypted.
            IMO the security solutions being proposed are based on web systems were the interaction is client server. MQTT is client-server-client and possibly more. It is more like email than the web.

  14. Hi Steve,
    Can we use databases for the authentication and is that necessary to restart config files after adding new users ?

    1. Yes there are plugin options but you need to write the code. I haven’t tried that or seen it done.
      When using the text file for passwords you need to get the broker to reread it after any changes.

  15. Nice write up Steve!

    I was wondering if I run the kill-HUP PID command will it stop the broker from receiving messages or only reloads the config file?

  16. In MQTT V5.0 just released, there’s an AUTH control message newly introduced. How does this impact current implementations? Can the new control message be used to simplify authentication? Thx

Leave a Reply to steve Cancel reply

Your email address will not be published. Required fields are marked *