Mosquitto Username and Password Authentication -Configuration and Testing

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

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

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

When Using MQTTv5 a return string of Not Authorised is returned and the actual code is 135.

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

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

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.

It can be configured 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

• 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
• Understanding and Using the Mosquitto Dynamic Security Plugin

Other Related Articles and Resources:

• MQTT for Beginners
• Using the Paho MQTT client for beginners
• Beginners Guide to MQTT Security Mechanisms