Abstract

Access Control Lists (ACLs) control what topics a given username/password pair is allowed to publish and subscribe on. ACLs should be designed with a 'principal of least privilege' model while also considering device management and maintenance.  For example gateways and devices in the field should be limited to publishing and subscribing only on the topics for which they should be expected to.  The same should be true of 'consumer' applications that will be either sending commands to devices in the field or consuming data coming from those devices.


It is important to note that a username is not limited to a single MQTT client. You will need to create separate users for each publishing and/or subscribing client, such as MQTT Transmission and MQTT Engine, if each one has a different Read/Write requirement.  


If you are new to MQTT topics, the Eclipse Foundation's Paho project provides good information here on the basics of wildcards.

For subscriptions, two wildcard characters are supported:

Definition

ACLs are defined by the following format: [R|W|RW] topic where:

R = Read or 'subscribe' privileges

W = Write or 'publish' privileges

RW = Read and Write (subscribe and publish) privileges

topic = The topic or wildcard topic representing the scope of the privilege


RW #

R #

W #


ACLs are case sensitive. This means that setting a users ACL to R spbv1.0 will not allow a user to subscribe to spBv1.0/# topics

Examples for MQTT Transmission ACLs

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

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

W device_one/temp/#, R state/#


When creating an Access Control List (ACL) for an MQTT Transmission client:

  • There must be R privilege's for the Sparkplug NCMD message
    • This is used by MQTT Transmission to subscribe to the Sparkplug Rebirth request
  • There must be R privilege's for the Sparkplug NDEATH message
    • This is used by MQTT Transmission to subscribe to its own STATE message

Examples For MQTT Engine ACLs

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

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

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

When creating an Access Control List (ACL) for an MQTT Engine client:

  • There must be RW privilege's for the MQTT Sparkplug™ B STATE message
  • There must be W privilege's for the Sparkplug NCMD message
    • This is used by MQTT Engine to publish the Sparkplug Rebirth request
  • The MQTT Engine SparkplugB Namespace Filter must be configured for the same Group or Group/EdgeNode combination used in the ACL entry


Client Connection Issues

Subscribe on topic not allowed by the ACL

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

With the following ACL, the Transmission client is not able to subscribe to the NCMD and DCMD topics

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


Publish on a topic not allowed by the ACL

If MQTT Engine or MQTT Transmission client attempts to publish on a topic that is not allowed by the ACL for that client, the connection will be forcefully closed and the client will attempt to reconnect.

With the following ACL, the Transmission client can publish the NBIRTH for PLC 1 but is not able to publish the DBIRTH for edge node device D1

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


With the following ACL, the MQTT Engine client is not able to send a rebirth request

R #, W spBv1.0/STATE/MyPrimaryHost


Connect using a LWT not allowed by the ACL

With the following ACL, the Transmission client My MQTT Group/PLC 1 is able to connect and subscribe but client My MQTT Group/PLC 2 is not authorized to connect with the LWT of spBv1.0/My MQTT Group/NDEATH/PLC 2.

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



Additional Resources