Skip to content

Authenticating MQTT Devices with HiveMQ and Microsoft Entra

by Harminder Jandu
10 min read

In Enterprise IoT deployments, ensuring robust security measures is paramount. HiveMQ is a leading MQTT platform that offers advanced security features tailored to the needs of large-scale IoT deployments.

HiveMQ’s exemplary solution for implementing security is with the HiveMQ Enterprise Security Extension (ESE). The HiveMQ ESE provides comprehensive security functionalities, including authentication, authorization, and encryption. It enables organizations to enforce fine-grained access control policies, ensuring that only authorized devices and users can access IoT resources.

HiveMQ ESE offers seamless integration with existing enterprise authentication systems, simplifying the management of user credentials and access permissions. In Part 1 of this two-part blog series, we look at the HiveMQ ESE setup for MQTT client authentication using Microsoft Entra ID. 

The setup entails leveraging the OAuth 2.0/JSON Web Token (JWT) authentication setup using HiveMQ ESE and Microsoft Entra as the IDP/JWT provider. For further information on Oauth2 flow being used from Microsoft Entra, you can reference details here.

Prerequisites to Set 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 in order to set up, which you can download for free. Note that the HiveMQ trial comes with ESE for free (remember 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 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.  

Microsoft Entra ID Setup

  1. Go to Microsoft Entra and create an account https://entra.microsoft.com/ or go to Entra within your Azure instance. 

  2. Navigate to Applications and select App registrations.

Step 1:

Select the New registration tab.

Setting Up HiveMQ ESE and Microsoft Entra IDIn the Register an application page that opens, fill out the Name field and click Register.

Registering a new application on Microsoft Entra

Step 2:

On the App registrations page, note down the following as shown below:

  • Application (client) ID 

  • Directory (tenant) ID

Copying Application client ID and Directory Tenant ID on Microsoft EntraYou will need these for ESE config setup. 

Step 3:

Create a New client secret under Certificates & secrets.

Microsoft Entra Quick Start

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 the app role. 

  1. Navigate to the App roles and create the necessary roles.  

  2. Enter Display name and Value.

  3. For Allowed member types - Both.

  4. Value - this entry will be your scope, so keep note of it for ESE authorization configuration.  

HiveMQ ESE

Step 5:

Expose Application ID URI.

Click the Add beside Application ID URI box to generate. 

You will need this API in order to get the Scope as part of the client token request. 

HiveMQ ESE - exposing an API

Step 6:

Select the requested API permissions

  • Navigate to API permissions.

  • Click on APIs my organization uses and search for your exposed API just created. 

  • Select the Permissions for your app role. 

Request API permissions

In the API permissions window, click on Grant admin consent for Default Directory.

HiveMQ ESE API Permissions

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 Oauth 2.0/JWT authentication, the ESE configuration setup will be with a jwt-realm , which specifies the Entra ID and 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.

<?xml version="1.0" encoding="UTF-8" ?>
<enterprise-security-extension
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="config.xsd"
       version="1">
   <realms>
       <!-- a oauth provider-->
       <jwt-realm>
           <name>jwt-provider</name>
           <enabled>true</enabled>
           <configuration>
               <jwks-endpoint>https://login.microsoftonline.com/[TENANTID]/discovery/v2.0/keys</jwks-endpoint>
               <simple-auth>
                   <username>CLIENT ID</username>
                   <password>SECRET PASSWORD</password>
               </simple-auth>
           </configuration>
       </jwt-realm>

Authorization Preprocessing - Allow All 

Below is a snippet of the ESE configuration that has the jwt-authentication manager sourcing the jwt-realm setup above and authorization to enable all for testing purposes. You can further adjust the authorization to set up either file-based or SQL DB authorization realm. 

<pipelines>
   <!-- secure access to the mqtt broker -->
   <listener-pipeline listener="ALL">
       <!-- authenticate with provided jwts -->
       <jwt-authentication-manager>
           <realm>jwt-provider</realm>
           <jwt-validation>
               <exp-grace disconnect-after-expiry="true">300</exp-grace>
           </jwt-validation>
       </jwt-authentication-manager>
       <authorization-preprocessors>
           <jwt-preprocessor prefix="{{" postfix="}}">
               <source>authentication-byte-secret</source>
               <jwt-extractions>
                   <jwt-extraction>
                       <jwt-claim>roles</jwt-claim>  
                       <ese-variable>authorization-role-key</ese-variable>
                   </jwt-extraction>
               </jwt-extractions>
           </jwt-preprocessor>
       </authorization-preprocessors>
          <allow-all-authorization-manager/>
       </listener-pipeline>
       <!-- secure access to the control center   -->
   </pipelines>

File Authorization Manager Setup 

Below is a further example of the ESE configuration that has the jwt-authentication manager sourcing the jwt-realm setup above and File Authorization Manager setup using file-based realm to apply authorization policies based on the role.

<authorization-preprocessors>
           <jwt-preprocessor prefix="{{" postfix="}}">
               <source>authentication-byte-secret</source>
               <jwt-extractions>
                   <jwt-extraction>
                       <jwt-claim>roles</jwt-claim>  
                       <ese-variable>authorization-role-key</ese-variable>
                   </jwt-extraction>
               </jwt-extractions>
           </jwt-preprocessor>
       </authorization-preprocessors>
<!-- authorize over a file -->
<file-authorization-manager>
    <realm>file-realm</realm>
    <use-authorization-key>false</use-authorization-key>
    <use-authorization-role-key>true</use-authorization-role-key>
</file-authorization-manager>

ESE File Realm - Example for Authorization Based on Role Key 

<!-- roles are fetched via AUTHENTICATION_ROLE_KEY-->
<roles>
   <role>
       <id>niagara4</id>  ← Match to your scope name 
       <permissions>
           <permission>
               <topic>topic-1</topic>
               <qos>ALL</qos>
               <activity>PUBLISH</activity>
           </permission>
           <permission>
               <topic>topic-2</topic>
               <qos>ALL</qos>
               <activity>SUBSCRIBE</activity>
           </permission>
       </permissions>
   </role>

Test to Get Client Token 

You can test your setup and verify the request of a client token with third-party tools like Postman or curl command. Below are steps to use Postman for that purpose: 

  1. Download Postman

  2. Go to Post 

  3. Click on Body section 

  4. Click x-www-form-urlencoded 

Add the below details: 

  • Post, enter your Entra Tenant ID URL https://login.microsoftonline.com/[TENANTID]/oauth2/v2.0/token

  • client_id [YOUR CLIENT ID]

  • client_secret = [YOUR SECRET]

  • scope = api://[YOUR API URL]/.default

  • grant_type = client_credentials

Click Send, and if all is successful, you get the access_token (screenshot sample below).

Testing your setup and verifying the request of a client token with third-party tools like Postman

You can copy the access token which you can then use with any MQTT test client like the HiveMQ MQTT CLI as the password to test authentication. Optionally, you can navigate to jwt.io and decode the token to check valid information for claim and scopes as you have set up in Entra ID.  

Conclusion

In conclusion, the HiveMQ Enterprise Security Extension (ESE) stands as a critical solution for securing large-scale IoT deployments, offering robust authentication, authorization, and encryption capabilities alongside seamless integration with enterprise systems such as Microsoft Entra for OAuth 2.0/JWT authentication. In Part 2 of this series, we will show how to set up Single Sign On (SSO) for users to access the HiveMQ Control Center portal with Microsoft Entra ID. Stay tuned.

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

Implementing Authentication in HiveMQ Without Active Directory Schema Changes

A step-by-step guide to implement access control management and authentication inside of HiveMQ Broker without active directory schema changes.

Blog

Stopping the Scam: Anomaly Detection and Fraud Prevention with MQTT

Learn how MQTT & HiveMQ platform help provide deeper insights into IoT/IIoT data, detect anomalies as they occur, & safeguard against fraudulent activities.

Blog

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

A step-by-step guide to secure MQTT devices and your IoT ecosystem with OIDC authentication, HiveMQ control center, and Microsoft Entra.

Blog

Understanding HiveMQ’s ISO/IEC 27001 Certification for Information Security Management

Explore why & how HiveMQ adopted ISO/IEC 27001 information security management standard to protect data, intellectual property, & consumer information.

Blog

Navigating Cybersecurity Concerns in Industrial IoT Deployments

Explore how authentication, encryption, hardware security, audits, & tailored security approaches can help secure your IIoT systems against Cybersecurity.

Blog

Securing HiveMQ Broker Deployments With Intermediate CA Certificates

Learn how to secure HiveMQ MQTT broker deployments by adopting a hierarchical approach, with Root CA delegating authority to Intermediate CAs.

Blog

Securing Data in IoT Deployments

Learn how to enhance the security of IoT deployments while using MQTT, the de facto protocol for IoT, and HiveMQ’s Enterprise Security Extension (ESE).

Blog

Reinforcing Security of OT Systems in IIoT with MQTT and HiveMQ

Explore potential attacks on an MQTT Broker, security challenges in OT for IIoT, and discover how MQTT and HiveMQ can effectively mitigate these threats.

Blog

Securing the Unified Namespace Architecture for IIoT

Learn how to address key security challenges associated with Unified Namespace (UNS) in IIoT environments with actionable strategies and best practices.

Blog

Step Up Your MQTT Security with JWT Authentication on HiveMQ Cloud Starter

Explore how JSON Web Token (JWT) feature in HiveMQ Cloud Starter helps bring advanced security measures to your MQTT projects. Learn more.

Blog

Enhance Your IoT Security with Client Certificate Authentication on HiveMQ Cloud Starter

Explore the security enhancement to HiveMQ Cloud Starter. The feature, Client Certificate Authentication, helps with IoT security. Learn more.

Blog

Managing MQTT Security on HiveMQ Cloud Starter

A guide for IoT developers to get started with cloud-based, fully managed pay-as-you-grow MQTT platform, HiveMQ Cloud Starter, and its security.

Blog

Configuring HiveMQ Control Center Authentication and Authorization with Microsoft Active Directory

Learn how to configure HiveMQ's Control Center to authenticate and authorize users through Microsoft Active Directory.

Blog

HiveMQ is not affected by Log4Shell

Announcement about HiveMQ and the recent security vulnerability known as Log4Shell.

Blog

Mitigate IoT Attacks with Key MQTT Security Principles

By adhering to key MQTT security principles, we can mitigate several IoT attacks.

Blog

Implementing MQTT Challenge-Response Authentication

Learn how to integrate challenge-response-authentication into a HiveMQ extension.

Blog

Integrating HiveMQ with Okta

An introduction on using HiveMQ, the HiveMQ Enterprise Security Extension, and the Okta cloud to secure your MQTT deployment.

Blog

Setting up TLS for your cloud-based MQTT broker

Step by step guide on configuring HiveMQ to utilize mutual TLS encryption for device to server communication as well as inter server communication.

Blog

Role Based Access Control to Secure an MQTT Broker

Learn how to use HiveMQ, the HiveMQ Enterprise Security Extension, and Postgres DB to secure the access to the HiveMQ Control Center.

Blog

IoT Security in the cloud - How to integrate IoT Device Authentication and Authorization with HiveMQ and AWS

Bring IoT security in the cloud with HiveMQ Security Extension and AWS RDS Postgres DB. Build a secured high availability MQTT broker cluster in the cloud.

Blog

A Better Solution for IoT Security and MQTT

The new HiveMQ Enterprise Security Extension is built to meet security requirements of IoT business.

Blog

HiveMQ - TLS and MQTT: How is the performance affected?

Learn how much resources are needed for MQTT and SSL in this benchmark and get rid of the significant overhead TLS adds.

Blog

MQTT Security Fundamentals - Wrapping up the complete series

Get the entire list of MQTT Security Fundamentals in one go. Learn how to secure your IoT and IIoT applications.

Blog

Securing MQTT Systems - MQTT Security Fundamentals

MQTT Security Fundamentals: Learn how to secure MQTT deployments and harden the deployment to prevent cyberattacks.

Blog

MQTT Message Data Integrity - MQTT Security Fundamentals

Explore how to sign MQTT messages. Find out how digital signatures/MACs, and checksums for MQTT messages work and what problems they solve.

Blog

Payload Encryption - MQTT Security Fundamentals

Explore this MQTT Security Fundamentals blog discussing why and when MQTT payload encryptions should be used, how it works & what are the advantages.

Blog

OAuth 2.0 & MQTT - MQTT Security Fundamentals

MQTT Security Fundamentals: Learn the basic concepts of Oauth 2.0 and how it plays along with MQTT clients and brokers.

Blog

X509 Client Certificate Authentication - MQTT Security Fundamentals

Learn how to add an additional layer of security to MQTT with X509 client certificates and find out the challenges of using this approach

Blog

TLS/SSL - MQTT Security Fundamentals

MQTT Security Fundamentals: Learn about transport encryption with TLS/SSL while implementing MQTT.

Blog

Authorization - MQTT Security Fundamentals

Learn how authorization works in MQTT. Take your MQTT security to next level and safeguard the communication between your IoT devices.

Blog
HiveMQ logo
Review HiveMQ on G2