Configuring HiveMQ Control Center Authentication and Authorization with Microsoft Active Directory

The HiveMQ Control Center provides management tools and analytics to monitor and maintain a deployed HiveMQ system. We have included finely-grained access control to this powerful tool to align with customer’s enterprise security needs and existing infrastructure.

In this article, we explore how to configure HiveMQ’s Control Center to authenticate and authorize users through Microsoft Active Directory.

Before we jump in, let’s define the key products involved:

HiveMQ Control Center is part of our MQTT platform and offers a detailed, real-time overview of your MQTT broker cluster. It provides a sophisticated level of observability and is ideal for enterprise-grade operations.

Microsoft Active Directory is a service that provides a variety of network services like LDAP directory services, Kerberos-based authentication, DNS-based naming, etc. LDAP (Lightweight Directory Access Protocol) is a bullet-proof and mature protocol used for authentication and authorization. It is widely used among HiveMQ customers and is often part of their existing enterprise infrastructure.

The HiveMQ Enterprise Security Extension provides enterprise-level security features, including the ability to authenticate and authorize against various systems like LDAP, SQL databases, and others. The HiveMQ Enterprise Security Extension is able to handle LDAP authentication and/or authorization of HiveMQ Control Center users.

Prerequisites for Configuration

• An active HiveMQ Professional or Enterprise Edition installation

• HiveMQ Enterprise Security Extension

• HiveMQ Control Center listener properly configured and fully operational

• Windows Server running as an Active Directory Domain Controller

• The HiveMQ broker should be configured to successfully resolve the AD domain via DNS. If these conditions are not met, the HiveMQ broker may encounter difficulty locating your domain controller within your network.

Setting up the Active Directory

First, please ensure that your Microsoft Active Directory instance is correctly configured. You should have your domain controllers set up and a list of users who will be given access to the HiveMQ Control Center.

Configuring HiveMQ Enterprise Security Extension for Active Directory Authentication and Authorization

HiveMQ uses the Enterprise Security Extension to integrate with Microsoft Active Directory. This integration requires specific parameters to be set in the config.xml file of the extension, including the server URL of the Active Directory instance, domain name, and service account credentials.

1. Managing User Access

Within the Microsoft Active Directory, you can manage which users or groups have access to the HiveMQ Control Center. By properly setting up your organization unit and user groups, you can control who can access the Control Center, providing an additional layer of security.

Microsoft Active Directory Overview

2. Configuring the Enterprise Security Extension (ESE)

The structure will be explained in the example of the following ESE config.xml

Description

1. The header of the XML file specifies the schema file config.xsd. The content of the XML file must match the schema.

2. The ldap-realm specifies that the ESE must connect to the FQDN “dc.hivemq.com” port 389 via TCP. The service account user should bind to the LDAP using Base DN DC=hivemq,DC=com, the user’s related DN is CN=HiveMQ,CN=Users and the password is ServiceAccount_Password.

The HiveMQ Enterprise Security Extension supports this kind of distributed authentication load balancing. By allowing the connection to multiple LDAP servers, authentication requests can be accepted in a round-robin manner. Should the connection to one of the LDAP servers fail, ESE ensures that the remaining LDAP servers take over the load and thus keep HiveMQ and the entire infrastructure highly available.

The sample below shows how to configure multiple instances.

3.The file-realm settings should be read from the file ese-file-realm-ldap.xml.

The ldap-authentication-manager will search for LDAP objects among those whose clients-rdns is CN=Users and where the sAMAccountName matches the control center login and will try to authenticate with the control center password.

Apart from the commonly used “samAccountName” attribute, Active Directory allows you to use various other attributes to facilitate logins. One such attribute is the company user’s email address. Depending on the configuration of your authentication and login systems, you can leverage the “mail” or “userPrincipalName” attribute in AD as a unique identifier for login purposes.

UserPrincipleName Attribute

If the authentication was successful, the authorization-key contains the full DN of the authenticated user and the authorization-role-key contains the value of the MemberOf attribute. Each group the user is a member of is enclosed into {{ }} and contains the full DN of the group, sample below:

The authorization-role-key in this format is treated by the file-authorization-manger as a list of items where each item is enclosed in enclosed into {{ }}.

If there is a role in the ese-file-realm-ldap.xml in which role.id equals an item from the list, then the role’s permissions are granted to the user.

Authentication-preprocessors and authorization-preprocessors debug logs for “HiveMQ_ControlCenter_User1 / cc_user1”

Console Debug Logs cc_user1

Authentication-preprocessors and authorization-preprocessors debug logs for “HiveMQ_ControlCenter_User2 / cc_user2”

Console Debug Logs cc_user2

Authentication-preprocessors and authorization-preprocessors debug logs for “HiveMQ_ControlCenter_User3 / cc_user3”

Console Debug Logs cc_user3

For more information refer to our LDAP documentation.

ese-file-realm-ldap.xml example:

To implement fine-grained access control for Control Center, please check all permissions available in our documentation.

Control Center Permission AD Group for user "cc_user1"

HiveMQ Control Center Super Admin Permission for user "cc_user1"

Control Center Permission AD Group for user "cc_user2"

HiveMQ Control Center License View Page Permission for user "cc_user2"

You can assign a set of Control Center permissions to Active Directory users by adding multiple Control Center permissions groups.

Control Center Permissions AD Groups for user "cc_user3"

HiveMQ Control Center License View and Support Page Permissions for user "cc_user3"

Once your setup is complete, it is important to test it. Try to access the HiveMQ Control Center using the credentials of a user with the proper permissions in your Active Directory. If the configuration is correct, you should be able to log in successfully.

Additional Considerations and Limitations

• The HiveMQ broker server does not need to join the domain controller.

• It’s recommended to create a dedicated user that will be used as a Service Account to grant access to the Active Directory.

• All Control Center users should be situated within the same Active Directory Builtin Users container (CN), Organizational Unit (OU), or its sub-OUs. This organizational arrangement is required due to the LDAP realm allowing only a single CN or OU to be specified in the configuration file.

• While it is essential that all Control Center users reside within the same Active Directory Builtin Users container (CN), Organizational Unit (OU), or its sub-OUs, it’s important to note that Active Directory (AD) groups designated for Control Center permissions exhibit more flexibility. These groups can be positioned anywhere within the AD tree, allowing for enhanced adaptability in your AD structure.

• The default LDAP port number is 389. If you are using SSL/TLS, the default LDAP port number is 636. When setting up LDAP over SSL/TLS, a few changes in your configuration are needed. As you switch from port 389 to port 636, your security settings need to be updated as well. In the HiveMQ configuration, this means changing the <tls> setting from TCP to TLS.

• You can remove <authentication-preprocessors> and <authorization-preprocessors> sections from the config file, we use it here only to debug purposes.

• In the event that user authentication is successful, yet the subsequent authorization step does not complete as expected, the user will still be able to access the Control Center with a default “Dashboard Viewer” permission.

• The Microsoft Active Directory Forest Functional Level and Domain Functional Level settings used in this example were “Windows Server 2016.”

• CN stands for Common Name, OU Organizational Unit, and DC the Domain Component.

Troubleshooting Adding to the ESE Configuration File

We have spoken with customers who don’t have access to Active Directory and the IT Team only provided service account credentials. In this case, here is how to collect all the information required to add to the ESE configuration file.

One such tool is ’ldapsearch’, a command-line utility for querying an LDAP (Lightweight Directory Access Protocol) directory. It allows administrators to craft specific LDAP search queries, which can help to diagnose problems related to LDAP, such as connectivity and binding issues, incorrect filters, and more.

The ldapsearch utility is part of the openldap package. Here’s how you can install it on different Linux distributions:

1.Ubuntu/Debian: You can install ldapsearch on Ubuntu or Debian by using the apt package manager. Open a terminal and type:

2. CentOS/RHEL: For CentOS or RHEL, you would use the yum or dnf package manager. Open a terminal and type:

To check for an LDAP user using TLS, you can use the ldapsearch command. Here is a generic example, which you’ll need to adjust according to your LDAP server settings and the user you’re looking for.

The ldapsearch command without TLS (Transport Layer Security) is fairly similar.

Here’s what each part of the command does:

• H ldaps://ldap.example.com: This specifies the LDAP server. Replace ldap.example.com with your server’s address. The ldaps:// protocol designator is for LDAP over SSL/TLS. ldap:// as the protocol, indicating a non-encrypted LDAP connection.

• x: This enables simple authentication instead of SASL.

• D “cn=admin,cn=users,dc=example,dc=com”: This specifies the bind DN (Distinguished Name). The user specified here needs to have appropriate permissions to perform the search. Replace with an appropriate DN from your LDAP directory.

• W: This prompts for the bind DN’s password.

• b “dc=example,dc=com”: This specifies the base DN of the LDAP search. Replace with your base DN.

• (samAccountName=user): This is the LDAP search filter. In this case, it is searching for entries where the samAccountName attribute is user. Replace user with the username you are searching for.

Example:

ldapsearch Results for user "cc_user1"

Conclusion

Securing your HiveMQ Control Center with robust authentication and authorization is vital in maintaining the integrity of your IoT systems. By integrating HiveMQ with Microsoft Active Directory, you can leverage enterprise-grade security features, providing peace of mind and improved control over your MQTT deployments.

The HiveMQ Enterprise Security Extension support for LDAP means customers who are using LDAP services, like Microsoft Active Directory, OpenLDAP or Apache Directory Services can now easily integrate authentication and authorization with HiveMQ.

Remember, each organization’s needs and systems are unique. Therefore, always ensure your security setup is tailored to your specific requirements. For more technical guides and information, please refer to the official HiveMQ and Microsoft Active Directory documentation.