RunMQTT separates a device identity from the topic rules assigned to it. This keeps credentials narrow and makes access reviews easier as a fleet grows.
Policy templates
A template represents one device role. Examples include a read-only dashboard, a field sensor, a gateway, or a command service. Devices created from the same template receive the same topic policy set without sharing credentials.
Each policy contains:
- a topic filter;
- a permission: publish, subscribe, or both;
- an optional description for reviewers.
Topic filter design
Use stable, hierarchical topics that describe ownership before payload type:
tenants/acme/sites/shanghai/devices/sensor-42/telemetry
tenants/acme/sites/shanghai/devices/sensor-42/state
tenants/acme/sites/shanghai/devices/sensor-42/commands
The + wildcard matches one topic level. The # wildcard matches the remaining tree and should be reserved for trusted gateway or backend identities.
Prefer separate filters for telemetry and commands. A sensor that publishes telemetry usually does not need permission to publish commands, and a dashboard that subscribes to state rarely needs device-level publish access.
Device credentials
Every device has its own generated connection credentials. A credential belongs to one broker and one policy template. Deleting or rotating a device identity does not change the account login or other devices.
Use a different client ID for each concurrent connection, even when testing the same device secret from multiple clients. Broker connection accounting treats simultaneous client IDs as separate connections.
Safe rollout pattern
- Create the template with the minimum topic set.
- Create one test device from that template.
- Verify permitted publish and subscribe operations.
- Verify that an out-of-scope topic is rejected.
- Add production devices only after the policy behaves as expected.
Changes to a shared template can affect every attached device. Review wildcard changes with the same care as application authorization changes.