Security model

TBMQ secures MQTT traffic in three layers: the transport a client connects over, the authentication that establishes who it is, and the authorization that bounds what it may do. Every connection passes through all three, in that order.

The layers are independent and composable, which is what makes the model worth understanding before you configure any of it: a broker on a trusted private network can reasonably run plain TCP with password authentication, while a public-facing one uses mutual TLS with per-topic rules and no stored passwords at all. Picking that combination is the job of this page — each layer’s own guide owns the configuration. For the concepts behind MQTT security in general, see the MQTT security guide.

A client reaches the broker through a listener. TBMQ offers four: MQTT over TCP and MQTT over WebSocket, each with an encrypted counterpart. The two plaintext listeners are enabled out of the box and the two encrypted ones ship disabled until you supply certificates — so a default broker will accept credentials in clear text, and hardening a deployment starts with turning that off.

TLS listeners support either direction of trust. With one-way TLS the client verifies the broker and the channel is encrypted, but the client still proves itself with credentials inside the CONNECT packet. With mutual TLS both sides present certificates, which is the foundation X.509 authentication is built on.

See MQTT listeners for the ports and per-listener settings, MQTTS for certificates and mutual TLS, and HTTPS for the management interface, which is secured separately from MQTT traffic.

Authentication happens during the CONNECT handshake and is implemented as a set of providers, each enabled and configured on its own:

• Basic — client ID, username and password taken from the CONNECT packet.
• X.509 — the certificate the client presented during a mutual-TLS handshake.
• JWT — a signed token in the password field, verified against a key or a JWKS endpoint instead of stored credentials.
• SCRAM — a challenge–response exchange that never puts the password on the wire. MQTT 5.0 only.
• HTTP — the decision is delegated to an external service you operate.

Enabled providers are tried in a configurable order, and the first one to authenticate the client wins. A provider that cannot evaluate the credentials at all is skipped so the next one gets a turn; a provider that actively rejects the client ends the attempt there. SCRAM is the exception: the broker handles it directly per the MQTT 5.0 specification, outside that order. A client can also be refused before authentication runs at all, by blocking its client ID, username or IP address.

An authenticated client is still confined to the topics its identity allows. Authorization is expressed as regular expressions attached to the credentials — separate lists for publishing and for subscribing — and a topic is permitted only if it matches one of those patterns in full. A per-device credential typically permits publishing to that device’s own telemetry subtree and subscribing to its own command subtree, and nothing more.

Denials are reported rather than silently ignored, and what the client observes depends on its protocol version:

• Publishing to a forbidden topic: an MQTT 5.0 client receives a Not Authorized reason code on the acknowledgement and stays connected — a QoS 0 publish has no acknowledgement to carry it, so the message is simply dropped. An MQTT 3.x client is disconnected.
• Subscribing to a forbidden filter: the SUBACK marks that filter as failed — with Not Authorized for MQTT 5.0 clients and the generic failure code for MQTT 3.x — and the subscription is not created. Other filters in the same SUBSCRIBE are unaffected.

The identity that carries these rules also carries the client’s type. The JWT and HTTP providers can return both per connection instead of storing them, which lets an external identity system own topic permissions without the broker keeping a record per device. See Security overview for the provider flow in detail and MQTT client credentials for authoring the rules.

The three layers above govern MQTT clients. Access to the broker’s own management interface is a separate concern: users sign in with a password or through OAuth 2.0 / SSO, what each of them may change is decided by their role, domains control which login options a given hostname offers, and audit logs record who changed what.