Mosquitto ACL -Configuring and Testing MQTT Topic Restrictions

Not only can you restrict access to the Mosquitto MQTT broker using a username and password you can also restrict access to topics using an ACL (Access control list).

Unless you are running an open broker you will want to restrict access to topics so that only authorized users/clients can publish or subscribe to them.

Topic restrictions are configured on the Broker, and there is nothing to configure on the client.

Topic restriction is done in an access control list ( ACL ) file.

To enable topic restrictions you need to edit the mosquitto.conf file to use it.

Note: You should create a copy of the default file as a backup before you edit it.

You will find the setting in the Default authentication and topic access control section:

You need to add the following line (windows install example)

A default file ( aclfile.example ) is provided with the installation.

The contents of this file are shown below:

The default ACL file is very restrictive, and if implemented as is, would deny access to almost every topic to every user and client.

The file has effectively three sections:

• General section
• User specific section
• Client or user ID section

General Section

Entries here start with the keyword topic and apply to all clients except if the client provides a user name.

If the client provides a username then entries in this section are ignored for that user.

The entry in the default file is

This gives read (subscribe) access to any client that doesn’t supply a username to the topic $SYS/#.

User Section

This section uses the keyword user.

Each user can have topic entries that define access rights. The default file contains the following entry

This entry only apples if the client supplies a username otherwise it is ignored.

The entry means that a user named roger can publish and subscribe on the topic foo/bar.

No other user can publish or subscribe on any other topics.

Note: topic foo/bar is the same as topic readwrite foo/bar

Client or User ID Section

Every client will provide a client ID.

Entries in this section will only apply to the client with that Client ID.

The entry in the default file is

This means that a client with client name or ID of P1 can publish to the topic:

$SYS/broker/connection/P1/state

and a client with client ID of P2 can publish to the topic

$SYS/broker/connection/P2/state

Client P! cannot publish to :

$SYS/broker/connection/P2/state

However entries in the General section and User section will also need to be taken into consideration and could allow more access.

The user id is used in a similar fashion.

Would give user roger publish and subscribe access to:

phone/inbox/roger/#

Detecting Access Control Restrictions

Unfortunately it is not easy to detect ACL restrictions as they aren’t notified to the client.

This means that if a client subscribes to a topic and is denied by the ACL then the client doesn’t know it has been denied as it receives a positive acknowledgement.

In addition if a client publishes to a topic and is denied, again the client doesn’t know it has been denied as it receives a positive acknowledgement. (This you will see in the examples below)

The only way you can really detect a problem is by subscribing and publishing to a topic, and detecting or not detecting the published message.

Access Control Examples -General Settings

In the detailed examples below we look at topic restrictions using the general settings.

Later we look at User and client settings and how they are used to control topic access.

In the examples below we will use a simple python script to subscribe and publish and examine the results on the python client and on the broker console.

In the examples below we will do the following:

1. Subscribe and Publish to a topic with no ACL configured.
2. Subscribe and Publish to a topic using the default ACL file.
3. Edit the default ACL file to allow subscriptions and then Subscribe and Publish to a topic.
4. Edit the default ACL file to allow subscriptions and publishing and then Subscribe and Publish to a topic.

In each case we look at the various return and error codes shown by the client script, and on the Mosquitto broker console.

For the examples I have enabled logging of all error messages on the broker.

Example 1-Subscribe and Publish to a topic with no ACL configured.

With no ACL being used then we are free to subscribe and publish to any topic.

The screen shots below show that the messages we publish are received.

Example 2- Subscribe and Publish to a topic with the default ACL configured.

With the default ACL being used then we are restricted to reading the #SYS topic.

In the example we subscribe to house/# and publish to house/sensor1

The screen shots below show that the messages we publish are not received which is as expected.

However the Mosquitto server console logs a published denied message.

Example 3- Subscribe and Publish to a topic with an Edited ACL .

This time we edit the default ACL to allow subscribing to topic house/#

The setting is

Again,In the example we subscribe to house/# and publish to house/sensor1

The screen shots below show that the messages we publish are not received which is as expected.

However the Mosquitto server console logs a published denied message.

Example 4- Subscribe and Publish to a topic with an Edited ACL.

This time we edit the default ACL to allow anyone to subscribe and publish to topic house/# .

the setting is

Again,In the example we subscribe to house/# and publish to house/sensor1

The screen shots below show that the messages we publish are received, which is as expected.

This time the Mosquitto server console logs the message being sent back to the client.

User Restrictions

User restrictions are triggered when the client provides a username.

If a username is provided by the client then the ACL list is checked for that user.

Username restrictions will override General restrictions.

This means that if the General settings allow access to that topic, if the client provides a username, and that user name doesn’t have an entry in the ACL explicitly giving access to that topic, then they are denied.

Client Settings

Client settings usually use the client ID as part of a pattern match.

You normally see entries like:

This setting will allow a client with client id python1 to publish and subscribe to topic house/python1/#.

Client python1 will not be able to publish and subscribe to topic house/lights/#.

Client Settings and General Settings are additive. This means that if the client settings don’t allow, but the General settings do then, it is allowed.

Client Settings will override User Settings.

This means that if clients settings allow a client to publish/subscribe to a topic then they are allowed regardless of the user settings.

The Following table tries to summarize the General,User and Client Settings

General Settings	User Settings	Client sends Username	Client Settings	Result
Blank	Blank	No	Blank	Denied
Configured	Blank or configured	No	Blank	Depends on General settings
Blank or configured	Blank	Yes	Blank	Denied
Blank or configured	Configured	Yes	Blank	Depends on User settings. General settings don’t apply
Blank or configured	Blank or configured	No	Configured	Combination of General and Client settings
Blank or configured	Blank or configured	Yes	Configured	Client Settings will override user settings and user settings make General settings irrelevant

Examples Settings

Here are some example settings to illustrate the above

Example 1 -User Settings

#General settings

readwrite topic #

#User settings

user Roger
topic readwrite house/#

#Client settings

#Blank

Result

Only user roger can publish and subscribe to topic house/#.

If the client doesn’t send a username then the client can publish and subscribe to all topics -entry readwrite topic # in General settings.

---

Example 2 -User and Client Settings

#General settings

#Blank

#User settings

user Roger
topic readwrite house/P1/#

#Client settings

pattern readwrite house/%C/#

Result

If the client name is Python 1 then that client can publish and subscribe to topic house/Python1/# regardless of the username sent.

However only user roger can publish and subscribe to topic house/P1/#..

Important Notes:

Topic names and usernames are case sensitive. User roger isn’t the same as user Roger.

Topic house/Python1/# isn’t the same as house/python1/#.

Common Questions and Answers

Q- How do I know if my published message has been denied by the broker or just lost?

A- You cannot tell from the client.

Q-Does the user in the ACL user section need to be added to the passwords file?

A- No, not for the ACL to work, but it does if you are also using username and password authentication.

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

You can restrict access to a broker by configuring Access control.

Access control can be applied to users,client ids and topics.

From a client perspective it isn’t easy to know if access control is being applied as restrictions aren’t notified to the client in MQTT v3.1.1.

Mosquitto Configuration Tutorials

• Installing and Testing The Mosquitto Broker
• Quick Guide to The Mosquitto.conf File With Examples
• MQTT TLS Security – Mosquitto Broker Configuration
• Understanding and Configuring Logging on Mosquitto
• Understanding and Configuring Bridging on Mosquitto
• Understanding and Using the Mosquitto Dynamic Security Plugin

Related Tutorials and Resources

• See this Github query thread on acl error messages
• MQTT Security for Beginners