Role Based Access Control to Secure an MQTT Broker
Written by Margaretha Erber
Category: HiveMQ IoT Security Control Center Security Extension
Published: September 10, 2019
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-extensionfolder into the
extensionssubfolder of the unzipped hivemq folder.
Download the latest Postgres JDBC driver jar file and move it into the
drivers/jdbcsubfolder of your ESE.
Set Up Postgres Database with Docker
Open the command line and pull the official docker image for Postgres:
docker pull 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:
docker run --name hivemq-ese-database -v `pwd`:/docker-entrypoint-initdb.d -p 5432:5432 postgres -d
Start the docker container:
docker start hivemq-ese-database
Create a new database to store the access information of the HiveMQ control-center users:
docker exec -it hivemq-ese-database psql -U postgres -c "create database hivemq_ese_db"
Go to the
sql/v1.2subfolder 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
default_permissions_insert.sqlfiles, that are located in this folder, to the docker container:
docker cp ./postgresql_create.sql hivemq-ese-database:/docker-entrypoint-initdb.d/postgresql_create.sql docker cp ./insert/default_permissions_insert.sql hivemq-ese-database:/docker-entrypoint-initdb.d/default_permissions_insert.sql
To create the database tables, execute the sql statements from the
docker exec -u postgres hivemq-ese-database psql hivemq_ese_db postgres -f docker-entrypoint-initdb.d/postgresql_create.sql
To add the default permissions as database table entries, execute the sql statements from the
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
In this post, we work with the following two HiveMQ Control Center user roles and permissions:
Permission: Allowed to see and do everything in the HiveMQ Control Center.
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
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:Adjust the path to your downloaded file accordingly.
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
Execute the sql statements from the
ese-example-control-center-users-and-roles.sqlfile to add users, roles, and role permissions:
docker exec -u postgres hivemq-ese-database psql hivemq_ese_db postgres -f docker-entrypoint-initdb.d/ese-example-control-center-users-and-roles.sql
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.
You can copy this file and adjust lines 13, 14, 16, and 17 accordingly.
Start your HiveMQ via the console:
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:
Log in as Superuser with the username:
superadminand the password:
You should be able to log in to the Control Center and see every page.
Log in as Dashboard Viewer with the username:
dashboardviewerand the 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:
adminand the password:
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:
- HiveMQ Enterprise Security Extension
- Postgres initial table script
- Postgres Default HiveMQ Control Center permissions
- Example HiveMQ Control Center users, roles and role-permissions