Role Based Access Control to Secure an MQTT Broker

by Magi Erber

Sep 10, 2019 11 min read

Your business-critical IoT deployments must be protected from abuse of any kind. As always, there are many ways to do this.

For example, using TLS to secure communication between all of your system components is a good starting point. Requiring all connecting IoT devices to authenticate and authorize against an MQTT broker such as HiveMQ (as explained in this blog post) will give you a further level of security.

MQTT brokers that have a graphical user interface (GUI) face an additional problem. Frequently, legal concerns or corporate compliance policies require that access to a system is restricted. These restrictions include the GUI. Naturally, since HiveMQ is an MQTT broker with an excellent GUI, the HiveMQ Control Center also supports you in securing this part of your deployment.

Access Control for the HiveMQ Control Center

The Enterprise Edition of HiveMQ 4.2 adds a new feature that supports role based access control (RBAC) for the HiveMQ Control Center. RBAC allows you to restrict user permissions and precisely control which users can view, access, and modify data. You can use RBAC to create fine-grained access management for your HiveMQ system. Our HiveMQ Enterprise Security Extension (ESE) also gives you the ability to use permissions that are stored in external data sources such as SQL databases. With the HiveMQ ESE, adding and removing HiveMQ control-center users or changing the access rights of these users is quickly and easily possible straight out-of-the-box.

In this blogpost, we’ll set up a local HiveMQ broker (with HiveMQ ESE) that authenticates and authorizes HiveMQ control-center users with the help of a Postgres database.

Setup HiveMQ with HiveMQ Enterprise Security Extension (ESE)

Download HiveMQ from our website and unzip the file.
Download HiveMQ Enterprise Security Extension from our HiveMQ Marketplace and unzip the file.
Move the unzipped hivemq-enterprise-security-extension folder into the extensions subfolder of the unzipped hivemq folder.
Download the latest Postgres JDBC driver jar file and move it into the drivers/jdbc subfolder of your ESE.

Set Up Postgres Database with Docker

Open the command line and pull the official docker image for Postgres:
Bind mount the current working directory into the container. This is necessary to be able to share files between the host system and the docker container:
Start the docker container:
Create a new database to store the access information of the HiveMQ control-center users:
Go to the sql/v1.2 subfolder in your ESE folder. To set up the database, we will use the predefined SQL scripts that are located there.
Adjust the path to the location of your HiveMQ setup.
Copy the predefined postgresql_create.sql and default_permissions_insert.sql files, that are located in this folder, to the docker container:
To create the database tables, execute the sql statements from the postgresql_create.sql file:
To add the default permissions as database table entries, execute the sql statements from the default_permissions_insert.sql file:

docker exec -u postgres hivemq-ese-database psql hivemq_ese_db postgres -f docker-entrypoint-initdb.d/default_permissions_insert.sql

Create HiveMQ Control Center Users

Now that our database is set up, we can insert data according to our individual needs. Our database contains many database tables. For now, we will concentrate on the HiveMQ Control Center database tables. These tables are easy to recognize because they start with cc_<table-name>.

In this post, we work with the following two HiveMQ Control Center user roles and permissions:

Superuser Role:
Username: superadmin
Password: password
Role: super_admin
Permission: Allowed to see and do everything in the HiveMQ Control Center.
Dashboard Viewer:
Username: dashboardviewer
Password: password
Role: dashboard_viewer
Permission: Allowed to see only the Dashboard page of the HiveMQ Control Center.

The ESE includes a helper tool that allows us to create properly-encrypted passwords and can provide us with the insert statements we need for our database. To add more than these two users, see our documentation on how to create insert statements for HiveMQ control-center users.

To configure the HiveMQ Enterprise Security Extension accordingly, we need to do the following:

Download the ese-example-control-center-users-and-roles.sql file. This file contains example users, roles, and role permissions.

insert into cc_roles (name, description)
values ('super_admin', 'has the HIVEMQ_SUPER_ADMIN permission'),
       ('dashboard_viewer', 'can only see the dashboard');

insert into cc_role_permissions (role, permission)
select cc_roles.id, cc_permissions.id
from cc_roles,
     cc_permissions
where cc_roles.name = 'super_admin'
  AND cc_permissions.permission_string = 'HIVEMQ_SUPER_ADMIN'
;

insert into cc_users (username, password, password_iterations, password_salt, algorithm)
values ('dashboardviewer', 'DR9yesp2mEBmNalk5uTj5byyOf5Cs/cz4zzbN8T/61UTwlMHa9isHqGmwiIMmcrcsnSs1YCct5X+ql9OmPnQdw==', 100, '6iWJ0lp4w2e/D0YyAyXw9w==', 'SHA512'),
       ('superadmin', 'TmjEM4X1i5+PiHBnQrjMHrLRw139o6FwZYrQrLXuzbPuuMOZ4qOl8pvkY5knxeahPqVAgC/fruVK/ZNa4TutvQ==', 100, 'lhtADCtQjVil1HDHwfnJ3Q==', 'SHA512');

INSERT INTO cc_user_roles (user_id, role_id)
select cc_users.id, cc_roles.id
from cc_users,
     cc_roles
where cc_users.username = 'dashboardviewer'
  AND cc_roles.name = 'dashboard_viewer'
;

INSERT INTO cc_user_roles (user_id, role_id)
select cc_users.id, cc_roles.id
from cc_users,
     cc_roles
where cc_users.username = 'superadmin'
  AND cc_roles.name = 'super_admin'
;

Copy the file to your docker container:

docker cp <path_to_downloaded>/ese-example-control-center-users-and-roles.sql hivemq-ese-database:/docker-entrypoint-initdb.d/ese-example-control-center-users-and-roles.sql

Adjust the path to your downloaded file accordingly.
Execute the sql statements from the ese-example-control-center-users-and-roles.sql file to add users, roles, and role permissions:

Connecting the dots

Now that we have prepared HiveMQ and set up our database, it’s time to connect the systems.

Connect the ESE to the Postgres Database

Configure your HiveMQ Enterprise Security Extension with the enterprise-security-extension.xml file that is located in the ESE extension folder.

<?xml version="1.0" encoding="UTF-8" ?>
<enterprise-security-extension
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="enterprise-security-extension.xsd"
        version="1">
    <realms>
        <!-- a postgresql db-->
        <sql-realm>
            <name>postgres-backend</name>
            <enabled>true</enabled>
            <configuration>
                <db-type>POSTGRES</db-type>
                <db-name>hivemq-ese-db</db-name>
                <db-host>localhost</db-host>
                <db-port>5432</db-port>
                <db-username>postgres</db-username>
                <db-password>postgres</db-password>
            </configuration>
        </sql-realm>
    </realms>
    <pipelines>
        <!-- secure access to the control center -->
        <control-center-pipeline>
            <!-- authenticate over a sql db -->
            <sql-authentication-manager>
                <realm>postgres-backend</realm>
            </sql-authentication-manager>
            <!-- authorize over a sql db -->
            <sql-authorization-manager>
                <realm>postgres-backend</realm>
                <use-authorization-key>true</use-authorization-key>
                <use-authorization-role-key>true</use-authorization-role-key>
            </sql-authorization-manager>
        </control-center-pipeline>
    </pipelines>
</enterprise-security-extension>

You can copy this file and adjust lines 13, 14, 16, and 17 accordingly.

Start HiveMQ

Start your HiveMQ via the console:

cd <hivemq_install_directory>/bin
chmod 755 run.sh
./run.sh

Congratulations!

We have successfully created a running HiveMQ with HiveMQ ESE that can authenticate and authorize HiveMQ Control Center users via a PostgreSQL database. Now let’s log in as each of our HiveMQ control-center users and see if everything is working as expected:

Open the HiveMQ Control Center in your favourite browser via this URL: http://localhost:8080/.
Log in as Superuser with the username: superadmin and the password: supersecurepassword.
You should be able to log in to the Control Center and see every page.
Log in as Dashboard Viewer with the username: dashboardviewer and the password: password.
You should be able to log in to the Control Center and only see the Dashboard. Even if you try to access another page via the URL, you should not be able to see something else.
Log in as the default user with the username: admin and the password: hivemq.
You should not be able to log in to your HiveMQ Control Center.

Conclusion and Resource List

Authentication and authorization are crucial puzzle pieces for IoT security. This blog post shows how to use HivMQ, the HiveMQ Enterprise Security Extension, and a Postgres database to easily set up access control for your HiveMQ Control Center users. Adding access control via a centralized SQL database is a good starting point to fulfill legal requirements or corporate compliance policies. Contact Us for guidance on additional aspects of IoT security tailored to your specific needs.

Finally, here’s a list of the resources you need to secure your HiveMQ deployment with HiveMQ ESE and a Postgres SQL database:

Magi Erber

Magi Erber is Senior Product Manager at HiveMQ. She loves creating software that delights customers and helps them realizing innovative IoT solutions.