Configuring HiveMQ Security Extension with Active Directory for MQTT Client Authentication and Authorization
- Sheetal Shet
This guide walks you through configuring the HiveMQ Security Extension to use Active Directory (AD) to authenticate and authorize MQTT clients through the LDAP realm.
Prerequisites:
A fully configured Active Directory server with the appropriate users and permissions.
Valid HiveMQ Security Extension license
latest HiveMQ version.
Instructions
1. Configuring the LDAP Realm
To integrate Active Directory with HiveMQ, you’ll need to configure the LDAP realm. Details can be found in the HiveMQ documentation.
Here’s how to set up the ldap-realm in the ESE config.xml file:
base-dn: LDAP distinguished name
simple-bind:
rdns: The relative distinguished names (RDN) of the base DN that the ESE uses to bind to the LDAP server. Make sure that this DN is bindable and has the necessary rights to search for the users and permissions.
userPassword: The password portion that the ESE uses to perform a simple bind operation on the LDAP server.
<ldap-realm>
<name>my-ldap-server</name>
<enabled>true</enabled>
<configuration>
<servers>
<ldap-server>
<host>your hostname</host>
<port>389</port>
</ldap-server>
</servers>
<tls>tcp</tls>
<base-dn>dc=hivemq,dc=com</base-dn>
<simple-bind>
<rdns>cn=ese,cn=hivemq</rdns>
<userPassword>password</userPassword>
</simple-bind>
</configuration>
</ldap-realm>Configuring the LDAP Authentication Manager
Next, to implement custom authentication logic using LDAP, you must configure the LDAP Authentication Manager in your ESE config.xml:clients-rdns: LDAP directory name.
uid-attribute: The unique LDAP attribute that is used to identify every entry in the subtree of client RDNs. The default setting is uid.
<ldap-authentication-manager>
<realm>my-ldap-server</realm>
<clients-rdns>ou=mqtt-clients,ou=iot-services</clients-rdns>
<uid-attribute>cn</uid-attribute>
</ldap-authentication-manager>Configuring the LDAP Authorization Manager
For custom authorization logic over LDAP, you’ll need to configure the LDAP Authorization Manager in the ESE config.xml:
You can also use different realms for Authorization logic, for example: File-realm, SQL-realm etc. then you will need to use the respective authorization manager of that realm. For more details please check our documentation.
<ldap-authorization-manager>
<realm>my-ldap-server</realm>
<use-authorization-key>false</use-authorization-key>
<use-authorization-role-key>true</use-authorization-role-key>
</ldap-authorization-manager>Final
config.xmlExample
Here’s an overview of how the config.xml will look after completing the steps:
Restart the Broker
After making changes to AD users or permissions, either restart the broker or the ESE to apply the updates. Please note that ESE caches permissions by default.