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


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" ?>
       <!-- a oauth provider-->
                   <username>CLIENT ID</username>
                   <password>SECRET PASSWORD</password>

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. 

   <!-- secure access to the mqtt broker -->
   <listener-pipeline listener="ALL">
       <!-- authenticate with provided jwts -->
               <exp-grace disconnect-after-expiry="true">300</exp-grace>
           <jwt-preprocessor prefix="{{" postfix="}}">
       <!-- secure access to the control center   -->

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.

           <jwt-preprocessor prefix="{{" postfix="}}">
<!-- authorize over a file -->

ESE File Realm - Example for Authorization Based on Role Key 

<!-- roles are fetched via AUTHENTICATION_ROLE_KEY-->
       <id>niagara4</id>  ← Match to your scope name 

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[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 and decode the token to check valid information for claim and scopes as you have set up in Entra ID.  


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.


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.


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.


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.


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.


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.


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).


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.


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.


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.


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.


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.


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.


HiveMQ is not affected by Log4Shell

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


Mitigate IoT Attacks with Key MQTT Security Principles

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


Implementing MQTT Challenge-Response Authentication

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


Integrating HiveMQ with Okta

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


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.


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.


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.


A Better Solution for IoT Security and MQTT

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


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.


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.


Securing MQTT Systems - MQTT Security Fundamentals

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


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.


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.


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.


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


TLS/SSL - MQTT Security Fundamentals

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


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.

HiveMQ logo
Review HiveMQ on G2