HiveMQ Edge REST API

HiveMQ Edge can be optionally configured to expose an administrative API and an administrative user interface. The admin user interface uses the API to fulfill all of its features.

HiveMQ Edge REST API Configuration

HiveMQ Edge is designed to use sensible default values. When you run the default HiveMQ Edge configuration, the HiveMQ Edge API web server and user interface start up with a listener bound to port 8080.

HiveMQ Edge default API configuration

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <enabled>true</enabled>
    </admin-api>
</hivemq>

Example configuration to change the HiveMQ Edge API listener address and port

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <listeners>
            <http-listener>
                <port>80</port>
                <bind-address>0.0.0.0</bind-address>
            </http-listener>
        </listeners>
    </admin-api>
</hivemq>

HiveMQ Edge API and User Interface Authentication

The HiveMQ Edge API is secured using a Bearer Token scheme. This authentication method involves presenting an HTTP header with the following format in all requests for secured resources:

Authorization : "Bearer <JWT>"

The JWT (JSON Web Token) is generated by calling the API endpoint:

POST  /api/v1/auth/authenticate

Username and password credentials that match an entity in your configuration XML should be posted to the endpoint. If the credentials are valid, the webservice returns a JWT that can be used to secure future requests. To add, remove, or modify the users who are allowed access to the API and user interface, edit the users element in your config.xml file.

Changing API Users

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <users>
            <user>
                <username>admin</username>
                <password>hivemq</password>
                <roles>
                    <role>admin</role>
                </roles>
            </user>
        </users>
    </admin-api>
</hivemq>

By default, the JWTs the authenticate endpoint issues expire after 30 minutes. You can change the expiry, and other parameters of the generated token in the API configuration XML file.

Example cURL command to request a JWT from localhost:8080

curl 'http://localhost:8080/api/v1/auth/authenticate' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{"password":"hivemq","userName":"admin"}' \
  | jq .token -r

Example configuration to change the generated JWT

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <generated-tokens>
            <keySize>2048</keySize>
            <issuer>HiveMQ-Edge</issuer>
            <audience>HiveMQ-Edge-Api</audience>
            <expiryTimeMinutes>30</expiryTimeMinutes>
            <tokenEarlyEpochThresholdMinutes>2</tokenEarlyEpochThresholdMinutes>
        </generated-tokens>
    </admin-api>
</hivemq>

Example configuration to add secure TLS to API

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <listeners>
            <https-listener>
                <port>443</port>
                <bind-address>127.0.0.1</bind-address>
                <tls>
                    <protocols>
                        <protocol>TLSv1.2</protocol>
                    </protocols>
                    <cipher-suites>
                        <cipher-suite>TLS_RSA_WITH_AES_128_CBC_SHA</cipher-suite>
                        <cipher-suite>TLS_RSA_WITH_AES_256_CBC_SHA256</cipher-suite>
                        <cipher-suite>SSL_RSA_WITH_3DES_EDE_CBC_SHA</cipher-suite>
                    </cipher-suites>
                </tls>
            </https-listener>
        </listeners>
    </admin-api>
</hivemq>

Table 1. Available TLS parameters
Name	Default	Mandatory	Description
`protocols`	`All enabled`	`no`	The enabled protocols. Possible entries are `TLSv1.2`, `TLSv1.1`, and `TLSv1`.
`cipher-suites`	`All cipher suites enabled`	`no`	The enabled cipher suites. If desired, define specific cipher suites to limit the number of suites that are enabled. NOTE: The available cipher suits are dependent on the SSL implementation that is used and not necessarily the same for all machines.
`keystore.path`	`none`	`yes`	The path to the key store where your certificate and private key are located.
`keystore.password`	`none`	`yes`	The password to open the key store.
`keystore.private-key-password`	`none`	`no`	The password for the private key (if applicable).

LDAP Authentication

HiveMQ Edge supports LDAP (Lightweight Directory Access Protocol) authentication for the Admin API, enabling centralized user management and authentication against your organization’s LDAP directory server.

Overview

LDAP authentication allows you to:

Authenticate Admin API users against an existing LDAP directory (Active Directory, OpenLDAP, etc.)
Centralize user management without maintaining separate credentials
Support enterprise identity management systems
Enable secure authentication with TLS/SSL encryption

All authenticated users are assigned the ADMIN role with full access to the Admin API.

Connection Security

HiveMQ Edge supports three TLS modes for LDAP connections:

LDAPS (Recommended)

LDAP over TLS/SSL establishes an encrypted connection from the start. This is the most secure option.

Default Port: 636
TLS Mode: LDAPS
Use Case: Production deployments with strict security requirements

START_TLS

Upgrades a plain LDAP connection to TLS using the StartTLS extended operation.

Default Port: 389
TLS Mode: START_TLS
Use Case: Production environments where LDAPS is not available

Plain LDAP (Not Recommended)

Unencrypted LDAP connection. Credentials and data are transmitted in clear text.

Default Port: 389
TLS Mode: NONE
Use Case: Development and testing only

For production use, we strongly recommend using LDAPS or START_TLS to protect credentials and data in transit.

Authentication Modes

HiveMQ Edge supports two methods for resolving user Distinguished Names (DNs):

Direct Binding (Default)

The user DN is constructed by combining the username with a base DN template. This is the fastest method and works well for flat LDAP structures.

Example: For username alice with configuration:

uid-attribute: uid
rdns: ou=people,dc=example,dc=org

The constructed DN would be: uid=alice,ou=people,dc=example,dc=org

Use this mode when:

Users are stored in a single organizational unit
The LDAP structure is flat and predictable
Performance is critical (no search overhead)

Directory Descent

Performs an LDAP search to locate the user’s DN. This method supports complex hierarchical LDAP structures where users may be in nested organizational units.

Use this mode when:

Users are distributed across multiple organizational units
The LDAP structure is hierarchical (e.g., separate OUs for departments)
User locations in the directory tree are not predictable

Directory Descent requires a service account with search permissions on the LDAP directory.

Configuration

LDAP authentication is configured in the Admin API section of the HiveMQ Edge configuration file (config.xml).

Basic Configuration Example

<admin-api>
    <enabled>true</enabled>
    <listeners>
        <http-listener>
            <port>8080</port>
            <bind-address>0.0.0.0</bind-address>
        </http-listener>
    </listeners>
    <ldap>
        <servers>
            <ldap-server>
                <host>ldap.example.com</host>
                <port>636</port>
            </ldap-server>
        </servers>
        <tls-mode>LDAPS</tls-mode>
        <simple-bind>
            <rdns>cn=admin</rdns>
            <userPassword>secret</userPassword>
        </simple-bind>
        <uid-attribute>uid</uid-attribute>
        <rdns>ou=people,dc=example,dc=org</rdns>
    </ldap>
</admin-api>

Configuration with TLS Truststore

When using self-signed certificates or custom Certificate Authorities:

<ldap>
    <servers>
        <ldap-server>
            <host>ldap.example.com</host>
            <port>636</port>
        </ldap-server>
    </servers>
    <tls-mode>LDAPS</tls-mode>
    <tls>
        <truststore-path>/opt/hivemq/conf/truststore.jks</truststore-path>
        <truststore-password>changeit</truststore-password>
        <truststore-type>JKS</truststore-type>
    </tls>
    <simple-bind>
        <rdns>cn=service-account</rdns>
        <userPassword>secret</userPassword>
    </simple-bind>
    <uid-attribute>sAMAccountName</uid-attribute>
    <rdns>dc=corp,dc=example,dc=com</rdns>
</ldap>

Configuration with Directory Descent

For hierarchical LDAP structures with nested organizational units:

<ldap>
    <servers>
        <ldap-server>
            <host>ldap.example.com</host>
            <port>389</port>
        </ldap-server>
    </servers>
    <tls-mode>START_TLS</tls-mode>
    <simple-bind>
        <rdns>cn=admin</rdns>
        <userPassword>secret</userPassword>
    </simple-bind>
    <uid-attribute>uid</uid-attribute>
    <rdns>dc=example,dc=org</rdns>
    <directory-descent>true</directory-descent>
    <search-timeout-seconds>10</search-timeout-seconds>
</ldap>

Multiple LDAP Servers (High Availability)

Configure multiple LDAP servers for failover, they will be used in a round robin fashion:

<ldap>
    <servers>
        <ldap-server>
            <host>ldap1.example.com</host>
            <port>636</port>
        </ldap-server>
        <ldap-server>
            <host>ldap2.example.com</host>
            <port>636</port>
        </ldap-server>
        <ldap-server>
            <host>ldap3.example.com</host>
            <port>636</port>
        </ldap-server>
    </servers>
    <tls-mode>LDAPS</tls-mode>
    <max-connections>5</max-connections>
    <simple-bind>
        <rdns>cn=admin</rdns>
        <userPassword>secret</userPassword>
    </simple-bind>
    <uid-attribute>uid</uid-attribute>
    <rdns>ou=people,dc=example,dc=org</rdns>
</ldap>

Configuration Options

LDAP Server Configuration

Element Required Default Description

Element	Required	Default	Description
`<servers>`	Yes	-	Container for LDAP server definitions
`<ldap-server>`	Yes	-	Individual LDAP server configuration
`<host>`	Yes	-	LDAP server hostname or IP address
`<port>`	Yes	-	LDAP server port (389 for plain/START_TLS, 636 for LDAPS)

<servers>

Yes

Container for LDAP server definitions

<ldap-server>

Yes

Individual LDAP server configuration

<host>

Yes

LDAP server hostname or IP address

<port>

Yes

LDAP server port (389 for plain/START_TLS, 636 for LDAPS)

TLS Configuration

Element Required Default Description

Element	Required	Default	Description
`<tls-mode>`	No	`NONE`	TLS encryption mode: `NONE`, `START_TLS`, or `LDAPS`
`<tls>`	No	-	TLS truststore configuration (optional)
`<truststore-path>`	No	System CAs	Path to Java truststore file
`<truststore-password>`	No	-	Truststore password
`<truststore-type>`	No	`JKS`	Truststore type: `JKS`, `PKCS12`, `JCEKS`

<tls-mode>

NONE

TLS encryption mode: NONE, START_TLS, or LDAPS

<tls>

TLS truststore configuration (optional)

<truststore-path>

System CAs

Path to Java truststore file

<truststore-password>

Truststore password

<truststore-type>

JKS

Truststore type: JKS, PKCS12, JCEKS

Authentication Configuration

Element Required Default Description

Element	Required	Default	Description
`<simple-bind>`	Yes	-	Service account credentials for LDAP binding
`<rdns>` (under simple-bind)	Yes	-	Relative DN of the service account
`<userPassword>`	Yes	-	Password for the service account
`<uid-attribute>`	No	`uid`	LDAP attribute used for username lookup
`<rdns>` (under ldap)	Yes	-	Base DN for user searches or DN construction
`<directory-descent>`	No	`false`	Enable directory descent for hierarchical searches
`<required-object-class>`	No	-	Optional object class filter for search results
`<search-timeout-seconds>`	No	`5`	Timeout for directory descent searches

<simple-bind>

Yes

Service account credentials for LDAP binding

<rdns> (under simple-bind)

Yes

Relative DN of the service account

<userPassword>

Yes

Password for the service account

<uid-attribute>

uid

LDAP attribute used for username lookup

<rdns> (under ldap)

Yes

Base DN for user searches or DN construction

<directory-descent>

false

Enable directory descent for hierarchical searches

<required-object-class>

Optional object class filter for search results

<search-timeout-seconds>

5

Timeout for directory descent searches

The <rdns> element represents a comma-separated sequence of RDN (Relative Distinguished Name) components. The full Distinguished Name (DN) is constructed by concatenating components: - Service Account DN = <simple-bind><rdns> + base <rdns> - User DN (direct binding) = <uid-attribute>={username} + base <rdns>

Connection Pool Configuration

Element Required Default Description

Element	Required	Default	Description
`<max-connections>`	No	`1`	Maximum number of connections in the pool
`<connect-timeout-millis>`	No	`10000` (system default)	Connection timeout in milliseconds
`<response-timeout-millis>`	No	`10000`	Response timeout in milliseconds

<max-connections>

1

Maximum number of connections in the pool

<connect-timeout-millis>

10000 (system default)

Connection timeout in milliseconds

<response-timeout-millis>

10000

Response timeout in milliseconds

Active Directory Configuration

Example for Active Directory

<ldap>
    <servers>
        <ldap-server>
            <host>ad.corp.example.com</host>
            <port>636</port>
        </ldap-server>
    </servers>
    <tls-mode>LDAPS</tls-mode>
    <simple-bind>
        <rdns>CN=HiveMQ Service,OU=Service Accounts</rdns>
        <userPassword>ServiceAccountPassword</userPassword>
    </simple-bind>
    <uid-attribute>sAMAccountName</uid-attribute>
    <rdns>DC=corp,DC=example,DC=com</rdns>
    <directory-descent>true</directory-descent>
    <required-object-class>person</required-object-class>
</ldap>

Active Directory Considerations

Use sAMAccountName as the uid-attribute (the Windows login name)
Enable directory-descent if users are in multiple OUs
The service account needs read access to the directory
Use person or user as the required-object-class to filter results

OpenLDAP Configuration

Example for OpenLDAP

<ldap>
    <servers>
        <ldap-server>
            <host>ldap.example.org</host>
            <port>389</port>
        </ldap-server>
    </servers>
    <tls-mode>START_TLS</tls-mode>
    <simple-bind>
        <rdns>cn=admin</rdns>
        <userPassword>admin</userPassword>
    </simple-bind>
    <uid-attribute>uid</uid-attribute>
    <rdns>dc=example,dc=org</rdns>
    <directory-descent>true</directory-descent>
</ldap>

OpenLDAP Considerations

Use uid as the uid-attribute (standard for OpenLDAP)
The cn=admin account typically has full read access
Use inetOrgPerson as the required-object-class if needed

Troubleshooting

Authentication Fails

Problem: Users cannot authenticate even with correct credentials.

Solution:

Verify the service account credentials in <simple-bind> are correct
Check that the <rdns> (base DN) matches your LDAP structure
Test LDAP connectivity using ldapsearch: ldapsearch -H ldap://your-server -D "cn=admin,dc=example,dc=org" -w password -b "dc=example,dc=org"
Enable debug logging in HiveMQ Edge to see detailed error messages

TLS Connection Errors

Problem: Cannot connect to LDAP server with TLS enabled.

Solution:

Verify the LDAP server supports TLS on the specified port
Check that the truststore contains the correct CA certificate
Test the TLS connection: openssl s_client -connect ldap.example.com:636
For START_TLS, ensure port 389 is used, not 636

Directory Descent Issues

Problem: Directory descent mode cannot find users.

Solution:

Verify <directory-descent> is set to true
Ensure the service account has search permissions on the base DN
Check that the <rdns> (base DN) is set to a high enough level in the tree
Verify the <uid-attribute> matches your LDAP schema (e.g., uid vs sAMAccountName)

Service Account DN Construction

Problem: The service account cannot bind to LDAP.

Solution:

The service account DN is constructed by combining:

<simple-bind><rdns> + <rdns> (base DN)

Example:

<simple-bind>
    <rdns>uid=admin</rdns>
    <userPassword>hivemq</userPassword>
</simple-bind>
<rdns>ou=people,dc=example,dc=org</rdns>

Results in service account DN: uid=admin,ou=people,dc=example,dc=org

Ensure this matches an actual account in your LDAP directory.

User DN Construction (Direct Binding)

Problem: Users exist but authentication fails with direct binding.

Solution:

User DNs are constructed by combining:

<uid-attribute>={username} + <rdns> (base DN)

Example:

<uid-attribute>uid</uid-attribute>
<rdns>ou=people,dc=example,dc=org</rdns>

For username alice, the constructed DN is: uid=alice,ou=people,dc=example,dc=org

Verify your users are actually stored at this location in the LDAP tree. If users are in nested OUs, enable directory-descent.

Security Best Practices

Always use TLS in production: Use LDAPS or START_TLS to encrypt all LDAP traffic
Use a dedicated service account: Create a read-only service account specifically for HiveMQ Edge
Limit service account permissions: Grant only the minimum permissions needed (read access to user entries)
Rotate passwords regularly: Change service account passwords on a regular schedule
Monitor failed authentication attempts: Set up alerts for unusual authentication patterns
Use certificate validation: Configure a proper truststore with your organization’s CA certificates

Performance Considerations

Connection pooling: Increase <max-connections> for high-traffic deployments (recommended: 5-10)
Direct binding vs. Directory descent: Direct binding is faster but requires a flat LDAP structure
Timeout tuning: Adjust <search-timeout-seconds> and <response-timeout-millis> based on your LDAP server performance
Multiple servers: Configure multiple LDAP servers for load distribution and failover
Network latency: Place HiveMQ Edge close to your LDAP servers to minimize network latency

Example: Complete Production Configuration

<admin-api>
    <enabled>true</enabled>
    <listeners>
        <http-listener>
            <port>8080</port>
            <bind-address>0.0.0.0</bind-address>
        </http-listener>
    </listeners>
    <ldap>
        <!-- Multiple servers for high availability -->
        <servers>
            <ldap-server>
                <host>ldap1.corp.example.com</host>
                <port>636</port>
            </ldap-server>
            <ldap-server>
                <host>ldap2.corp.example.com</host>
                <port>636</port>
            </ldap-server>
        </servers>

        <!-- LDAPS for security -->
        <tls-mode>LDAPS</tls-mode>
        <tls>
            <truststore-path>/opt/hivemq/conf/truststore.jks</truststore-path>
            <truststore-password>changeit</truststore-password>
            <truststore-type>JKS</truststore-type>
        </tls>

        <!-- Service account credentials -->
        <simple-bind>
            <rdns>CN=HiveMQ Service,OU=Service Accounts</rdns>
            <userPassword>SecureServiceAccountPassword</userPassword>
        </simple-bind>

        <!-- Active Directory configuration -->
        <uid-attribute>sAMAccountName</uid-attribute>
        <rdns>DC=corp,DC=example,DC=com</rdns>
        <directory-descent>true</directory-descent>
        <required-object-class>person</required-object-class>

        <!-- Performance tuning -->
        <max-connections>10</max-connections>
        <connect-timeout-millis>5000</connect-timeout-millis>
        <response-timeout-millis>10000</response-timeout-millis>
        <search-timeout-seconds>10</search-timeout-seconds>
    </ldap>
</admin-api>

Security Log for LDAP Authentication

For LDAP we support logging successful and unsuccessful authentication attempts. The log will be in the file logs/security.log.

Testing Security Configuration

You can test authentication using the Admin API directly:

curl -X POST http://localhost:8080/api/v1/auth/authenticate \
  -H "Content-Type: application/json" \
  -d '{"userName":"alice","password":"user-password"}'

A successful authentication returns a JWT bearer token:

{
  "token": "eyJraWQiOiIwMDAwMSIsImFsZyI6IlJTMjU2In0..."
}

An unsuccessful authentication returns:

{
  "type": "Unauthorized",
  "title": "Unauthorized",
  "detail": "Unauthorized",
  "status": 401,
  "errors": [{
    "detail": "Invalid username and/or password"
  }]
}

The HiveMQ Edge administrative user interface supports the configuration of a pre-login notice that users must acknowledge before accessing the system. This feature allows administrators to display a customizable notice dialog with a title, message, and optional consent confirmation. When consent is set, users must explicitly accept the terms presented in the notice to proceed with the login process.

The pre-login notice can be configured through the pre-login-notice element.

Example configuration to add pre login notice

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <admin-api>
        <pre-login-notice>
           <enabled>true</enabled>
           <title>Notice (Area 12, Munich)</title>
           <message>User, please note you’re accessing the HiveMQ Edge instance that collects data for Area 12, Munich.  Please ensure you’re making changes to the correct instance, to continue log in check ‘Proceed’ and click ‘Proceed to sign in’.</message>
           <consent>Proceed</consent>
        </pre-login-notice>
    </admin-api>
</hivemq>

Using The HiveMQ Edge API

The HiveMQ Edge API is generated from JAX-RS compliant web service definitions based on the OpenAPI specification. The latest version of the specification document can be generated from the source repository using the supplied gradle task:

./gradlew :openApiSpec

You can also refer to the version-controlled HiveMQ Edge Open API document.

The HiveMQ Edge API provides functionality to control the addition, removal, modification, and runtime control of MQTT bridges and protocol adapters. The API also gives you the ability to set up and modify Unified Namespace (UNS) configurations.

For a list of all the available services, see HiveMQ Edge Open API.

HiveMQ Edge REST API