Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

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:

  1. A fully configured Active Directory server with the appropriate users and permissions.

  2. Valid HiveMQ Security Extension license

  3. latest HiveMQ version.

\uD83D\uDCD8 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: 

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

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

<ldap-authentication-manager>
    <realm>my-ldap-server</realm>
    <clients-rdns>ou=mqtt-clients,ou=iot-services</clients-rdns>
    <uid-attribute>cn</uid-attribute>
    <required-object-class>hmq-mqttClient</required-object-class>
</ldap-authentication-manager>

  1. 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>
    <directory-descent>false</directory-descent>
    <use-authorization-key>false</use-authorization-key>
    <use-authorization-role-key>true</use-authorization-role-key>
</ldap-authorization-manager>

  1. Final config.xml Example

Here’s an overview of how the config.xml will look after completing the steps:

<?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>
        <!-- Enable LDAP Realm  -->
        <ldap-realm>
            <name>my-ldap-server</name>
            <enabled>true</enabled>
            <configuration>
                <servers>
                    <ldap-server>
                        <host>testhivemq.com</host>
                        <port>389</port>
                    </ldap-server>
                </servers>
                <tls>tcp</tls>
                <base-dn>DC=testhivemq,DC=com</base-dn>
                <simple-bind>
                    <rdns>CN=HiveMQ,OU=Management,OU=hivemq/rdns>
                    <userPassword>hivemq</userPassword>
                </simple-bind>
            </configuration>
        </ldap-realm>
    </realms>
    <pipelines>
        <!-- Secure access to the MQTT broker -->
        <listener-pipeline listener="ALL">
            <!-- Authenticate MQTT client against a LDAP Server -->
            <ldap-authentication-manager>
                <realm>my-ldap-server</realm>
                <clients-rdns>CN=customer1,OU=Customers</clients-rdns>
                <uid-attribute>cn</uid-attribute>
           </ldap-authentication-manager>
            <!-- Authorize MQTT client client against a LDAP Server -->
            <ldap-authorization-manager>
                <realm>my-ldap-server</realm>
                <use-authorization-key>true</use-authorization-key>
                <use-authorization-role-key>true</use-authorization-role-key>
            </ldap-authorization-manager>
        </listener-pipeline>
    </pipelines>
</enterprise-security-extension>

  1. Restart the Broker

After making changes to AD users or permissions, restart the broker and the ESE to apply the updates. Please note that ESE caches permissions by default.

  • No labels