X.509 certificate authentication

X.509 Certificate Chain Authentication is a widely used method for securing MQTT connections in enterprise environments and IoT deployments requiring strong identity verification. Instead of relying on a username and password, clients present a certificate during the TLS handshake, allowing the broker to authenticate them based on the Common Name (CN) certificate attribute.

With X.509 Certificate Chain Authentication, the client presents its certificate chain as part of the TLS handshake. TBMQ extracts the Common Name (CN) from the client’s certificate, or any certificate in the chain, to generate a credentialsId and match it against the configured MQTT client credentials.

TBMQ supports two matching modes:

• Exact match — the CN in the certificate must exactly match the configured pattern.
• Regular expression (regex) match — the CN must match a regex pattern, allowing flexible matching for groups of certificates.

After a successful match, the client is authenticated. For performance and low-latency lookups, TBMQ caches credentials in Redis, while PostgreSQL ensures persistent storage. The following sections explain provider configuration, credential matching, credentialsId generation, and how authorization is applied after successful authentication.

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.

Go to the Broker Settings card on the Home page to switch authentication providers. On the Authentication → Providers page, use the switch button in the table's right column to enable or disable providers. Open the Authentication → Providers page, select the X.509 Certificate Chain row, and click the "Edit" button to configure the provider.

The Skip certificate validity check for client certificates parameter controls whether the broker verifies the validity period of the client’s certificate during authentication.

• When enabled, TBMQ skips the validation of the Not Before and Not After dates in the certificate, meaning expired or not-yet-valid certificates will still be accepted.
• When disabled, the broker enforces standard validity checks, and authentication will fail if the certificate is expired or not yet valid.

The X.509 Certificate Chain credentials have a “Use certificate CN regex” option that controls how credentials are matched.

• When “Use certificate CN regex” is disabled: the “Certificate common name (CN)” must exactly match the CN of the client’s certificate or, if present, one of the parent’s certificates in the chain. Authentication will fail if none of the certificates have an exactly matching CN.

• When “Use certificate CN regex” is enabled: the “Certificate common name (CN) matcher regex” must match the CN of the client’s certificate or, if present, one of the parent’s certificates in the chain. Authentication will fail if no certificate in the chain matches the regex.

The credentialsId is generated as follows:

• ssl|$CERTIFICATE_COMMON_NAME — for exact CN matching.
• ssl|$CERTIFICATE_COMMON_NAME_REGEX — for regex-based CN matching.

Where $CERTIFICATE_COMMON_NAME is the common name of the certificate from the chain, and $CERTIFICATE_COMMON_NAME_REGEX is a regex-based string that should be matched with the certificate’s CN from the chain.

Copy TLS credentials ID. TLS authentication with "Use certificate CN regex" disabled to match certificate common name by exact match. TLS authentication with "Use certificate CN regex" enabled to match certificate common name using a regex pattern.

After the client is authenticated, it is possible to restrict its access to topics it can publish or subscribe to. To provide flexible control over authorization rules, TBMQ uses regular expressions.

For example, to allow clients to publish or subscribe to all topics that begin with city/, an authorization rule should be created with the value city/.*.

For the X.509 Certificate Chain type, authorization is configured using the authRulesMapping field of the corresponding MQTT client credentials:

{
  "certCnPattern": "$certCnPattern",
  "certCnIsRegex": "$certCnIsRegex",
  "authRulesMapping": {
    "example_1": {
      "pubAuthRulePatterns": ["example_pub_topic/.*"],
      "subAuthRulePatterns": ["example_sub_topic/.*"]
    },
    "example_2": {
      "pubAuthRulePatterns": [".*"],
      "subAuthRulePatterns": [".*"]
    }
  }
}

Where:

• certCnPattern — the pattern for the common name that should be present in the certificate chain.
• certCnIsRegex — option to control whether the CN pattern is treated as a regular expression for matching.
• authRulesMapping — the mapping used to configure the access restrictions for different keywords.

This allows clients to connect with a certificate containing example_1 in its CN to publish only to topics that start with example_pub_topic/ and subscribe to topics that start with example_sub_topic/. Clients with a certificate containing example_2 are allowed to publish and subscribe to any topic.

X.509 certificates are used to set up mutual (two-way) authentication for MQTT over TLS. There are two strategies that can be used for establishing a connection between the client and TBMQ:

• X.509 Certificate chain — configure TBMQ to trust all client certificates from a specific trust anchor (intermediate certificate). This feature eliminates the need for manual certificate updates on each MQTT client credential when certificate rotation occurs.
• X.509 Certificate — configure TBMQ to accept connections from specific devices using pre-configured client certificates.