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>

Access to the HiveMQ Edge Admin UI and Admin REST API is controlled by role-based access control (RBAC).

HiveMQ Edge provides three roles:

user
super
admin

Each user is assigned one or more roles. When a user belongs to multiple roles, the highest-privilege role determines the effective access level.

Table 1. Roles and permissions
Permission	No Role	`user`	`super`
Front page / login
Read Edge configuration (adapters, bridges, mappings, etc.)	–
Edit Edge configuration (create/update/delete adapters, bridges, mappings, etc.)	–	–	–
Read Data Hub configuration (policies, schemas, scripts)	-
Edit Data Hub configuration (create/update/delete policies, schemas, scripts)	–	–	–
Start, stop, and restart protocol adapters	–	–
Read access to REST API (GET)	-
Write access to REST API (POST, PUT)	-	-	-
Authentication REST API (get, refresh, validate Auth token)
Liveliness and readiness REST API

Role-based access control is fully enforced in the HiveMQ Edge backend. However, the frontend UI does not yet completely reflect these restrictions. Currently, users with read-only roles (user, super) can interact with edit controls (for example, forms to create tags or mappings), but the backend rejects the write requests. However when the frontend tries to store this in the backend, the backend will fail this write request. No data is modified without the correct permissions. A view-only mode will be implemented in a future release to ensure frontend permissions accurately mirror backend access control.

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

LDAP 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</uid-attribute>
<rdns>ou=people</rdns>
<base-dn>dc=example,dc=org</base-dn>

the constructed DN is: 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 (Direct binding adds 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.

LDAP Authorization (Role Assignment)

After a user is authenticated, HiveMQ Edge can execute LDAP queries to assign roles to that user. Each query checks group membership in the LDAP directory. If a query returns at least one result, the user is assigned the corresponding role. assign roles to the user. This happens after the authentication has resolved the user DN as described above and the user has been authenticated with their password.

The queries have the form (&(entryDN={userDn})(memberOf=CN=EdgeAdmins,OU=Groups,DC=Example,DC=Org)). Edge executes the queries after the user has been authenticated and assigns the corresponding role to the user for any query that returns at least one result.

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,ou=people</rdns>
            <userPassword>secret</userPassword>
        </simple-bind>
        <uid-attribute>uid</uid-attribute>
        <rdns>ou=people</rdns>
        <base-dn>dc=example,dc=org</base-dn>
    </ldap>
</admin-api>

Configuration Example with User Roles

Role assignment is configured using <user-roles>. Each <user-role> entry maps a role name to an LDAP query. HiveMQ Edge executes each query after authentication. If a query returns at least one result, the user is assigned the corresponding role.

<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,ou=people</rdns>
            <userPassword>secret</userPassword>
        </simple-bind>
        <uid-attribute>uid</uid-attribute>
        <rdns>ou=people</rdns>
        <base-dn>dc=example,dc=org</base-dn>
        <user-roles>
            <user-role>
                <role>admin</role>
                <query>(&amp;(entryDN={userDn})(memberOf=CN=EdgeAdmins,ou=groups,dc=example,dc=org))</query>
            </user-role>
            <user-role>
                <role>user</role>
                <query>(&amp;(entryDN={userDn})(memberOf=CN=EdgeUsers,ou=groups,dc=example,dc=org))</query>
            </user-role>
        </user-roles>
    </ldap>
</admin-api>

The queries in this example search the user entry for a memberOf attribute matching the target group. This requires the memberOf overlay, which is enabled by default in OpenLDAP and most other LDAP servers.

The ampersand &, which denotes the logical AND in LDAP query syntax, must be escaped as & in the XML configuration file.

If your LDAP server does not support the memberOf overlay (for example, some lightweight LDAP implementations), search the group entry for a member or uniqueMember attribute instead: (&(objectClass=groupOfNames)(cn=administrators(member={userDn})). Again, remember to escape & as & in XML.

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>
ERWIN
    <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,ou=people</rdns>
        <userPassword>secret</userPassword>
    </simple-bind>
    <uid-attribute>uid</uid-attribute>
    <base-dn>dc=example,dc=org</base-dn>
    <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,ou=people</rdns>
        <userPassword>secret</userPassword>
    </simple-bind>
    <uid-attribute>uid</uid-attribute>
    <rdns>ou=people</rdns>
    <base-dn>dc=example,dc=org</base-dn>
</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	-	Relative DN used for user name construction or search
`<base-dn>`	No (but recommended)	-	Base DN for DN construction
`<directory-descent>`	No	`false`	Enable directory descent for hierarchical searches
`<required-object-class>`	No	-	Optional object class filter for search results
`<user-roles>`	No	-	List of user-role role-query pairs. If no user role-query pairs are specified, the user is assigned the `admin` role.
`<user-role>` (under user-roles)	No, can appear multiple times	-	One role-query pair.
`<role>` (under user-role)	Yes	-	The role `admin`, `super`, `user`
`<query>`(under user-role)	Yes	-	The query to execute. Such queries would take the form of `(&(entryDN={userDn})(memberOf=CN=EdgeAdmins,OU=Groups,DC=Example,DC=org))`, where `{userDn}` is replaced by the user’s DN. If the query is successful (returns at least one result), the user is assigned the role.
`<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

Relative DN used for user name construction or search

<base-dn>

No (but recommended)

Base DN for DN construction

<directory-descent>

false

Enable directory descent for hierarchical searches

<required-object-class>

Optional object class filter for search results

<user-roles>

List of user-role role-query pairs. If no user role-query pairs are specified, the user is assigned the admin role.

<user-role> (under user-roles)

No, can appear multiple times

One role-query pair.

<role> (under user-role)

Yes

The role admin, super, user

<query>(under user-role)

Yes

The query to execute. Such queries would take the form of (&(entryDN={userDn})(memberOf=CN=EdgeAdmins,OU=Groups,DC=Example,DC=org)), where {userDn} is replaced by the user’s DN. If the query is successful (returns at least one result), the user is assigned the role.

<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:
- User DN (direct binding) = <uid-attribute>={username},<rdns>,<base-dn>
- Search Root (directory descent) = <rdns>,<base-dn>
- Service Account DN = <simple-bind-rdns>,<base-dn>
However, if the <base-dn> is not present or empty, then the full DN for the service account is constructed relative to the <rdns> (from the ldap element) for backward compatibility reasons:
- Service Account DN = <simple-bind-rdns>,<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>
    <base-dn>DC=corp,DC=example,DC=com</base-dn>
    <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>
    <base-dn>dc=example,dc=org</base-dn>
    <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:

If <base-dn> is not empty:

<simple-bind><rdns> , <base-dn>

If <base-dn> is empty, then the <rdns> element from the <ldap> element is used:

<simple-bind><rdns> , <rdns> (from <ldap> element)

Example:

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

Results in service account DN: uid=admin,ou=admins,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</rdns>
<base-dn>dc=example,dc=org</base-dn>

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