Configuring LDAP Authentication for HiveMQ in Kubernetes
Overview
This article addresses the configuration of LDAP authentication for HiveMQ deployments in Kubernetes environments. Users may encounter challenges when attempting to configure LDAP or OAuth authentication, particularly when documentation lacks specific Kubernetes implementation details or command references.
Issue Description
Users deploying HiveMQ in Kubernetes require LDAP or OAuth authentication configuration but face the following challenges:
Unclear configuration steps for Kubernetes deployments
Missing specific commands or configuration examples
Uncertainty about required extensions
Lack of industry-standard implementation guidance
Applicable Products
HiveMQ Edge (Kubernetes deployment)
HiveMQ Self-Managed (with Enterprise Security Extension)
Prerequisites
Valid HiveMQ license (for Enterprise features)
Kubernetes cluster with kubectl access
Helm 3.x installed
Access to LDAP server with appropriate credentials
Base DN and service account information for LDAP binding
Solution for HiveMQ Edge in Kubernetes
HiveMQ Edge supports LDAP authentication for the Admin API through Helm chart configuration.(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
Step 1: Configure LDAP in values.yaml
Add the following LDAP configuration to your values.yaml file:(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
adminLdap:
enabled: true
tlsMode: "LDAPS"
servers:
- host: "ldap.example.com"
port: 636
simplebind:
userDn: "cn=admin,dc=example,dc=org"
password: "admin-password"
uid: "uid"
rdns: "ou=people,dc=example,dc=org"
directoryDescent: false
maxConnections: 5
connectionTimeoutMillis: 10000
searchTimeoutSeconds: 10
Step 2: Configure TLS Truststore (if using LDAPS or START_TLS)
If your LDAP server uses self-signed certificates, you must configure a truststore.(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
First, encode your truststore file:(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
# On macOS/BSD:
base64 -i truststore.jks | tr -d '\n' > truststore.jks_b64
# On Linux:
base64 -i truststore.jks -o truststore.jks_b64 -w 0
Then update your values.yaml:(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
adminLdap:
enabled: true
tlsMode: "LDAPS"
servers:
- host: "ldap.example.com"
port: 636
tls:
enabled: true
create:
enabled: true
simplebind:
userDn: "cn=admin,dc=example,dc=org"
password: "admin-password"
uid: "uid"
rdns: "ou=people,dc=example,dc=org"
Step 3: Deploy with Helm
Install or upgrade HiveMQ Edge with the truststore configuration:(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
helm upgrade edge hivemq/hivemq-edge -f values.yaml \
--set-file adminLdap.tls.create.file=truststore.jks_b64 \
--set adminLdap.tls.create.password=${TRUSTSTORE_PASSWORD}
Step 4: Using External Secrets (Alternative Approach)
For production environments, use Kubernetes secrets:(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
adminLdap:
enabled: true
tlsMode: "LDAPS"
servers:
- host: "ldap.example.com"
port: 636
tls:
enabled: true
truststore:
truststoreSecretName: "my-ldap-truststore"
truststoreSecretKey: "truststore.jks"
passwordSecretName: "my-ldap-truststore"
passwordSecretKey: "password"
simplebind:
userDn: "cn=admin,dc=example,dc=org"
password: "admin-password"
uid: "uid"
rdns: "ou=people,dc=example,dc=org"
Solution for HiveMQ Self-Managed with Enterprise Security Extension
For HiveMQ Self-Managed deployments, LDAP authentication requires the Enterprise Security Extension.(2)(https://docs.hivemq.com/hivemq-enterprise-security-extension/latest/ese.html)(3)(https://docs.hivemq.com/hivemq-enterprise-security-extension/4.28/ese.html)
Step 1: Configure LDAP Realm
Add an LDAP realm to your Enterprise Security Extension config.xml:(4)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3145203717/Configuring+HiveMQ+Security+Extension+with+Active+Directory+for+MQTT+Client+Authentication+and+Authorization)
<ldap-realm>
<name>my-ldap-server</name>
<enabled>true</enabled>
<configuration>
<hostname>your hostname</hostname>
<port>389</port>
<connection-security-mode>tcp</connection-security-mode>
<base-dn>dc=hivemq,dc=com</base-dn>
<simple-bind>
<rdns>cn=ese,cn=hivemq</rdns>
<userPassword>password</userPassword>
</simple-bind>
</configuration>
</ldap-realm>
Step 2: Configure LDAP Authentication Manager
Add the LDAP authentication manager to your pipeline:(4)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3145203717/Configuring+HiveMQ+Security+Extension+with+Active+Directory+for+MQTT+Client+Authentication+and+Authorization)
<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>
Step 3: Configure LDAP Authorization Manager
Add the LDAP authorization manager:(4)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3145203717/Configuring+HiveMQ+Security+Extension+with+Active+Directory+for+MQTT+Client+Authentication+and+Authorization)
<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>
Step 4: Complete Configuration Example
Here is a complete ESE configuration with LDAP:(4)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3145203717/Configuring+HiveMQ+Security+Extension+with+Active+Directory+for+MQTT+Client+Authentication+and+Authorization)
<ldap-realm>
<name>my-ldap-server</name>
<enabled>true</enabled>
<configuration>
<hostname>testhivemq.com</hostname>
<port>389</port>
<connection-security-mode>tcp</connection-security-mode>
<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>
<pipelines>
<listener-pipeline listener="ALL">
<ldap-authentication-manager>
<realm>my-ldap-server</realm>
<clients-rdns>CN=customer1,OU=Customers</clients-rdns>
<uid-attribute>cn</uid-attribute>
</ldap-authentication-manager>
<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>
Step 5: Restart or Reload
After configuration changes, restart the broker or reload the ESE to apply updates.(4)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3145203717/Configuring+HiveMQ+Security+Extension+with+Active+Directory+for+MQTT+Client+Authentication+and+Authorization)
Configuration Parameters Reference
HiveMQ Edge LDAP Parameters
Property | Required | Description |
|---|---|---|
adminLdap.enabled | Yes | Enable LDAP authentication |
adminLdap.servers | Yes | Array of LDAP server configurations with host and port |
adminLdap.tlsMode | No | TLS mode: NONE, START_TLS, or LDAPS (default: NONE) |
adminLdap.simplebind.userDn | Yes | Service account DN for LDAP binding |
adminLdap.simplebind.password | Yes | Service account password |
adminLdap.uid | No | LDAP attribute for username lookup (default: uid) |
adminLdap.rdns | Yes | Base DN for user searches or DN construction |
adminLdap.directoryDescent | No | Enable hierarchical LDAP searches (default: false) |
adminLdap.maxConnections | No | Maximum LDAP connection pool size (default: 1) |
adminLdap.connectionTimeoutMillis | No | LDAP connection timeout in milliseconds |
adminLdap.searchTimeoutSeconds | No | LDAP search timeout in seconds (default: 5) |
Important Notes
LDAP authentication in HiveMQ Edge replaces user-based authentication when enabled.(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
The Enterprise Security Extension caches permissions by default.(4)(https://hivemq.atlassian.net/wiki/spaces/KB/pages/3145203717/Configuring+HiveMQ+Security+Extension+with+Active+Directory+for+MQTT+Client+Authentication+and+Authorization)
For production deployments, always use LDAPS or START_TLS to protect credentials in transit.(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
Changes to LDAP configuration do not affect already-connected clients; they only apply to new connections.(3)(https://docs.hivemq.com/hivemq-enterprise-security-extension/4.28/ese.html)
OAuth Configuration
OAuth configuration is not directly covered in the provided documentation for Kubernetes deployments. For OAuth requirements, contact HiveMQ support for guidance specific to your deployment architecture.
Prevention and Best Practices
Security Best Practices
Always use encrypted connections (LDAPS or START_TLS) for LDAP authentication.(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
Store sensitive credentials in Kubernetes secrets rather than values.yaml files.(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
Use service accounts with minimal required permissions for LDAP binding.(2)(https://docs.hivemq.com/hivemq-enterprise-security-extension/latest/ese.html)
Implement role-based permissions rather than user-specific permissions for better maintainability.(2)(https://docs.hivemq.com/hivemq-enterprise-security-extension/latest/ese.html)(3)(https://docs.hivemq.com/hivemq-enterprise-security-extension/4.28/ese.html)
Configuration Management
Version control your values.yaml and ESE configuration files
Test LDAP connectivity before deploying to production
Document your LDAP schema and user/group structure
Plan for certificate rotation when using TLS
Monitor LDAP connection pool usage and adjust maxConnections as needed(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
Kubernetes-Specific Recommendations
Use external secret managers for production deployments(1)(https://docs.hivemq.com/hivemq-edge/installing-hivemq-edge.html)
Configure appropriate resource limits for HiveMQ pods
Implement health checks and readiness probes
Use Helm for consistent deployments across environments
Maintain separate configurations for development, staging, and production