MQTT
The MQTT component is the central communication hub through which all MQTT communications between components happen.
ACS MQTT Component
Overview
Similar to the Data Warehouse Component, Factory+ does not prescribe a particular specification for the MQTT Component; it only necessitates that any chosen solution be MQTT 3.1 compatible. There are however a few requirements of any chosen MQTT broker that must be satisfied to ensure compatibility with Factory+.
Authentication & Authorisation
Any chosen MQTT broker must be able to authenticate users via Kerberos and enforce fine-grained access control for topic management via rules from the Authorisation Component.
If you are using HiveMQ, our Factory+ plugin will handle this for you.
Well-Known UUIDs
These well-known UUIDs are part of the core framework and all MUST to be registered with the Configuration Store component under the appropriate classes.
Identity
Permission Groups
Any UUIDs created representing MQTT permissions MUST be added to this group in the Authorisation Component, otherwise the MQTT component will not be able to see the ACEs.
Permissions
Global
{
"spBv1.0/#": "s"
}
{
"spBv1.0/#": "rs"
}
{
"spBv1.0/+/NCMD/+": "w",
"spBv1.0/+/DCMD/+/+": "w"
}
{
"STATE/+": "rs"
}
{
"spBv1.0/%g/DCMD/%n/#": "rs",
"spBv1.0/%g/DDATA/%n/+": "w",
"spBv1.0/%g/DBIRTH/%n/+": "w",
"spBv1.0/%g/DDEATH/%n/+": "w"
}
Group
{
"STATE/%g": "w"
}
{
"spBv1.0/%g/#": "w"
}
{
"spBv1.0/%g/#": "rs"
}
{
"spBv1.0/%g/NCMD/+": "w",
"spBv1.0/%g/DCMD/+/+": "w"
}
Node
{
"spBv1.0/%g/NDATA/%n": "w",
"spBv1.0/%g/NBIRTH/%n": "w",
"spBv1.0/%g/NCMD/%n/#": "rs",
"spBv1.0/%g/NDEATH/%n": "w"
}
{
"spBv1.0/%g/NDATA/%n": "rs",
"spBv1.0/DDEATH/%n/+": "rs",
"spBv1.0/%g/NBIRTH/%n": "rs",
"spBv1.0/%g/NDEATH/%n": "rs",
"spBv1.0/%g/DDATA/%n/+": "rs",
"spBv1.0/%g/DBIRTH/%n/+": "rs"
}
{
"STATE/%n": "w"
}
Device
{
"spBv1.0/%g/DCMD/%n/#": "rs",
"spBv1.0/%g/DDATA/%n/+": "w",
"spBv1.0/%g/DBIRTH/%n/+": "w",
"spBv1.0/%g/DDEATH/%n/+": "w"
}
Roles
The Edge Node role MUST be granted to all principals used for edge agents and MUST have the following Permissions:
| Permission | UUID |
|---|---|
| MQTT: Subscribe & Read All States | 8790cf3d-b793-423c-b373-8cfcf9f63529 |
| MQTT: Participate as Node | a1314953-8226-44f4-8a3e-e87b09310579 |
| MQTT: Represent Devices | e82456b3-a7d9-4971-9d8c-fd0be4545ab4 |
Applications
UUIDs representing MQTT permissions need to have a Configuration Store entry of this type. This entry serves as a template for the MQTT permissions granted when the given permission UUID is granted in the Authorisation Component.
The entry MUST be a JSON object. Keys represent MQTT topics; values represent the access granted to that topic. Values MUST be strings, as defined below.
Topic names support the normal MQTT + and # wildcards. In addition,
if any of the percent sequences below appear in the topic name, the
target of the relevant ACE will be looked up under the 'Sparkplug
Address' application below. The percent sequence will be expanded to the
relevant property of the entry returned. If there is no such entry the
topic will be ignored (no permission will be granted).
| Sequence | Property |
|---|---|
%g | group_id |
%n | node_id |
The access granted is specified as a string containing one or more of the characters below.
| Access | Meaning |
|---|---|
r | Read data published to the given topic. |
w | Publish to the given topic. |
s | Allow subscription to the given topic. |
The s code is intended for implementations that distinguish between
'subscribe' and 'read' permissions. A client granted s permission
SHOULD be allowed to request subscription to the given topic, but
MUST NOT be sent packets for that topic unless r permission is
also granted.
Not all implementations will implement the s permission.
Implementations that do not MAY refuse subscription requests for
topics that do not have r permission. Currently the ACS HiveMQ plugin
does not implement s.