The 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.
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:
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
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.
Now you can use the command
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
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:
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.
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.
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.
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..
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
- Installing The Mosquitto broker on Windows and Linux
- Configuring and Testing MQTT Topic Restrictions
- Configuring Logging on Mosquitto
- Mosquitto MQTT Bridge -Usage and Configuration
- Mosquitto SSL ConFiguration – MQTT TLS Security
Other Related Articles and Resources:
- MQTT for Beginners
- Using the Paho MQTT client for beginners
- Beginners Guide to MQTT Security Mechanisms







Hi Steve,
Can we use databases for the authentication and is that necessary to restart config files after adding new users ?
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
thanks
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?
Only reloads the config file
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
It doesn’t really impact current implementations as they don’t use it and existing authentication mechanisms have been retained.
I don’t think it will simplify authentication as it is pretty simple as it stands.
It is meant to be used to create more sophisticated authentication schemes. See this Hive article
https://www.hivemq.com/blog/mqtt-5-foundational-changes-in-the-protocol/
Excellent article! Thanks a lot, Steve!!! Congratulations!
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.
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.
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
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?
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?
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?
Yes you need to use the same port on client and server
Also how do i use kill-HUP in windows?
You can’t as far as I know
So use linux for make dynamically add user
Thanks
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?
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
Hi
If i have over 10k users,does mosquitto can load password file?(we assume password file is 10mb)
Thanks
Hi
Sorry but I’ve never tried it but would expect it to work. The fiel size seems large to me as there isn’t much in it.
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
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”)
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.
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.
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
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
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
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?
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.
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.
You can use the mosquitto_pub client that comes with the install on windows. I have a beginners tutorial here http://www.steves-internet-guide.com/mosquitto_pub-sub-clients/.
The only problem is that is is more difficult to automate than using python scripts.
Thanks,
It is already resolved 🙂
Thanks,
It is already resolved 🙂
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?
What client software are you using?
dear steve
I have a question
can I use this auth-plugin (https://github.com/jpmens/mosquitto-auth-plug) in the windows?
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?
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.
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.
Jack
Here is a tutorial that covers it
http://www.steves-internet-guide.com/topic-restriction-mosquitto-configuration/
Rgds
steve
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
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
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…
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
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.
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
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
Nice write up! Thanks, Steve!