MQTT Security Fundamentals: Authorization


Hello and welcome to another MQTT Monday and the next post of the MQTT Security Fundamentals. This week we will devote our focus to a new topic and look into authorization with MQTT. This fits ideally after we discussed authentication previously. If you haven’t read the last two posts about authentication(part 1 and part 2), you should definitely do so, before you continue reading this post.

What is Authorization?

Authorization is the function of specifying access rights to a certain resource. This includes the definition and enforcement of policies, which specify who can access a certain resource. Therefore the following terms are essential:

  • subject or user: wants to access a resource
  • resource, object or service: should be protected from unauthorized access
  • policy: specifies if a subject has access to a resource

Real world illustration

Let’s pick up the traveling example of the authentication blog post and carry it on. We have seen that a passport can be used for authenticating a person’s identity when boarding a flight. So after the identity is confirmed, the booking confirmation or the boarding pass is used for authorizing/granting access to get on a particular plane. So after booking the flight, the information about your person and the exact flight date, time and destination serves as authorization for the flight.

Authentication & Authorization: Two best friends!

As we have already seen in the real world example, authentication and authorization are two very important security concepts that go hand in hand. There is not much value in the authorization of a user or subject without having it authenticated beforehand and thereby confirmed its identity. Authorization is important for restricting access and allowing only eligible persons, clients or subjects to access certain resources, data or things. If you don’t have a specific focus on security, you might not notice that these concepts are everywhere, but if you step back and look closely, you can identify them very easily: login to your operating system and access files, login to a web application and having certain rights or access the company building with a staff badge.

How to specify Authorization Policies

There are different types of authorization that are most commonly used, here is a quick overview. If you want to know more, there are tons of resources on the web which explain each of these types in detail.

Short Name Description Example
ACL Access Control List An ACL associates a resource with a list of permissions. A permission includes who can access the resource (e.g. a file) and which operations (e.g. read, write, execute) are allowed. Unix file permissions
RBAC Role Based Access Control RBAC is always associating the permissions to a certain resource with a role. A role is a additional abstraction between the user and the resource. It makes it more easy to associate users with roles as to maintain permission over all users. Active Directory, SELinux, PostgreSQL

Authorization in MQTT

Let’s have a look at MQTT.

A MQTT client can basically do two things after it has connected to a broker, it can publish messages and it can subscribe to topics. So translating this to the previously stated definitions:

  • A MQTT client is the subject, it wants authorization to do something
  • The main resources or objects available to a client are the topics
  • Other objects would be: Store Last Will and Testament or have a persistent session
  • The main resources which need protection are the ability to publish or subscribe

Without proper authorization each authenticated client can publish and subscribe to all kinds of topics. This could be desirable in a closed system. For most use cases, fine-grained restrictions make a lot of sense and should be used. The official MQTT 3.1.1 specification states the following on this matter:

“MQTT solutions are often deployed in hostile communication environments. In such cases, implementations will often need to provide mechanisms for: […] Authorization of access to Server resources”

In order to restrict a client to publish or subscribe only to topics it is authorized to, it is necessary to implement topic permissions on the broker side. These permissions need to be configurable and adjustable during the runtime of the broker. A topic permission could for example look like the following:

  • Allowed topic (exact topic or wild card topic)
  • Allowed operation (publish, subscribe, both)
  • Allowed quality of service level (0, 1, 2, all)

This kind of topic permission would allow the broker to specify authorization policies for clients and to limit their ability to subscribe and publish messages. An example would be giving a client the permission to subscribe only to a single topic and use only a certain quality of service level.


After having defined authorization policies, a very common question is how to notify a client that it doesn’t have the permission to publish or subscribe on a certain topic.


When publishing to a topic the client has no permission for, the broker has two options:

  • It can disconnect the client, because publishing to a restricted topic is disallowed.
  • It can acknowledge the publish to the client in a normal fashion – in case of QoS 1 or 2 with PUBACK or PUBREL – and decide not to send the published message to the subscribers.

The current MQTT 3.1.1 specification does not define a broker-independent way to inform clients about the unauthorized publish, except disconnecting the client, which may be improved in upcoming MQTT versions.


In the case of subscribing to a topic, the broker needs to acknowledge each subscription with a return code. There are 4 different codes for acknowledging each topic with a granted QoS or sending an error code. So if the client has no right to subscribe a specific topic, the broker can notify the client that the subscription was denied.

Best practices

A commonly used best practice is to include the client id of the publishing client in the permission. So the client is restricted to only publishing to topics, where it’s client id is upfront. An example would be client123/temperature or client123/#. The same can be used for subscribing. This is a good pattern for topics that are only concern one client. Of course this are often not the only permission. Additionally a client commonly has permissions to subscribe to more general topics like: clients/status or clients/command. This depends highly on the use case and should only be a suggestion.

Broker implementation

Finally let’s have a look how a custom authorization can be implemented with the HiveMQ MQTT broker.

The open source plugin system of HiveMQ makes it easy to specify topic permissions for each client. Whenever a client wants to publish or subscribe, HiveMQ asks the plugin for the permissions of the client. Of course these permissions can be cached, so it doesn’t slow down the flow of the messages.

The OnAuthorizationCallback allows to implement the method getPermissionsForClient, which is shown exemplarily below. The method is called from within the HiveMQ core and hands over an object of ClientData, which contains all information available for the client requesting the permission. This can be used to determine the correct permissions, like using the client id as in the example. HiveMQ expects the plugin to return a list of topic permissions the client is allowed to use. The exact matching of the permissions and the current topic is done by HiveMQ itself.

@Cached(timeToLive = 5, timeUnit = TimeUnit.MINUTES)
public List getPermissionsForClient(ClientData clientData) {
    List mqttTopicPermissions = new ArrayList();
             new MqttTopicPermission(
                    clientData.getClientId() + “/#”,            // Topic
                    MqttTopicPermission.ALLOWED_QOS.ALL,        // QoS
                    MqttTopicPermission.ALLOWED_ACTIVITY.ALL)); // Publish, Subscribe, All

    return mqttTopicPermissions;

The example shows how a client can only publish and subscribe to topics, which start with its client id. All other subscriptions or published messages are denied.
The complete example can be found on the HiveMQ GitHub account.

Another example is the Stormpath Plugin, which uses the Strompath API for authentication and authorization.

We hope you enjoyed part four of the MQTT Security Fundamentals, if you want to get notified as soon as we publish the next post, you can subscribe to our newsletter or RSS feed. You think we have missed some important information? Please tell us, we are always open to questions and suggestions.

Leave a Reply

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