It is important to configure authentication on your Mosquitto instance, so unauthorised clients cannot connect.

In Mosquitto 2.0 and up, you must choose your authentication options explicitly before clients can connect. In earlier versions the default is to allow clients to connect without authentication.

There are three choices for authentication: password files, authentication plugins, and unauthorised/anonymous access. It is possible to use a combination of all three choices.

It is possible to have different listeners use different authentication methods by setting per_listener_settings true in your configuration file.

As well as authentication you should also consider some form of access control to determine what clients can access which topics.

Password files

Password files are a simple mechanism of storing usernames and passwords in a single file. They are good if you have a relatively small number of fairly static users.

If you make changes to the password file you must trigger the broker to reload the file by sending a SIGHUP message:

kill -HUP <process id of mosquitto>

Creating a password file

To create a password file, use the mosquitto_passwd utility, use the line below. You will be asked for the password. Note that -c means an existing file will be overwritten:

mosquitto_passwd -c <password file> <username>

To add more users to an existing password file, or to change the password for an existing user, leave out the -c argument:

mosquitto_passwd <password file> <username>

To remove a user from a password file:

mosquitto_passwd -D <password file> <username>

You can also add/update a username and password in a single line, but be aware that this means the password is visible on the command line and in any command history:

mosquitto_passwd <password file> <username> <password>

Configuring the broker

To start using your password file you must add the password_file option to your configuration file:

password_file <path to the configuration file>

The password file must be able to be read by whatever user Mosquitto is running as. On Linux/POSIX systems this will typically be the mosquitto user, and /etc/mosquitto/password_file is a good place for the file itself.

If you are using the per_listener_settings true option to have separate security settings per listener, you must place the password file option after the listener it is for:

listener 1883
password_file /etc/mosquitto/password_file

Authentication plugins

If you want more control over authentication of your users than is offered by a password file, then an authentication plugin may be suitable for you. The features offered depend on which plugin you use.

Configuring the plugin

Configuring a plugin varies depending on the version of Mosquitto plugin interface the plugin was written for, either version 2.0 and up, or 1.6.x and earlier.

For 1.6.x and below, use the auth_plugin option. These plugins are also supported by version 2.0:

listener 1883
auth_plugin <path to plugin>

Some plugins require extra configuration which will be described in their documentation.

For 2.0 and up, use the plugin option:

listener 1883
plugin <path to plugin>

Available plugins

  • Dynamic security, for 2.0 and up only, provided by the Mosquitto project to give flexible in-broker clients, groups, and roles that can be administered remotely.
  • mosquitto-go-auth, which offers the use of a variety of backends to store user data, such as mysql, jwt, or redis.

Unauthenticated access

To configure unauthenticated access, use the allow_anonymous option:

listener 1883
allow_anonymous true

It is valid to allow anonmous and authenticated access on the same broker. In particular the dynamic security plugin allows you to assign different rights to anonymous users than to authenticated users, which may be useful for read-only access to data for example.