Book a consultation

HiveMQ Extensions and Data Hub: The Catalogue and How It Fails

HiveMQ Enterprise Security Extension: Realms, Roles and Topic ACLs

The HiveMQ Enterprise Security Extension explained: realms, pipelines, roles and topic permissions, the Sparkplug STATE pitfall, and where it gets hard.

Vladimir Romanov


The HiveMQ Enterprise Security Extension (ESE) is the commercial component that decides who may connect to a HiveMQ broker and what each client may publish and subscribe to. The question for a plant team is what to design before switching it on, because the extension is easy to enable and hard to retrofit across hundreds of gateways. This page covers realms, pipelines, roles and permissions, a Sparkplug pitfall that a community thread documents, and where it gets hard. It is current as of November 2026 and built from HiveMQ’s documentation; we read the 4.9 version of the long concepts page, which is older than the current documentation.

It sits under Extensions and Data Hub in the HiveMQ technology hub. Its sibling for data movement is the Kafka extension.

How the HiveMQ Enterprise Security Extension works

Realms connect the broker to a source of identity or permissions. HiveMQ’s documentation describes a realm as an abstract connection to an external source: SQL, JWT, LDAP, File or OAuth, each with a unique name. HiveMQ’s current documentation also lists an OIDC realm, and the 4.9 concepts page lists Microsoft Active Directory Domain Services among compatible LDAP servers. HiveMQ’s product page lists role-based access control for the Control Center. The external services must be available when the extension starts.

Pipelines carry a client through four stages: authentication preprocessing, authentication, authorisation preprocessing and authorisation. A pipeline attaches to a broker listener. A pipeline for ALL listeners is the fallback, and with no match and no fallback the connection is rejected. That is how you give a plant-floor listener a different process from the one a cloud bridge uses.

A client passing authentication, authorisation and a topic permission check A client connects to a listener. The pipeline sends it to an authentication realm, which verifies identity and can set a role key. An authorisation realm then looks up the role's permissions. Each publish or subscribe is checked against a topic permission with activity, QoS and retain fields. Failure at authentication rejects the connection. A request with no permission is denied. MQTT client on a listener Authentication realm: who are you Authorisation realm: role to rules Topic permission filter, activity, QoS may set a role key checked per publish or subscribe fail: connection rejected no permission: request denied Authentication and authorisation may use different realms. Reload applies to new connections only.
Identity and permission are separate steps, and may come from separate systems. Most field problems sit in the last box, where role and topic design meet.

Authentication managers verify identity using variables. By default the MQTT username and password fill the key and secret. They can also set authorisation variables such as a role key. Authorisation managers use those variables to look up permissions.

Permissions belong on roles. HiveMQ’s documentation recommends roles over per-user permissions, for easier management and better performance. A file-based permission has a topic filter (wildcards allowed), an activity (PUBLISH, SUBSCRIBE or ALL), a qos (ZERO, ONE, TWO, combinations or ALL) and a retain setting (NOT_RETAINED by default, RETAINED or ALL). topic, qos and activity are mandatory, and a permission missing one is ignored. Placeholders such as ${mqtt-clientid} can put the client’s own identity in the topic, so one rule can say each client publishes only under its own name.

Brass combination lock resting on a keyboard and gold chip cards
A lock is only as useful as the rules it enforces: the permissions are the work.

Realm choices for a plant

RealmTypical sourceFits whenWatch for
FileAn XML file on the brokerA small site or a lab with few identitiesManual edits across a cluster; no central audit
SQLA database tableDevice credentials managed by a provisioning toolThe database becomes a dependency at start
LDAPActive Directory or another directoryControl Center users and people-owned clientsService accounts for machines; directory reachability from the plant network
JWT or OAuth (including OIDC)An identity providerCloud services, short-lived tokens, Microsoft Entra IDToken lifetime against long-lived PLC connections

HiveMQ’s 4.57 release (3 November 2026) added PEM certificate support to SQL, LDAP, JWT, OAuth and OIDC realms. HiveMQ’s pricing page states Enterprise Extensions are included in every self-managed plan, as listed on 20 November 2026; see editions and pricing. The open-source File RBAC extension is the lighter alternative HiveMQ lists in its catalogue.

The Sparkplug STATE permission pitfall

A role for Sparkplug needs both STATE/# and spBv1.0/STATE/#. This comes from a HiveMQ community thread of 14 and 15 January 2025, also cited from an Inductive Automation forum thread. A user could publish Sparkplug data only with the admin role. The reported fix was to permit the legacy topic STATE/# in addition to spBv1.0/STATE/#. The thread is a user report, not HiveMQ guidance, and we have not reproduced it.

We read it this way: a Sparkplug 3.0 primary host uses the spBv1.0/STATE/ form, but some clients still touch the legacy STATE/ form, and a least-privilege role written only from the specification denies one of them. The Sparkplug mechanics are in Sparkplug on HiveMQ; for the standard itself see MQTT and Sparkplug B.

An illustrative role design

This scenario is illustrative, not a recommended standard. A plant has three kinds of client: a PLC gateway per line, an Ignition gateway acting as a Sparkplug host, and a cloud bridge. In our view a workable first draft is three roles.

  • line-gateway: PUBLISH on plant1/${mqtt-clientid}/# only, so each gateway can write under its own name and nowhere else, with SUBSCRIBE on its own command topic. Nothing on #.
  • sparkplug-host: SUBSCRIBE on spBv1.0/#, PUBLISH on spBv1.0/STATE/# and on the legacy STATE/# form, with retain set to RETAINED for the STATE topics, because a host announces its status as a retained message.
  • cloud-bridge: SUBSCRIBE on the subtree it exports, and no publish right toward the plant unless a documented command path needs one.

The placeholder syntax is from HiveMQ’s documentation, which says substitution happens at the end of the authorisation step and byte variables cannot be substituted. The point of the exercise is the review: each role fits on one page, each line names a reason, and a person from controls can read it.

What to design before enabling it

  1. Identity per device class. Decide what a PLC gateway, an Ignition gateway, a historian and a cloud bridge each authenticate with, and who rotates it.
  2. Roles from the topic tree. Write the role list against your Unified Namespace topic structure, not the other way round.
  3. Listener per trust zone. Use separate listeners and pipelines for plant-floor clients and cloud clients.
  4. Wildcard policy. Decide who may subscribe to #. HiveMQ also lists an open-source Deny Root Wildcard extension for this.
  5. A deny test suite. Test what must fail, not only what works.

Where it gets hard

Role sprawl. Per-device exceptions pile up in the permission file until nobody can say what a role grants. Review every role against a written reason once a year, and delete the ones that have none.

Undocumented edges. In the pages we read, HiveMQ does not say how multiple matching permissions combine or what happens when none match. Test both on your version.

Revocation is not immediate. Permission changes do not affect connected clients. Long-lived MQTT sessions mean a removed right can persist until reconnect.

Startup dependencies. Realms must be reachable when the extension starts, so an LDAP or database outage during a restart can keep a broker from enforcing the policy you expect. Place the directory where the plant can reach it during a WAN loss.

Security is more than the broker. A role file does not replace segmentation. See OT network segmentation, IEC 62443 and our OT network assessment. We found no HiveMQ IEC 62443 certification statement for the broker.

Frequently asked questions

What is the HiveMQ Enterprise Security Extension?

It is a commercial HiveMQ Enterprise Extension that handles authentication and authorisation for MQTT clients and Control Center users. HiveMQ's documentation describes realms (SQL, JWT, LDAP, File and OAuth) connected through pipelines, with permissions assigned to roles. HiveMQ's pricing page states Enterprise Extensions are included in every self-managed plan, as listed on 20 November 2026.

Which realm types does the Enterprise Security Extension support?

HiveMQ's documentation lists SQL, JWT, LDAP, File and OAuth realms, with a separate OIDC realm in the current documentation. HiveMQ's 4.57 release of 3 November 2026 added PEM certificate support for the SQL, LDAP, JWT, OAuth and OIDC realms. The 4.9 documentation shows authentication from an OAuth realm and authorisation from a file realm.

Why can my Sparkplug client only publish with the admin role?

A January 2025 HiveMQ community thread reports exactly this. The reported fix was to give the role permission for the legacy topic STATE/# as well as spBv1.0/STATE/#. We have not reproduced it. If a Sparkplug publisher such as an Ignition MQTT Transmission client fails with a narrow role, check the STATE topics first.

Do permission changes apply to clients that are already connected?

Per HiveMQ's documentation, no. The authorisation file is monitored and hot-reloaded, and an invalid new file is rejected while the previous configuration stays active, but a permission change affects only clients that connect afterwards. To revoke access from a connected client, plan to disconnect it.

What happens when no permission matches a request?

The pages of the documentation we read do not say, and they do not describe how multiple matching permissions are combined. Do not assume. Write a test that publishes and subscribes with a role that should be denied, run it against your version, and keep it as a regression test.

References and further reading

  1. HiveMQ Enterprise Security Extension: concepts · HiveMQRealms, pipelines, roles, permission fields and placeholders. We read the 4.9 version of the page, an older docs version than the current latest; re-check it against the version you run.
  2. HiveMQ Enterprise Security Extension documentation · HiveMQ
  3. HiveMQ extensions catalogue · HiveMQThe extension listed as Enterprise, with its realm types.
  4. What's new in HiveMQ 4.57 · HiveMQRelease of 3 November 2026: PEM certificate support in realms.
  5. Sparkplug RBAC issues (HiveMQ community) · HiveMQ CommunityJanuary 2025 thread on the STATE topic permission. A user report, not an official statement.
  6. HiveMQ pricing · HiveMQ
  7. Authenticating MQTT devices with HiveMQ and Microsoft Entra · HiveMQ

← Extensions and Data Hub

Have a project that needs technical ownership?

Send us the situation. If it is not something we should take on, we will say so.

The Plant-Side Brief

The weekly brief for the people who own a plant’s control systems.

One email every Wednesday for engineering and operations leaders responsible for controls, SCADA, MES and OT networks. Skim the top in two minutes; read the Deep Dive when you have fifteen.

  • One modernization problem, worked through to cost, risk and a schedule you can defend. The Deep Dive.
  • End-of-support dates before they reach your plant Windows, servers, controllers and HMI software. Lifecycle Watch.
  • A checklist your engineers can run that week not a framework to admire. Field Kit.
  • Every number sourced, no vendor agenda we are paid by plants, never by vendors.