Authenticating MQTT Devices with HiveMQ and Microsoft Entra

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.

In the Register an application page that opens, fill out the Name field and click Register.

Step 2:

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

• Application (client) ID 

• Directory (tenant) ID

You will need these for ESE config setup. 

Step 3:

Create a New client secret under Certificates & secrets.

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. 

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. 

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

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.

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. 

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.

ESE File Realm - Example for Authorization Based on Role Key 

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

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.