Security Overview

TBMQ provides a set of security features designed to protect MQTT communication, control client access, and enforce topic-level permissions. These features cover key aspects of MQTT security — from connection level settings to fine-grained authorization rules — and offer flexible configuration options for a variety of deployment scenarios.

Connection-level security focuses on configuring how clients connect to the broker. It defines supported transport protocols, encryption options, and network-level parameters — all essential to establishing a secure communication channel before authentication and authorization are applied. In TBMQ, this is achieved through the configuration of MQTT listeners, which support both encrypted and unencrypted protocols (TCP, TLS, WebSockets). Each listener exposes configurable properties — such as ports, host addresses, and performance tuning options — that can be set via configuration files or overridden using environment variables. For TLS and WebSocket Secure (WSS) listeners, encryption parameters such as certificates and supported protocols can also be configured.

Authentication verifies the identity of clients attempting to connect. It is the process of validating client credentials before granting access to the broker. Supported authentication methods include: Basic (client id/username/password), HTTP (client id/username/password sent to the HTTP server), X.509 Certificate Chain, JWT, and SCRAM.

Authentication methods are implemented as pluggable authentication providers:

• Basic — Authenticates clients using a clientId, username, and password sent in the CONNECT packet.
• X.509 Certificate Chain — Uses the client’s X.509 certificate chain during TLS handshake for authentication.
• JWT (JSON Web Token) — Authenticates clients using a signed JWT passed in the password field of the CONNECT packet.
• SCRAM — Performs a secure challenge-response using hashed credentials to authenticate without sending the actual password (MQTT 5.0 only).
• HTTP — Authenticates clients via an external HTTP service using the clientId, username, and password.

Each provider can be individually enabled, disabled, and configured to meet requirements for different deployment use cases.

You can check the authentication provider status and enable or disable it directly from the TBMQ user interface, without modifying configuration files or restarting the broker.

• On the Home page, in the Broker Settings card, you’ll find quick-toggle buttons for each available authentication provider. Click the button next to the desired provider to enable or disable it.
• On the Authentication Providers page, you have more control and visibility:
  • You can enable or disable a provider directly from the table by clicking the Switch button in the corresponding row.
  • For more detailed management, click on a provider to open its details page, where you can change the status or other parameters.

TBMQ processes authentication providers in a configurable execution order. This can be configured from the MQTT Authentication Settings page, which is designed to configure key MQTT authentication-related parameters.

The Authentication Execution Order setting defines the order in which the broker uses authentication providers to validate MQTT client connections.

Key rules:

When all providers are disabled, the execution flow is bypassed entirely. All clients are authenticated automatically and assigned the DEVICE type with no topic restrictions. This is acceptable in isolated lab environments but must not be used in production.

When at least one provider is enabled, each provider in the configured order is evaluated until the flow stops:

• success — the client is authenticated; no further providers are tried.
• failure — the provider explicitly rejected the client; the connection is rejected immediately without trying subsequent providers. This is used by providers that apply custom authorization logic, such as the HTTP provider returning a non-success response.
• skipped — the provider could not process the credentials (for example, no client certificate was presented to the X.509 provider); the next provider in the order is tried. Disabled providers always return skipped.

If the flow reaches the end of the list without a success or failure result, the connection is rejected.

Authentication decides whether a client may connect. Authorization decides what it may do once it is connected: which topics it may publish to, and which topic filters it may subscribe to. TBMQ expresses this as two lists of regular expressions carried by the client — one for publishing, one for subscribing — so the two directions are controlled independently. A client can be allowed to publish to a topic it may not subscribe to, and the other way round.

• Every PUBLISH is checked against the publish patterns, and each topic filter in a SUBSCRIBE is checked against the subscribe patterns.
• A pattern must match the whole topic, not a fragment of it. city/.* permits city/berlin/temperature, while the pattern city permits nothing except the literal topic city.
• The topic is allowed if any pattern in that direction matches. Rules are additive — there are no deny patterns, so access is widened by adding a pattern, never narrowed.
• An empty list denies every topic in that direction. This is how you revoke publishing while leaving subscriptions intact, and it is why an accidentally cleared field locks a client out rather than opening it up.
• A client with no rules at all is unrestricted. That is the case when every authentication provider is disabled, and it is another reason not to run that way outside a lab.

Rules are resolved once, when the client connects. Editing credentials or provider settings therefore takes effect on that client’s next connection — force a reconnect if a change has to apply immediately.

Source	How the rules are defined
Basic and SCRAM credentials	One publish list and one subscribe list per credentials record, edited in the client credentials UI. Both default to .*.
X.509 credentials	Several rule sets per record, each keyed by a certificate Common Name matcher. Every set whose key matches the client’s CN applies, and patterns may embed the ${cn} placeholder for per-device scoping. A client whose CN matches no entry fails authentication.
JWT provider	Default patterns in the provider settings, optionally replaced per connection by patterns read from token claims. The fallback to the defaults is independent for publish and subscribe.
HTTP provider	Returned by the external service alongside the authentication result, falling back to the provider’s configured defaults when absent or unparsable.

Rules can also be loaded in bulk — see bulk provisioning, which treats an unmapped column and an empty cell differently.

A denial is always reported back, but not the same way in both directions: a rejected publish is answered on the acknowledgement, while a rejected subscription is flagged per topic filter in the SUBACK. For the exact reason codes and the MQTT 3.x versus 5.0 difference, see authorization in the security concepts. Every denial is also published as a CLIENT_AUTHORIZATION_FAILED lifecycle event, so integrations can alert on clients that are probing topics they have no rights to.