How to install HiveMQ object classes into Windows AD

This knowledge base article provides a step-by-step guide for configuring Windows Active Directory (AD) to manage access control for:

Control Center
MQTT clients
Rest API

There is a predefined schema that the HiveMQ Enterprise Security Extension (ESE) utilizes to determine the permissions an account has when publishing or subscribing to MQTT messages or what is available to them when logging into the Control Center.

The predefined schema consists of:

In this example, we will configure Windows AD to allow ADMIN access in the Control Center.

📋 Prerequisites

Latest version of HiveMQ installed
Enterprise Security license (.elic)
Active Directory and Active Directory Services installed in Windows
LDAP Authentication is configured using ESE

Instructions

Section 1: LDAP Authentication

Before implementing LDAP Authorization, it is essential to verify that LDAP Authentication for the Control Center is fully operational.

Steps:

Ensure that your <hivemq>/extensions/hivemq-enterprise-security-extension/conf/config.xml follows the formatting and resembles the example below:

<?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>
        <ldap-realm>
            <name>ldap-server</name>
            <enabled>true</enabled>
            <configuration>
                <servers>
                    <ldap-server>
                        <host><ldap host></host>
                        <port><ldap port></port>
                    </ldap-server>
                </servers>
                <tls>tcp</tls>
                <base-dn>dc=hivemq,dc=com</base-dn>
                <simple-bind>
                    <rdns>cn=Administrator,cn=User</rdns>
                    <userPassword><rdns password></userPassword>
                </simple-bind>
            </configuration>
        </ldap-realm>
    </realms>
	<pipelines>
        <listener-pipeline listener="ALL">
            <allow-all-authentication-manager/>
            <allow-all-authorization-manager/>
        </listener-pipeline>
        <control-center-pipeline>
            <ldap-authentication-manager>
                <realm>ldap-server</realm>
                <clients-rdns>cn=Users</clients-rdns>
                <uid-attribute>SAMAccountName</uid-attribute>
            </ldap-authentication-manager>
            <ldap-authorization-manager>
                <realm>ldap-server</realm>
                <use-authorization-key>true</use-authorization-key>
                <use-authorization-role-key>false</use-authorization-role-key>
            </ldap-authorization-manager>
        </control-center-pipeline>
    </pipelines>
</enterprise-security-extension>

Key Configuration Elements:

<control-center-pipeline><ldap-authentication-manager><clients-rdns> - Points to the OU or CN where the group of Control Center users reside
<control-center-pipeline><ldap-authorization-manager><use-authorization-key> = true - Is enabled, where ESE is instructed to look for user-specific permissions in Windows AD
<control-center-pipeline><ldap-authorization-manager><use-authorization-role-key> = false - Is disabled, where ESE is instructed not to use role-specific permissions in Windows AD

With the config.xml above, this will allow us to log in to Control Center however, it will not provide any heightened authorization other than being able to read the main dashboard:

Section 2: Install HiveMQ object classes into Windows AD

In the previous section, we ensured that users can successfully log in and that their identities are correctly recognized. This serves as the foundation for the subsequent steps.

In this section, we will extend your Windows Active Directory Schema by defining the necessary Classes and Attributes, followed by configuring the required Permissions. These modifications allow your Windows AD to store and serve the specific data required for HiveMQ authorization.

The following steps should be performed by your System / Windows Administrator before step 1:

Schema Admin Rights: Your account must be a member of the Schema Admins group.
Schema Updates Enabled: By default, schema updates are disabled. You may need to enable them via the registry or the MMC snap-in.
Backup: Ensure you have a current System State backup of your Domain Controller.

Steps:

Copy the ldf from your HiveMQ installation directory (<hivemq>/extensions/hivemq-enterprise-security-extension/scripts/ldap/ad-hivemq.ldf), to your Windows Domain Controller where AD is accessible
Open PowerShell and navigate to the file path where the .ldf file was copied
Execute the following command:

ldifde -i -u -f ad-hivemq.ldf -s server:port -b username domain password -j . -c "cn=Configuration,dc=X" "cn=Configuration,<domain>"

A successful execution will look like:

Section 3: Apply user-specific permission for Authorization

With the HiveMQ Enterprise Security Extension (ESE) schema successfully integrated into Windows AD, the final step is to grant the necessary permissions to your designated Admin user.

Steps:

Create a Windows AD test user located in the same CN as per Line 35 in our config.xml (clients-rdns)
Open PowerShell and execute the following command to apply the object class, attribute and permission:

$dn = (Get-ADUser -Identity "<SAMAccountName>").DistinguishedName

Set-ADObject -Identity $dn -Add @{
    objectClass                 = 'hmq-controlCenterUser'
    'hmq-controlCenterPermission' = 'HIVEMQ_SUPER_ADMIN'
}

…replacing SAMAccount with that of the test user

Go to Active Directory Users and Computers (dsa.msc)
Locate your test user and go to properties:

Navigate to the Attribute Editor tab, and verify that the hmq-controlCenterPermission attribute with the HIVEMQ_SUPER_ADMIN permission has been assigned to the user:

Let us finalize our checks and log in to the Control Center. This time, we will see that we now have ADMIN permissions:

Section 4: Apply role-specific permission for Authorization

If you prefer to manage permissions at scale using Security Groups rather than assigning them to individual users, follow these steps to apply the object classes and permissions accordingly.

Steps:

On your Domain Controller, let's go back to Active Directory Users and Computers and let's create a Security group:

Once the group has been created, right-click on the Security group → Properties → Members → Add → find your test user and add it as a member
In PowerShell, execute the following command to apply the object class, attribute and permission:

Set-ADObject -Identity "<DN of Security group>" -Add @{
    objectClass                 = 'hmq-controlCenterUser'
    'hmq-controlCenterPermission' = 'HIVEMQ_SUPER_ADMIN'
}

…replacing the DN of the Security group

Verify that the permission has been applied to the Security group:

In ESE config.xml, change lines 40 and 41 from:

<use-authorization-key>true</use-authorization-key>
<use-authorization-role-key>false</use-authorization-role-key>

to…

<use-authorization-key>false</use-authorization-key>
<use-authorization-role-key>true</use-authorization-role-key>

This will instruct ESE to use role-specific permissions rather than user.

Restart the HiveMQ service to pick up the changes
Log in to the Control Center and confirm your user has ADMIN rights assigned via the relevant Security group