X.509 Certificate Chain Authentication

• X.509 authentication overview
• Configure provider
  • Skip certificate validity check for client certificates
• Credentials matching
• Credentials ID
• Authorization
• Example
• Next steps

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.

X.509 authentication overview

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 credentialsId and match it against the configured MQTT client credentials.

TBMQ supports two matching modes:

• Exact match — where the CN in the certificate must exactly match the configured pattern.
• Regular expression (regex) match — where 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.

Configure provider

You can check the authentication provider status, enable or disable it directly from the TBMQ user interface, making it easy to manage authentication behavior 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.

Skip certificate validity check for client certificates

The Skip certificate validity check for client certificates parameter in X.509 Certificate Chain Authentication 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 the standard validity checks, and authentication will fail if the certificate is expired or not yet valid.

This setting can be useful in testing or specific trust-controlled environments, but set it to true is not recommended for production deployments, as it weakens the certificate-based security model.

Credentials matching

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.

• “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.

Credentials ID

The generation of credentialsId is done as follows:

• credentialsId = ssl|$CERTIFICATE_COMMON_NAME;
• credentialsId = ssl|$CERTIFICATE_COMMON_NAME_REGEX.

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

Authorization

After the user has been authenticated, it is possible to restrict the client’s access to topics they 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 TLS type, authorization is configured using the authRulesMapping field of the corresponding MQTT Client Credentials. Here is a model of the credentials value:

1
2
3
4
5
{
    "certCnPattern": $certCnPattern,
    "certCnIsRegex": $certCnIsRegex,
    "authRulesMapping": $authRulesMapping
}

Where:

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

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  {
      "example_1": {
          "pubAuthRulePatterns": ["example_pub_topic/.*"],
          "subAuthRulePatterns": ["example_sub_topic/.*"]
      },
      "example_2": {
          "pubAuthRulePatterns": [".*"],
          "subAuthRulePatterns": [".*"]
      }
  }
  

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.

Note: if either pubAuthRulePatterns or subAuthRulePatterns is set to null or an empty list ([]), the client will not be able to publish to or subscribe to any topics.

Example

X.509 Certificates are used to set up mutual (two-way) authentication for MQTT over TLS. Instructions below will describe how to connect MQTT client using X.509 Certificate to TBMQ.

In particular, there are two strategies that can be used for establishing connection between 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 the specific devices using pre-configured client certificates.

1
openssl req -x509 -newkey rsa:4096 -keyout rootKey.pem -out rootCert.pem -sha256 -days 365 -nodes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Generating a RSA private key
writing new private key to 'rootKey.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:company.com
Email Address []:

1
openssl req -new -newkey rsa:4096 -keyout intermediateKey.pem -out intermediate.csr -sha256 -nodes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Generating a RSA private key
writing new private key to 'intermediateKey.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:group.company.com
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

1
openssl x509 -req -in intermediate.csr -out intermediateCert.pem -CA rootCert.pem -CAkey rootKey.pem -days 365 -sha256 -CAcreateserial -extfile <(echo "basicConstraints=CA:TRUE,pathlen:0")

1
2
3
Signature ok
subject=C = AU, ST = Some-State, O = Internet Widgits Pty Ltd, CN = group.company.com
Getting CA Private Key

1
openssl req -new -newkey rsa:4096 -keyout deviceKey.pem -out device.csr -sha256 -nodes

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Generating a RSA private key
writing new private key to 'deviceKey.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:device.group.company.com
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

1
openssl x509 -req -in device.csr -out deviceCert.pem -CA intermediateCert.pem -CAkey intermediateKey.pem -days 365 -sha256 -CAcreateserial

1
2
3
Signature ok
subject=C = AU, ST = Some-State, O = Internet Widgits Pty Ltd, CN = device.group.company.com
Getting CA Private Key

1
cat deviceCert.pem intermediateCert.pem rootCert.pem > chain.pem

1
2
mosquitto_pub --cafile ca.pem -d -q 1 -h "YOUR_TBMQ_HOST" -p "8883" \
-t "sensors/temperature" --key deviceKey.pem --cert chain.pem -m {"temperature":25}

1
2
mosquitto_pub --insecure --cafile server.pem -d -q 1 -h "YOUR_TBMQ_HOST" -p "8883" \
-t "sensors/temperature" --key deviceKey.pem --cert chain.pem -m {"temperature":25}

1
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes

1
2
openssl ecparam -out key.pem -name prime256v1 -genkey
openssl req -new -key key.pem -x509 -nodes -days 365 -out cert.pem 

1
2
mosquitto_pub --cafile ca.pem -d -q 1 -h "YOUR_TBMQ_HOST" -p "8883" \
-t "sensors/temperature" --key key.pem --cert cert.pem -m {"temperature":25}

Next steps

• Getting started guide - This guide provide quick overview of TBMQ.

• Installation guides - Learn how to set up TBMQ using Docker or deploy it in K8S environments on AWS, GCP, and Azure.

• Configuration guide - Learn about TBMQ configuration files and parameters.

• MQTT client type guide - Learn about TBMQ client types.

• Integration with ThingsBoard - Learn about how to integrate TBMQ with ThingsBoard.