How to Add Team Members to the HiveMQ Control Center

By default, HiveMQ Broker includes a single default user (admin) for accessing the Control Center. However, in team environments, it’s essential to provide each team member with individual credentials—or even fine-grained access permissions.

This guide explains how to:

Add users with individual passwords via config.xml
Enable role-based access control (RBAC) using the HiveMQ Enterprise Security Extension (ESE)

Instructions

🔐 Option 1: Add Team Members via `config.xml` (Default HiveMQ)

Use this option if you want every user to have their own username and password, but do not require role-based access control.

✅ Benefits

Simple to configure
Works out-of-the-box
No license required

⚙️ Configuration Example

Edit your config.xml (typically mounted or located in /opt/hivemq/conf/config.xml):

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <control-center>
        <users>
            <user>
                <name>alice</name>
                <password>f8c91b69804354d5ef49151c226f9533e74c6602</password>
            </user>
            <user>
                <name>bob</name>
                <password>3f57b5c968c91d036bc9a920484fe903664ed621</password>
            </user>
        </users>
    </control-center>
</hivemq>

⚠️ All users configured this way will have full access to the Control Center.

After saving the file, restart the HiveMQ broker to apply the changes.

🛡 Option 2: Role-Based Access Control with ESE

If you want fine-grained access control (e.g., read-only access for some users, admin for others), use the HiveMQ Enterprise Security Extension.

🧪 Trial Mode

ESE requires a license
You can test it in trial mode for 5 hours without a license

🔁 What Changes?

Users in config.xml are ignored
Users, passwords, and permissions are defined in ESE configuration files

📁 Step 1: Configure the ESE Main Config

Edit:
/opt/hivemq/extensions/hivemq-security-extension/conf/config.xml

<?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>
        <file-realm>
            <name>file-realm</name>
            <enabled>true</enabled>
            <configuration>
                <file-path>conf/ese-file-realm.xml</file-path>
            </configuration>
        </file-realm>
    </realms>

    <pipelines>
        <control-center-pipeline>
            <file-authentication-manager>
                <realm>file-realm</realm>
            </file-authentication-manager>
            <file-authorization-manager>
                <realm>file-realm</realm>
            </file-authorization-manager>
        </control-center-pipeline>
    </pipelines>
</enterprise-security-extension>

📁 Step 2: Define Users and Roles in `ese-file-realm.xml`

Edit:
/opt/hivemq/extensions/hivemq-security-extension/conf/ese-file-realm.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ese-file-realm xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:noNamespaceSchemaLocation="ese-file-realm.xsd">

    <control-center>
        <users>
            <user>
                <name>cc-user-1</name>
                <password>cc-password-1</password>
                <permissions>
                    <permission>HIVEMQ_SUPER_ADMIN</permission>
                </permissions>
            </user>

            <user>
                <name>cc-user-2</name>
                <password encoding="Base64">XW5ESC/iKdtYWIDpcgeFOIXhjA9reoCBzNcFm/SQhWk=</password>
                <iterations>10</iterations>
                <salt>cc-password-2-salt</salt>
                <algorithm>PKCS5S2</algorithm>
                <roles>
                    <role>topics</role>
                    <role>shared-subscriptions</role>
                </roles>
            </user>
        </users>

        <roles>
            <role>
                <id>topics</id>
                <permissions>
                    <permission>HIVEMQ_VIEW_DATA_TOPIC</permission>
                </permissions>
            </role>

            <role>
                <id>shared-subscriptions</id>
                <permissions>
                    <permission>HIVEMQ_VIEW_DATA_TOPIC</permission>
                    <permission>HIVEMQ_VIEW_DATA_SUBSCRIPTION</permission>
                    <permission>HIVEMQ_VIEW_PAGE_SHARED_SUBSCRIPTION_DETAIL</permission>
                    <permission>HIVEMQ_VIEW_PAGE_SHARED_SUBSCRIPTION_LIST</permission>
                </permissions>
            </role>
        </roles>
    </control-center>

</ese-file-realm>

🔗 Full list of permissions:
HiveMQ Control Center Permissions Reference

🔄 Step 3: Restart the Extension

To apply your changes, restart the HiveMQ Enterprise Security Extension.

🧩 Summary

Feature	`config.xml` Only	ESE with RBAC

Feature	`config.xml` Only	ESE with RBAC
Individual Credentials	✅	✅
Fine-grained Permissions	❌	✅
Password Hashing	Sha256	✅
Trial without License	✅ (default)	✅ (5 hrs)
Config Location	`/opt/hivemq/config.xml`	`/opt/hivemq/extensions/hivemq-security-extension/conf/`

Need help with deployment or ESE configuration?
👉 Contact HiveMQ Support