Prerequisites
- Knowledge of Ignition and Module installation process: Cirrus Link Module Installation
- Have Ignition 8.0.16 or greater installed
- Have MQTT Distributor 4.0.10 or later installed
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.
...
- A '#' character represents a complete sub-tree of the hierarchy and thus must be the last character in a subscription topic string, such as SENSOR/#. This will match any topic starting with SENSOR/, such as SENSOR/1/TEMP and SENSOR/2/HUMIDITY.
- A '+' character represents a single level of the hierarchy and is used between delimiters. For example, SENSOR/+/TEMP will match SENSOR/1/TEMP and SENSOR/2/TEMP.
Definition
ACLs are defined by the following format: [R|W|RW] topic where:
...
topic = The topic or wildcard topic representing the scope of the privilege
Examples
RW #
- This allows clients connecting using this username/password to publish and subscribe on any topic
...
- This allows clients connecting using this username/password to publish on any topic but not subscribe on any topics
Warning |
---|
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/#
- This allows clients connecting using this username/password to publish on spBv1.0/GroupID/+/EdgeNodeID/# topic
R STATE/PrimaryHostID, R spBv1.0/GroupID/+/EdgeNodeIDSTATE/PrimaryHostID, R spBv1.0/GroupID/#
- This allows clients connecting using this username/password to subscribe on both STATE/PrimaryHostID the legacy Sparkplug STATE, Sparkplug STATE and spBv1.0/GroupID/+/EdgeNodeID/# topics. GroupID# topics
W device_one/temp/#, R state/#
- This allows clients connecting using this username/password to publish on device_one/temp/# and subscribe on state/# topicslegacy STATE topics
Note |
---|
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
- This allows Engine clients connecting using this username/password to subscribe and publish on the spBv1.0/STATE/PrimaryHostID Sparkplug STATE and spBv1.0/GroupID/+/EdgeNodeID/# topics
- You must also configure the SparkplugB Namespace Filter for this same Group or Group/EdgeNode combination for this topic.
RW STATE/PrimaryHostID, RW spBv1.0/STATE/PrimaryHostID, RW R spBv1.0/GroupID/+/EdgeNodeID/#
- This allows clients connecting using this username/password to subscribe and publish on both the legacy Sparkplug STATE and Sparkplug STATE topics and subscribe on the spBv1.0/GroupID/# topic
RW spBv1.0/STATE/PrimaryHostID, W spBv1.0/GroupID/
...
NCMD/#, R spBv1.0/GroupID/#
- This allows clients connecting using this username/password to subscribe on both the Sparkplug STATE and spBv1.0/GroupID/+/EdgeNodeID/# topics . and publish on the spBv1.0/GroupID/NCMD/#
Notewarning |
---|
When creating an Access Control List (ACL) for an MQTT Engine client, there : - There must be RW privilege's for the MQTT Sparkplug™ B STATE message
- Sparkplug v3.0.0 state message topic: spBv1.0/STATE/primary_host_
id |
Warning |
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- 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
Code Block |
---|
|
R spBv1.0/My MQTT Group/NDEATH/PLC 1, W # |
Image Added
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
Code Block |
---|
|
R #, W spBv1.0/My MQTT Group/+/PLC 1 |
Image Added
With the following ACL, the MQTT Engine client is not able to send a rebirth request
Code Block |
---|
|
R #, W spBv1.0/STATE/MyPrimaryHost |
Image Added
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.
Code Block |
---|
R #, W spBv1.0/My MQTT Group/+/PLC 1/# |
Image Added
Additional Resources
- Inductive Automation's Ignition download with free trial
- Cirrus Link Solutions Modules for Ignition
- Questions about this tutorial?
- Sales questions
- About Cirrus Link
...