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 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 dong 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.

create-password-file-1

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:

create-password-file-2

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:

mosquitto-passwords

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 mosquiito.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.

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:

send-hup-mosquitto

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

reload-conf-mosquitto

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:

username_pw_set(username=”roger”,password=”password”)

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.

mqtt-password-examples

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.

Example:

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.

mqtt-password-authentication-example-3

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..

mqtt-password-authentication-example-4

Video

I have created a video that covers the main point above.You can find it here.

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

Summary

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.

Demo Code

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

Mosquitto Configuration Tutorials

Other Related Articles and Resources:

Facebooktwittergoogle_plusredditpinterestlinkedinmail

48 comments

  1. 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.
      rgds
      steve

  2. 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?

  3. 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

  4. Hi! I’m reading several of your guides regarding MQTT, and I appreciate how thorough your explanation is.

    Quick question:
    Would it make sense to have a separate username and password for all clients?

    I’m starting out with MQTT and ESP8266, projects involving temp/humidity shown on epaper, plant monitors etc.
    I’m worried about safety with WiFi transmission, TLS doesn’t seem to be that common with MQTT and ESP8266, so I’m a bit unsure how I should proceed.

    I guess I’ll skip TLS while prototyping, as I’m not using MQTT at all at this time anyways.

    1. It will obviously depend on what the devices are used for as to whether or not you use username/password.
      I like to keep things simple and so would go for no username password if possible and only a single password for all devices as the next best option.
      A password for each device would be difficult to manage if you had lots of them.
      As for TLS then again if your data isn’t sensitive then why encrypt?
      I would expect most local networks wouldn’t use encryption.
      However for control data I would employ some form of security even on local networks.
      Encryption would mainly be done on the connection to the Internet.
      I think on local networks you will see topic restrictions by client id as a common option for basic security.

  5. update : I have figured out the problem: the server (IBM IoT) config did not accept port 1883. Need go to security/connection security to change the setting

  6. Hi Steve,
    I am trying to publish a message to IBM cloud, and use on_connect to check the connection.

    def on_connect(client, userdata, flags, rc):
    print(“Connected flags “,str(flags),”result code “,str(rc))
    clientID =”d:” + organization + “:” + deviceType + “:” + deviceID
    client = mqtt.Client(clientID)
    brokerAddress=organization+”.messaging.internetofthings.ibmcloud.com”
    client.username_pw_set(username=”use-token-auth”,password=password)
    client.on_connect=on_connect
    client.connect(brokerAddress,1883,60)
    payload ={‘temp’:20}
    client.loop_start() #start the loop
    client.publish(“iot-2/evt/will/fmt/json”, json.dumps(payload))
    time.sleep(4) # wait
    client.loop_stop() #stop the loop

    the terminal then gives me this: (‘Connected flags ‘, “{‘session present’: 0}”, ‘result code ‘, ‘5’)
    sometimes 2-3 of that same line. I don’t get any case where rc parameter returns 0.
    Can you give me an idea where i did wrong?

    1. update: I just used a MQTT tool (MQTT Helper on Bluemix) and also cannot connect with “Code: 7, Message: AMQJS0007E Socket error:undefined.”
      looks like my authentication info is not correct?

      1. update : MQTT Helper is now working, i needed to change port 1883 to 443. So the authentication was not the problem. Should I use port 443 in paho as well?

  7. Hello
    Thank you for your good topic
    I have question
    You said that after add user to password file,it is necessary to call kill-HUP PID in command line
    OK
    Now assume in my app,user register in app and i need add this user in password file,how do it?
    Make script and use it for add user in file and restart broker?
    If i restart broker,are they losing all conenction?

    1. The broker runs as normal
      Your script updates the password file and then issue the hup command on the broker process to tell the broker to reload the files.All users stay connected

  8. Just to clarify, if you are running in Windows as a service, Mosquitto will look for mosquitto.conf in its executable’s folder. If there are any errors in the conf file you will get a message that the service started then stopped.

    Before running as a service, run from the command prompt, and as described, specify the conf file explicitly, like so (note the quote marks):

    “C:\Program Files (x86)\mosquitto\mosquitto.exe” -v -c “C:\Program Files (x86)\mosquitto\mosquitto.conf”

    If there are any errors in the conf file then the console will report that error and line number. Fix, rinse and repeat. Once it runs from the command line then you can run as a service without further issues.

    NOTE for windows:
    In mosquitto.conf in windows, specify paths **without quotemarks**, for example:

    password_file C:\Program Files (x86)\mosquitto\passwords.txt

  9. Hello Steve,

    how can I use the given password which I`ve protect in my passwordfile.txt in my python script?
    I’ ve rewrite the config file and after that I`ve reboot the Raspberry Pi.
    I’ m using the command username_pw_set(username=”roger”,password=”password”) in my script but without password I get an error when I’ m running the script. I think the password doesn’ t be use of passwordfile.txt.
    Can you give me please an example of the line:
    username_pw_set(username=”roger”,password=”password”)

    1. Have you created your own password file?
      The command you are using is correct but you need to use it before you connect to the broker.
      Are you trying to use the command without the password?
      If you are then don’t configure a passwords file in the mosquitto.conf file and allow anonymous access.

  10. Davide:
    There is no killing of the process. If you look at what steve said, he’s talking about -HUP, which sends
    a hangup signal to the process, to let it know it should reload the configuration, but this won’t stop
    the process nor affect currently connected users, this is a normal Linux behavior.

  11. Thank you for the answer steve
    To me the need to kill the process to provision a new user is non sense…you disrupt the service of all other users to provision a new one !??!
    Really don’t understand this limitation but if you have a multi user/multi device environment this make mosquitto almost unusable
    Any idea or workaround to overcame this big limitation ?
    In my application I would like provision via script the new users (everyone should have it’s own credential) without impacting the MQTT service of all the others

  12. Very clear and comprehensive tutorial, thanks

    I have mosquitto installed on linux, I have created PWD file and added few user/pwd with proper command but in order to make it effective in need to stop / start mosquitto process !

    Is this normal? Is there any way to make mosquitto load the passwordfile run-time without any re-start ?
    I would like to provision via script different MQTT client with different login/pwd and to me seems very strange to have to restart the process every time I provision a new client

    thanks for the help
    Davide

    1. On linux you can tell it to reload the configuration files by using the following
      kill -HUP PID
      where PID is the process id of the mosquitto broker. Use ps -a to find the PID

  13. Hi, i have encountered a problem when i try to connect to my broker after modified the configuration file (the setting for password_file and allow_anonymous). After i type in the command mosquitto -c c:\mosquitto\mosquitto.conf (this is my conf file path), the broker didn’t start. But if i commented the setting i modified as stated above, the broker can start and running without any issue. Do you have any idea what caused this problem?

    1. Oh never mind, it’s just that the password file created with the command isn’t .txt file and i forgot to change the extension type.

  14. Hi, Steve.

    Do we really have to write Paho Python client code in order to implement the user name/password every time a client connect to the broker?

    Can we just do configuration on the command prompt(i’m using windows to do all this tasks) and still get the same result? I don’t have any knowledge regarding python code so it might be difficult to me to write the client code.

  15. Hello please help me.
    How to connect from ssl, with username and password

    Code:
    SocketConnection socket;
    socket = (SocketConnection) Connector.open(“ssl://192.168.1.10:1883”);
    How send username and password to connect a mosquitto?

  16. thank you really.
    can you provide any article about “role-based access control” ?
    and another question:
    can we use MYSQL database (or any database) for authentication and authorization in the broker side?

    1. Jack
      You can use other authentication methods but I haven’t looked into it yet.
      Here is a plugin https://github.com/jpmens/mosquitto-auth-plug that should do it but it looks quite involved as regards setup.
      I’ll put it on my todo list and have a go.
      I haven’t seen anything on role passed authentication but expect it will be implelented at some time.

  17. Hi steve
    thank you very much for your help.
    I corrected the problems. I didnt understand what was the problem, because everything was exacthly same as you.
    finally after some re-install, i could run it correctly.
    I have another question.
    How can I implement an Access control list (ACL) in this local mosquito broker?
    thank you very much.

  18. hi.please help me.
    before that I see your site, I had installed a mosquitto successfully in windows 10
    and it worked perfectly with chrome LENS extension.
    also I must say that my mosquito folder did not have some files that you list in the :
    “http://www.steves-internet-guide.com/install-mosquitto-broker”
    , but worked good.
    then I wanted to add username/password authentication.here was where I saw your site.
    I read this article :
    ”http://www.steves-internet-guide.com/mqtt-username-password-example/”
    and followed it step by step.
    But I don’t know why username/password authentication does not work at all and client can connect with wrong username/password!
    also I have to say that :
    1. I’m using chrome LENS extension to connect to this local mosquito.
    2. I used the mosquitto folder that you add in “http://www.steves-internet-guide.com/install-mosquitto-broker” also, but did not work username/password auth again.
    what is the problem?please clarify me
    thank you very much

    1. Hi
      It is probably a configuration file issue. Either you haven’t made the correct edits or you aren’t using the config file. Are you starting mosquitto manually from the command line as
      mosquitto -c c:\mosquitto\mosquitto.conf ( that is the location of my config file your will be different).
      You need to disable anonymous access and set up a password file in the config file.
      Rgds
      Steve

      1. thanks for reply
        I can enable username/password authentication now.
        so that my chrome LENS can not connect to the local mosquitto.
        but now there is another problem :
        when I changed mosquitto.conf file, do I have to restart mosquitto service from services panel in the windows 10?
        when I tried to restart the mosquitto service, it give me the following error:

        “The Mosquitto Broker Service on local computer started and then stopped ,Some services stop automatically if there are not in use by other services or programs ”

        then I removed my changes in mosquitto.conf file (place # againfor allow_anonymous and password_file) , and tried to restart the mosquitto service again and it started successfully.

        my questions :
        1. do we need to restart manually mosquitto service?
        2. why restarting mosquitto service after modifying “mosquitto.conf” gives me the above error?

        thanks a lot…

        1. Jack
          When you make any changes to the conf file the mosquitto broker needs to be restarted. Because Windows has installed Mosquitto as a service you will need to stop and start this service.
          This is OK in a production environment but for testing I disable the mosquitto service and start it manually from the command prompt.
          Doing it this way I can also see the console log and use any conf file I want.
          Does this make sense?
          Steve

  19. Hi,
    What about authentificating and registering users from client (eemple ios swift app), hat is the best solution, the mosquitto broker is hosted on a memory constrained debian 8 vps.
    Thank you.

  20. Hi Steve,

    Very useful article !

    By the way, do you have any idea on how to control the mosquitto broker , for example when it hangs…?

    So, when mosquitto broker hangs, I want to somehow re-start it or do something so that it will be functional again.
    Could you please give me example…

    Thank you
    Novita

    1. Novita
      That would be an operating system task as the broker will be running as a service. I haven’t looked at that aspect yet.
      Steve

Leave a Reply

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