Securing MQTT Devices with OIDC Authentication, HiveMQ, and Microsoft Entra
HiveMQ Enterprise Security Extension (ESE) offers seamless integration with existing enterprise authentication systems, simplifying the management of user credentials and access permissions. In this second part of the blog series, Safeguarding Your IoT Ecosystem, we provide steps to set up Single Sign On (SSO) for users to access the HiveMQ Control Center portal with Microsoft Entra ID.
The setup entails leveraging the OIDC authentication using HiveMQ Enterprise Security Extension (ESE) and Microsoft Entra as the IDP. For further information on OIDC flow being used from Microsoft Entra, you can reference details here.
Prerequisites for Setting up HiveMQ ESE and Microsoft Entra ID
Before getting started, there are a few items that you will need in order to set up a test. The following are required:
A Microsoft Entra ID account or access to Entra ID in your Azure instance
A running HiveMQ Broker to set up, which you can download for free. Note that the HiveMQ trial comes with ESE for free (remember that it runs for 5 hrs, but you can restart HiveMQ to re-run it).
The steps outlined further in this blog post will guide you through setting up your Microsoft Entra ID environment with an Application Registration. The information within the Application Registration will be required as input for the HiveMQ ESE configuration. For the setup of HiveMQ ESE configuration, the details on what specific entries are required on the corresponding config.xml will be explained.
Setting Up Microsoft Entra ID
Go to Microsoft Entra and create an account or go to Entra within your Azure instance.
Navigate to Applications and select App registrations
Step 1:
Select New registration.
Enter your Redirect URI that needs to match with the redirect URI on your ESE configuration.
Step 2:
Go to Endpoints and note the following:
Application (client) ID
Directory (tenant) ID
You will need these for ESE config setup.
Step 3:
Create a new Client secret under Certificate & Secrets.
Note: Upon creation of the client secret, save the value as it will then be partially masked after you leave this window.
Step 4:
Create a new App role for a superuser and for a viewer.
Step 5:
Navigate to Enterprise applications, then to Users and groups. Click the Edit assignment tab.
Step 6:
Go to Select a role.
Setting Up the HiveMQ ESE Configuration
Now with the Entra ID setup in place, the next step is to generate the corresponding config.xml for ESE to be applied on the HiveMQ Broker node(s).
As we are using OIDC authentication from the HiveMQ Control Center the ESE configuration setup will be with an oidc-realm that will specify the Entra ID tenant ID setup in the previous steps. Below is a snippet of the ESE config.xml, and enter your appropriate settings for:
jwks-endpointClient IDSecret Password
Note: You can also set environment variables for the Client ID and Secret Password on HiveMQ node and enter those into the configuration, thereby ensuring no exposure of any Client ID or Secret Password. For details, see the documentation here.
<enterprise-security-extension
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="enterprise-security-extension.xsd"
version="1">
<realms>
<oidc-realm>
<name>my-oidc-realm</name>
<enabled>true</enabled>
<configuration>
<issuer>https://login.microsoftonline.com/[Tenant ID]/v2.0</issuer>
<client-id>[client ID]</client-id>
<client-authentication>
<client-secret-basic>[secret]</client-secret-basic>
</client-authentication>
</configuration>
</oidc-realm>
<file-realm>
<name>my-file-realm</name>
<enabled>true</enabled>
<configuration>
<file-path>conf/ese-file-realm.xml</file-path>
</configuration>
</file-realm>
</realms>Below is a further snippet of the ESE configuration that has the oidc-authentication manager sourcing the oidc-realm setup above and file-based authorization.
<pipelines>
<!-- secure access to the control center -->
<control-center-pipeline>
<oidc-authentication-manager>
<realm>my-oidc-realm</realm>
<redirect-uri>http://localhost:8080/redirect</redirect-uri>
<scopes>
<scope>profile</scope>
<scope>openid</scope>
<scope>User.Read</scope>
</scopes>
<authorization-key-claim>preferred_username</authorization-key-claim>
<authorization-role-key-claim>roles</authorization-role-key-claim>
</oidc-authentication-manager>
<file-authorization-manager>
<realm>my-file-realm</realm>
<use-authorization-key>false</use-authorization-key>
</file-authorization-manager>
</control-center-pipeline>
</pipelines>
</enterprise-security-extension>HiveMQ ESE File Realm Setup
Create a file ese-file-realm.xml and save it in your /hivemq/extensions/hivemq-enterprise-security-extension/conf directory.
To view client list information, the user must also have the following permission:
HIVEMQ_VIEW_DATA_CLIENT_ID
Below is a sample of the file realm:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ese-file-realm xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ese-file-realm.xsd">
<control-center>
<roles>
<role>
<id>superuser</id>
<permissions>
<permission>HIVEMQ_SUPER_ADMIN</permission>
</permissions>
</role>
<role>
<id>viewer</id>
<permissions>
<permission>HIVEMQ_VIEW_PAGE_CLIENT_LIST</permission>
<permission>HIVEMQ_VIEW_PAGE_CLIENT_DETAIL</permission>
<permission>HIVEMQ_VIEW_DATA_CLIENT_ID</permission>
</permissions>
</permissions>
</role>
</roles>
</control-center>
</ese-file-realm>Test Setup
With the ESE config.xml in place, start HiveMQ. If needed, remove the DISABLED file from the ESE path (extensions/hivemq-enterprise-security-extension/).
Navigate to your Control Center URL. If running locally, it will be http://localhost:8080.
Enter in username and passwordof the superuser.
Verify you have successfully logged into the Control Center.
Conclusion
In summary, through the integration of HiveMQ ESE with Microsoft Entra, organizations can effortlessly implement Single Sign On (SSO) for the HiveMQ Control Center, enhancing security with robust OIDC authentication and simplifying access management for IoT deployments.
Harminder Jandu
Harminder Jandu is a Solution Engineer at HiveMQ. Harminder helps enterprises with their IoT digital transformation activities using HiveMQ Enterprise MQTT platform. His background is in IoT and Communications across multiple specialities, which includes solution engineering, customer success, and consulting.
Patrick Giezen
Patrick is a Solutions Engineer at HiveMQ. With several years of experience in IoT solutions, Patrick helps enterprises from industry verticals such as automotive/connected cars, industrial manufacturing, healthcare, fleet/asset tracking, etc. adopt the HiveMQ MQTT Platform to transform their business.
