This article originally appeared on the HiveMQ blog. A huge ‘Thank You’ to their team for the plugin and writeup!

HiveMQ Logo

Authentication and authorization are key aspects for every Internet of Things application. When using MQTT, topic permissions are especially important for most public-facing MQTT brokers. Learn how you can use Stormpath with HiveMQ to set up fine grained security for your MQTT service in minutes.

For the impatient: You can download the Stormpath HiveMQ plugin here.

Challenges of Authentication and Authorization in the Internet of Things

Security is a big concern in the age of the Internet of Things. More than ever, personal and sensor information are transferred over the Internet. For example, data about the conditions and status in our home or company, as well as chat messages or status updates of our current activity and location. In the wrong hands this kind of information can be exploited to damage people and companies.

Often the problem with architecting for security is not awareness of the challenges and risks, but lies in the implementation of the necessary security measures. Most Developers are focused on building applications and not everybody has deep know-how in implementing secure authentication or authorization.

Stormpath to the Rescue

Stormpath is a User Management API for developers, built for user authentication and authorization in traditional web applications. It can also be used perfectly for Internet of Things applications – no more reinventing the wheel with a manual implementation of user and permission models for your applications. Stormpath saves all users credential in a centralized, cloud-based directory, and users can be assigned to different groups and granted fine-grained permissions.

Stormpath provides a role based access control by adding users to one or more groups, which is ideal for permissions inside one application. In order to create user accounts, groups and so on Stormpath provides a REST API, SDKs for Java, PHP, Ruby, Python and an easy to use WebUI. More details can be found in the extensive documentation on their website. Another important aspect for IoT applications is the constant availability of all services. The basic version of Stormpath is free and is ideal for prototyping and small applications. It does not provide any guarantees on uptime, though. For enterprise and production usage Stormpath provides short response time on support requests and 100% availability SLAs.

Use Stormpath for MQTT Authentication and Authorization

So how can we leverage Stormpath to create authentication and authorization for MQTT clients?

First of all, let’s have a look at its architecture.


The figure shows us that Stormpath is organized in different tenants and each tenant has a cloud directory, which can be accessed by a REST API. The API can be used by a variety of applications. Inside the cloud directory are accounts, groups, directories and applications.

We can use the Stormpath structure to associate MQTT clients with accounts. That means whenever a new MQTT client connects, we query Stormpath if an account with the MQTT username and password exists and only then let the client connect. This handles the authentication scenario pretty straightforwardly.

HiveMQ Stormpath Schema

The authorization behavior can be achieved using Stormpath groups. If an authenticated client wants to publish a message, the MQTT broker can lookup all groups of that particular account, which represent the topics (including wildcards) the client is allowed to use. For example a client wants to publish to home/livingroom/temperature the MQTT broker gets all the groups from Stormpath: home/livingroom/# and checks if the topic matches the permissions of the client. If the clients would only be in the group home/livingroom/light, the permission to publish would be denied.

This described behavior is implemented in our Stormpath Plugin for HiveMQ, which retrieves the necessary authentication and authorization permission from Stormpath.

Using the Stormpath HiveMQ Plugin

Now it is time to get the Stormpath HiveMQ in place and see how simple it is to authenticate a client from Stormpath.

General Setup

  • Download HiveMQ and the Stormpath Plugin
  • Unzip both and copy the plugin jar into the HiveMQ plugins folder
  • Create a Stormpath Free Account and verify it via email.
  • Login to your new account and create an API key
  • Copy the information from the API key download into the and set the name of how your application should be named in Stormpath.

  • Start HiveMQ with the Stormpath Plugin and connect with a client

  • The connection will be denied, but the plugin creates the necessary Stormpath application and directories



  • Go to Stormpath and create a new account inside of Stormpath

Please choose the directory, which represents your application name that you set in the property file. The username and password must match the credentials provided by the MQTT client (directory, username, firstname, lastname, email and password are mandatory fields)


  • Try to connect with the specified username and password
  • Client is successfully authenticated 🙂

Hint: At this point the client can’t publish or subscribe to any topic, because the permission defaults to deny.


  • Go to Stormpath and click on Directories
  • Choose the Directory with the name of your application
  • Click on the Groups tab
  • Create group with the name: #
  • Mouse over the action cell in the group overview and choose „Members“
  • Click Assign Accounts
  • Select the previously created account Stormpath-add-johndoe-to-wildcard
  • Try to publish a MQTT message to a topic
  • Message should be published

More than a proof of concept

While configuring permissions via the Stormpath Web UI is easy and sufficient for a proof of concept, it may be tedious for real applications to maintain all permissions by hand. And here is where Stormpath really excels in conjunction with HiveMQ: You can update all permissions and accounts via the REST API and all changes are automatically applied to your HiveMQ instance. You could integrate Stormpath easily with your user-registration backend and automatically add the correct topic permissions to HiveMQ. Imagine you had a HiveMQ cluster up and running – you can automatically update all the permissions without doing anything.


As we have seen, the setup of Stormpath and HiveMQ is done in minutes and now you have a directory for authentication and authorization in place that can be easily modified by the Web UI and programmatically – while HiveMQ is running!