Skip to main content
Modules for Ignition v8.1.x

ⓘ Access Control Lists (ACLs)

Access Control Lists (ACLs) define which MQTT topics a client can publish to and subscribe to when connecting to MQTT Distributor.

ACLs should follow the principle of least privilege. Each client should be granted access only to the topics required for its operation. Limiting topic access improves security and helps prevent unintended data access or modification.

For example:

  • MQTT Edge Nodes should only be allowed to publish and subscribe to their assigned Sparkplug topics.
  • MQTT Engine should only be granted access to the topics it consumes and any command topics it publishes to.
  • External applications should only be granted access to the topics required for monitoring or control.

❗ A single MQTT username can be used by multiple MQTT clients. However, if different clients require different permissions, create separate users and ACLs for each client.

MQTT Topic Wildcards​

ACLs support the standard MQTT topic wildcards.

Multi-Level Wildcard (#)​

The # wildcard matches all remaining levels in a topic hierarchy and must be the final character in the topic filter.

Single-Level Wildcard (+)​

The + wildcard matches exactly one level in a topic hierarchy.

For additional information about MQTT topics and wildcards, refer to the Eclipse Paho MQTT documentation.

ACL Format​

ACL entries use the following format:

[R|W|RW] <topic>

Where:

PermissionDescription
RRead access (subscribe)
WWrite access (publish)
RWRead and write access (subscribe and publish)

Examples​

Full Access​

RW #

Allows clients to publish and subscribe to all topics.

Subscribe Only​

R #

Allows clients to subscribe to all topics but cannot publish.

Publish Only​

W #

Allows clients to publish to all topics but cannot subscribe.

❗ ACLs are case-sensitive. For example, an ACL configured as R spbv1.0/# does not grant access to spBv1.0/#.

MQTT Transmission ACL Examples​

Publish Sparkplug Messages​

W spBv1.0/GroupID/+/EdgeNodeID/#

Allows a client to publish to Sparkplug topics matching the specified Group ID and Edge Node ID.

Subscribe to STATE Topics​

R STATE/PrimaryHostID
R spBv1.0/STATE/PrimaryHostID
R spBv1.0/GroupID/#

Allows a client to subscribe to both legacy Sparkplug STATE topics and Sparkplug B topics within the specified group.

Publish Device Data and Subscribe to STATE​

W device_one/temp/#
R state/#

Allows publishing to device temperature topics and subscribing to legacy STATE topics.

Required Permissions for MQTT Transmission​

When configuring ACLs for MQTT Transmission, the following permissions are required:

PermissionPurpose
Read (R) on NCMD topicsAllows Transmission to receive Sparkplug rebirth requests.
Read/Write (RW) on NDEATH topicsAllows Transmission to publish and subscribe to its own STATE-related messages.

MQTT Engine ACL Examples​

Full Sparkplug Access​

RW spBv1.0/GroupID/+/EdgeNodeID/#
RW spBv1.0/STATE/PrimaryHostID

Allows publishing and subscribing to Sparkplug B topics and STATE messages.

Subscribe to Sparkplug Data​

RW STATE/PrimaryHostID
RW spBv1.0/STATE/PrimaryHostID
R spBv1.0/GroupID/#

Allows access to legacy and current Sparkplug STATE topics while subscribing to all topics within a Sparkplug group.

Publish Rebirth Requests​

RW spBv1.0/STATE/PrimaryHostID
W spBv1.0/GroupID/NCMD/#
R spBv1.0/GroupID/#

Allows publishing Sparkplug rebirth requests while subscribing to Sparkplug data topics.

Required Permissions for MQTT Engine​

When configuring ACLs for MQTT Engine:

  • MQTT Engine must have read/write (RW) access to the Sparkplug STATE topic.
  • MQTT Engine must have write (W) access to NCMD topics to issue rebirth requests.
  • The MQTT Engine Sparkplug Namespace Filter must match the Group ID or Group ID/Edge Node combination defined in the ACL.

Supported STATE Topics​

Current Sparkplug B STATE topic:

spBv1.0/STATE/PrimaryHostID

Legacy Sparkplug STATE topic:

STATE/PrimaryHostID

For additional information, refer to the Sparkplug specification documentation regarding STATE topic changes.

Troubleshooting ACL Issues​

🔍 Subscription Not Authorized​

If MQTT Engine or MQTT Transmission attempts to subscribe to a topic that is not permitted by its ACL, the connection will fail and the client will not reconnect.

Example:

R spBv1.0/My MQTT Group/NDEATH/PLC 1
W #

In this example, the Transmission client cannot subscribe to the required NCMD and DCMD topics.

🔍 Publish Not Authorized​

If MQTT Engine or MQTT Transmission attempts to publish to a topic that is not permitted by its ACL, MQTT Distributor will close the connection and the client will attempt to reconnect.

Example:

R #
W spBv1.0/My MQTT Group/+/PLC 1

This ACL allows publishing for PLC 1 but prevents publishing device messages for child devices such as D1.

MQTT Engine rebirth requests can also fail if the NCMD topic is not permitted:

R #
W spBv1.0/STATE/MyPrimaryHost

🔍 Last Will and Testament (LWT) Not Authorized​

A client must have permission to publish its configured Last Will and Testament (LWT) topic. If the ACL does not permit publishing to the LWT topic, the client connection will be rejected.

Example:

R #
W spBv1.0/My MQTT Group/+/PLC 1/#

With this ACL, a client configured with an LWT topic of:

spBv1.0/My MQTT Group/NDEATH/PLC 2

is not authorized to connect because the ACL only permits publishing LWT messages for PLC 1.