Skip to content

Securing MQTT Devices with OIDC Authentication, HiveMQ, and Microsoft Entra

by Harminder Jandu, Patrick Giezen
7 min read

HiveMQ Enterprise Security Extension (ESE) offers seamless integration with existing enterprise authentication systems, simplifying the management of user credentials and access permissions. In Part 1 of the Safeguarding Your IoT Ecosystem blog series, we learnt how HiveMQ ESE offers seamless integration with enterprise systems such as Microsoft Entra for OAuth 2.0/JWT authentication. In the second part of this series, 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

  1. Go to Microsoft Entra and create an account or go to Entra within your Azure instance. 

  2. Navigate to Applications and select App registrations

Step 1:

Select New registration.

Setting Up Microsoft Entra ID - New RegistrationEnter your Redirect URI that needs to match with the redirect URI on your ESE configuration.

Redirect URI in HiveMQ ESE configurationStep 2: 

Go to Endpoints and note the following:

  • Application (client) ID 

  • Directory (tenant) ID

You will need these for ESE config setup. 

Microsoft Entra set up

Step 3: 

Create a new Client secret under Certificate & Secrets.

Adding certificates and secrets on Microsoft Entra

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.

Microsoft EntraStep 5:

Navigate to Enterprise applications, then to Users and groups. Click the Edit assignment tab.

Create a new App role for a superuser and for a viewer on Microsoft EntraStep 6: 

Go to Select a role.

Setting up Microsoft Entra

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-endpoint 

  • Client ID 

  • Secret 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.

  • Harminder Jandu on LinkedIn

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.

  • Patrick Giezen on LinkedIn
  • Contact Patrick Giezen via e-mail
HiveMQ logo
Review HiveMQ on G2