Skip to content

Authorization - MQTT Security Fundamentals

by HiveMQ Team
13 min read

Welcome to our MQTT Security Fundamentals series. In this blog, we will focus on a new topic: authorization with MQTT. Authorization builds nicely on our previous discussions about authentication. If you haven’t read the last two blogs on authentication using username and password and advanced authentication, definitely check them out before you continue with this blog.

What is Authorization?

Authorization specifies access rights to a resource. Authorization includes the definition and enforcement of the policies that control who can have or do something with a certain resource. The following terms are essential parts of authorization:

  • Subject or user who wants to access a resource.

  • Resource, object, or service that need to be protected from unauthorized access.

  • Policy that specifies if a subject or user has access to a resource.

Real-world Example

Let’s continue with the travel example from our previous post on MQTT authentication. In that example, we saw that a passport can be used to authenticate the identity of a person when they board a flight. After the identity of the person is confirmed, their boarding pass is used to authorize access to a particular plane. After the flight is booked, your personal information, flight date, departure time, and destination serve as authorization for the flight.

Authentication & Authorization: Two best friends!

As we can see in our real-world example, authentication and authorization are important security concepts that go hand in hand. There is little value in authorizing a user or subject if you haven’t authenticated their identity beforehand. Authorization is important for restricting entry and allowing only eligible persons, clients, or subjects access to certain resources, data, or things. If you’re not focused on security, you might not notice that these concepts are everywhere. If you step back and look closely, you can identify these concepts easily. For example, log in to your operating system and access files, log into a web application, or enter a corporate office with a key card.

How to Specify Authorization Policies

Different types of authorization are commonly used. Here’s a quick overview. If you want to know more, there are plenty of resources available that explain each of these authorization types in detail.

Short Name Description Example
ACL Access Control ListAn ACL associates a resource with a list of permissions. A permission includes who can access the resource (for example, a file) and which operations are allowed (for example, read, write, execute).Unix file permissions
RBAC Role Based Access ControlRBAC always associates the permissions to a certain resource with a role. A role is a additional abstraction between the user and the resource. It is easier to associate users with roles than to maintain permission over all users.Active Directory, SELinux, PostgreSQL

Authorization in MQTT

Let’s have a look at MQTT.

An MQTT client can basically do two things after it has connected to a broker: publish messages and subscribe to topics. Let’s translate this to the previously stated definitions:

  • An MQTT client is the subject.The MQTT client wants authorization to do something.

  • Topics are the main resources or objects that are available to a client.

  • Other objects can be: Store Last Will and Testament or request a persistent session.

  • The main resources that need protection are the ability to publish messages or subscribe to messages.

Without proper authorization, each authenticated client can publish and subscribe to all available topics. This can be desirable in a closed system. However, for most use cases, fine-grained restrictions make a lot of sense and should be enforced. The official MQTT 3.1.1 specification states the following:

“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”

To restrict a client to publishing or subscribing to only authorized topics, topic permissions must be implemented on the broker side. These permissions need to be configurable and adjustable during the run time of the broker. Here is a possible topic permission:

  • 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 allows the broker to specify authorization policies for clients and limit their ability to subscribe and publish messages. For example, give a client the permission to subscribe only to a single topic and use only a certain quality of service level.


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


When a client publishes to a topic without the correct permission, the broker has two options:

  • The broker can disconnect the client because publishing to a restricted topic is not permitted.

  • The broker can acknowledge the publish to the client in a normal fashion. In QoS 1 or 2, with PUBACK or PUBREL packets, 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 an unauthorized publish other than disconnecting the client. Notification options may improve in upcoming MQTT versions.


When a client subscribes to a topic, the broker needs to acknowledge each subscription with a return code. Return codes include 4 different codes that acknowledge topics with a granted QoS and error codes. If the client does not have the right to subscribe a specific topic, the broker can notify the client that the subscription was denied.

Best Practices for Authorization in MQTT

A common best practice is to include the client ID of the publishing client in the permission. The client is restricted to publish only to topics that are prefixed with its own client ID. For example, client123/temperature or client123/car/speed. The same solution can be used for subscribing. This is a good pattern for topics that are only concerned with one client. Of course, this is often not the only permission needed. Frequently, a client has permissions to subscribe to more general topics. For example, clients/status or clients/command. Use of this pattern depends highly on your individual use case.

MQTT Broker Implementation

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

The below implementation applies to only HiveMQ 3.0. If you are using HiveMQ 4.0 or higher, visit our documentation on Authentication.

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. Naturally, these permissions can be cached (which means that the flow of messages is not affected).

The OnAuthorizationCallback allows the getPermissionsForClient method to be implemented (as shown in the following example). The method is called from the HiveMQ core and hands over a ClientData object that contains all available information on the client requesting the permission. This data can be used to determine the correct permissions (the following example uses the client ID data). HiveMQ expects the plugin to return a list of topic permissions that the client is allowed to use. The exact matching of the permissions and the current topic is done by HiveMQ.

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

    return mqttTopicPermissions;

This example shows how a client can publish and subscribe only to topics that start with its client ID. All other subscriptions or published messages are denied.

Another example is the Stormpath Plugin. This plugin uses the Stormpath API for authentication and authorization.

We hope you are enjoying our MQTT Security Fundamentals. Subscribe to our newsletter or RSS feed to keep updated of our content. If you have ideas about the information we should add, please use the comments to tell us. We are always open to questions and suggestions.

HiveMQ Team

The HiveMQ team loves writing about MQTT, Sparkplug, Industrial IoT, protocols, how to deploy our platform, and more. We focus on industries ranging from energy, to transportation and logistics, to automotive manufacturing. Our experts are here to help, contact us with any questions.

Related content:

HiveMQ logo
Review HiveMQ on G2