Configure MQTT Client Certificate Authentication

Overview

This tutorial explains how to configure MQTT client certificate authentication between Chariot, MQTT Engine, and MQTT Transmission using TLS/SSL client certificates. You will generate certificates and keys, configure two-way SSL authentication, update the Chariot truststore, and configure MQTT Engine and MQTT Transmission to authenticate using client certificates.

This tutorial covers client certificate authentication only. TLS/SSL must already be configured on the Chariot MQTT Server to provide secure MQTT communication.

⚠️ Available in Chariot v2.3.1 and newer.

Prerequisites

The following components are required:

• Ignition installed with:

  • MQTT Engine
  • MQTT Transmission

• Chariot MQTT Server v2.3.1 or newer

• OpenSSL command line tools

• Java keytool

OpenSSL

Install the OpenSSL command line tool and ensure the OpenSSL executable is available in the system PATH.

Keytool

keytool is included with standard Java distributions.

Chariot includes a Java runtime located at:

<chariot_install_dir>/lib/runtime/jdk11.0.12_7/bin

Add the keytool directory to the system PATH if necessary.

❗ Restart any open command windows after updating environment variables.

---

Generate Certificates and Keys

The first step is to generate the certificate hierarchy for Chariot, MQTT Engine, and MQTT Transmission.

Create the following folder structure on your local drive to hold the certificates:

chariotcerts/
├── ca/
└── certs/
    ├── engine/
    └── transmission/

The Root Certificate Authority (CA) is the highest level of authority in the certificate hierarchy. It is responsible for issuing signed certificates, including the MQTT Engine and MQTT Transmission client certificates. When the Root CA issues a certificate, it signs the certificate with its private key. Chariot can then verify the authenticity of client certificates using the Root CA's public key.

Note: This tutorial covers client-based authentication using certificates. It does not cover setting up TLS/SSL on the MQTT Server, which is required to encrypt communication between MQTT clients and the MQTT Server. See Secure Chariot MQTT Server Communication Using SSL/TLS for information about configuring TLS/SSL.

The following certificates and keys will be generated:

• Root CA certificate and private key
• MQTT Engine client certificate and private key
• MQTT Transmission client certificate and private key

Generate the Root CA Certificate

1. Generate a private key file (ca.key) for the Root CA.

   The -des3 option protects the private key with a passphrase. You may choose the passphrase when prompted.

   openssl genrsa -des3 -out ca/ca.key 4096

   ⚠️ If you set a passphrase for the Root CA private key, make note of it. The passphrase will be required during subsequent certificate-generation steps.

2. Generate a self-signed Root CA certificate (ca.crt):

   openssl req -new -x509 -key ca/ca.key -days 3650 -out ca/ca.crt

   This command generates a self-signed X.509 certificate named ca.crt that is valid for 3650 days (10 years) using the RSA private key ca.key. You will be prompted for the passphrase associated with ca.key.

3. Complete the certificate fields using the appropriate organization and domain information.

   The certificate request uses a Distinguished Name (DN). Some fields can be left blank, and some fields provide default values.

   An example Root CA creation is shown below:

   $ openssl req -new -x509 -key ca/ca.key -days 3650 -out ca/ca.crt
   Enter pass phrase for ca/ca.key:
   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]:US
   State or Province Name (full name) [Some-State]:KS
   Locality Name (eg, city) []:Stilwell
   Organization Name (eg, company) [Internet Widgits Pty Ltd]:Cirrus Link Solutions
   Organizational Unit Name (eg, section) []:Support
   Common Name (e.g. server FQDN or YOUR name) []:CLS Example Root CA
   Email Address []:
   $

After completing this step, the following files should exist:

chariotcerts/
├── ca/
│   ├── ca.crt
│   └── ca.key

Note: Depending on the version of OpenSSL being used, additional .srl files may be created. These files contain the unique serial number for a signed certificate. They are not used directly by the modules and are not included in the certificate hierarchy shown above.

Generate the MQTT Engine Client Certificate

1. Generate the MQTT Engine private key:

   openssl genrsa -out certs/engine/engine.key 4096

2. Generate a Certificate Signing Request (CSR) for MQTT Engine:

   openssl req -new -key certs/engine/engine.key -out certs/engine/engine.csr

   Complete the certificate request fields using the appropriate information.

   An example CSR creation is shown below:

   $ openssl req -new -key certs/engine/engine.key -out certs/engine/engine.csr
   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]:US
   State or Province Name (full name) [Some-State]:KS
   Locality Name (eg, city) []:Stilwell
   Organization Name (eg, company) [Internet Widgits Pty Ltd]:Cirrus Link Solutions
   Organizational Unit Name (eg, section) []:Support
   Common Name (e.g. server FQDN or YOUR name) []:EngineDevice
   Email Address []:
   
   Please enter the following 'extra' attributes
   to be sent with your certificate request
   A challenge password []:
   An optional company name []:
   $

3. Sign the MQTT Engine client CSR using the Root CA:

   openssl x509 -req -in certs/engine/engine.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out certs/engine/engine.crt -days 365

   This command signs engine.csr with the Root CA certificate (ca.crt) and Root CA private key (ca.key) and creates an X.509 certificate named engine.crt that is valid for 365 days (1 year).

   You will be required to enter the passphrase associated with ca.key.

Generate the MQTT Transmission Client Certificate

1. Generate the MQTT Transmission private key:

   openssl genrsa -out certs/transmission/transmission.key 4096

2. Generate a Certificate Signing Request (CSR) for MQTT Transmission:

   openssl req -new -key certs/transmission/transmission.key -out certs/transmission/transmission.csr

   Complete the certificate request fields using the appropriate information.

   An example CSR creation is shown below:

   $ openssl req -new -key certs/transmission/transmission.key -out certs/transmission/transmission.csr
   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]:US
   State or Province Name (full name) [Some-State]:KS
   Locality Name (eg, city) []:Stilwell
   Organization Name (eg, company) [Internet Widgits Pty Ltd]:Cirrus Link Solutions
   Organizational Unit Name (eg, section) []:Support
   Common Name (e.g. server FQDN or YOUR name) []:TransmissionDevice1
   Email Address []:
   
   Please enter the following 'extra' attributes
   to be sent with your certificate request
   A challenge password []:
   An optional company name []:
   $

3. Sign the MQTT Transmission client CSR using the Root CA:

   openssl x509 -req -in certs/transmission/transmission.csr -CA ca/ca.crt -CAkey ca/ca.key -CAcreateserial -out certs/transmission/transmission.crt -days 365

   This command signs transmission.csr with the Root CA certificate (ca.crt) and Root CA private key (ca.key) and creates an X.509 certificate named transmission.crt that is valid for 365 days (1 year).

   You will be required to enter the passphrase associated with the Root CA private key.

Certificate Structure

After completing the certificate generation steps, the directory structure should resemble the following:

chariotcerts/
├── ca/
│   ├── ca.crt
│   └── ca.key
└── certs/
    ├── engine/
    │   ├── engine.crt
    │   ├── engine.csr
    │   └── engine.key
    └── transmission/
        ├── transmission.crt
        ├── transmission.csr
        └── transmission.key

The certificates and keys in this directory are used to configure client certificate-based authentication between Chariot and the MQTT Engine and MQTT Transmission modules.

---

Set Up SSL Connections Using Two-Way Authentication

The following sections configure SSL connections between the MQTT Engine and MQTT Transmission clients and the Chariot MQTT Server.

The configuration consists of two parts:

• Server-side configuration

  • Enable SSL on Chariot and add the server-side certificates and keys.
  • Add the MQTT Engine and MQTT Transmission client certificates to the Chariot truststore.
  • Set the Chariot client authentication policy to required.

• Client-side configuration

  • Add the MQTT Engine certificate and private key to the Chariot connection on the MQTT Engine side.
  • Add the MQTT Transmission certificate and private key to the Chariot connection on the MQTT Transmission side.

Server-Side Configuration

Set Up SSL on Chariot

1. Navigate to Main Menu → General → Certificates.

2. Upload the following certificate components:

   File Type	Where to Get the File
   CA Chain	Provided by your Certificate Authority
   Private Key	The key generated when creating the CSR submitted to your Certificate Authority
   Certificate	The server certificate provided by your Certificate Authority after the CSR was submitted

3. Select Setup SSL after uploading the files.

Note: Use the certificate components created when configuring Secure Chariot MQTT Server Communication Using SSL/TLS.

Enable Secure MQTT

1. Navigate to Main Menu → MQTT → Server Configuration → Configuration.

2. Enable Enable Secure.

3. Select Update to save the configuration.

Update the Chariot Truststore

By default, Chariot includes an empty truststore named clientcerts.jks located at:

<chariot_install_dir>/security/clientcerts.jks

1. View the current truststore contents:

   keytool -list -v -keystore <chariot_install_dir>/security/clientcerts.jks

   The truststore password can be found in:

   <chariot_install_dir>/conf/com.cirruslink.chariot.system

   The password is specified by the trustStorePassword parameter.

   A new truststore will contain no entries before the client certificates are imported.

2. Import the Root CA certificate:

   keytool -importcert -file ca/ca.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias CACertificate

   When prompted:

   Trust this certificate? [no]:

   Enter:

   yes

3. Import the MQTT Engine certificate:

   keytool -importcert -file certs/engine/engine.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias EngineDevice

   When prompted to trust the certificate, enter yes.

4. Import the MQTT Transmission certificate:

   keytool -importcert -file certs/transmission/transmission.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias TransmissionDevice1

   When prompted to trust the certificate, enter yes.

5. Verify that the Root CA, MQTT Engine, and MQTT Transmission certificates appear in the truststore.

   After importing the certificates, the truststore should contain three entries.

Configure the Chariot Client Authentication Policy

1. Using a text editor, edit the following configuration file:

   <chariot_install_dir>/conf/com.cirruslink.chariot.server

2. Set clientAuthPolicy to required:

   clientAuthPolicy="required"

3. Save the configuration file.

❗ Restart the Chariot service after saving the configuration changes.

Client-Side Configuration

Configure MQTT Engine

1. In Ignition, navigate to Config → MQTT Engine → Servers → Certificates.

2. Add the following certificates:

   Friendly Name	Certificate Filename	File Description	File Location
   EngineCertificate	engine.crt	MQTT Engine Certificate	chariotcerts/certs/engine
   EngineKey	engine.key	MQTT Engine Private Key	chariotcerts/certs/engine

3. Navigate to Config → MQTT Engine → Servers → Settings.

4. Configure the Chariot server URL using SSL:

   ssl://<FQDN>:8883

   Replace <FQDN> with the FQDN of the Chariot Server.

5. Assign the uploaded certificates to the Chariot connection.

6. Select Save Changes to save the configuration.

⚠️ The connection URL must use ssl://. If a non-secure connection is specified, the connection will not succeed.

Configure MQTT Transmission

1. In Ignition, navigate to Config → MQTT Transmission → Servers → Certificates.

2. Add the following certificates:

   Friendly Name	Certificate Filename	File Description	File Location
   TransmissionCertificate	transmission.crt	MQTT Transmission Certificate	chariotcerts/certs/transmission
   TransmissionKey	transmission.key	MQTT Transmission Private Key	chariotcerts/certs/transmission

3. Navigate to Config → MQTT Transmission → Servers → Settings.

4. Configure the Chariot server connection to use SSL.

5. Assign the uploaded certificates to the Chariot connection.

6. Select Save Changes to save the configuration.

⚠️ The connection URL must use SSL. If a non-secure connection is specified, the connection will not succeed.

Configure Anonymous Client Connections

Chariot MQTT Server still requires MQTT account credentials to authenticate incoming client connections, even when client certificates are used to establish a TLS/SSL session.

If clients will not send an MQTT username and password, anonymous connections must be enabled.

1. Navigate to Main Menu → MQTT → Server Configuration → Configuration.

2. Enable Allow Anonymous.

By default, an anonymous client connection is allowed to publish and subscribe on # unless an Anonymous MQTT Credential has been selected.

An MQTT account credential can be selected for anonymous connections to apply its Publish and Subscribe ACLs to all anonymous connections.

3. To configure an Anonymous MQTT Credential, navigate to Main Menu → MQTT → MQTT Accounts → Credentials.

4. Select the MQTT Account Credential to use for anonymous connections.

Note: A password must be configured for the MQTT Credential, but Chariot does not use the password to authenticate anonymous connections.

---

Verify Connectivity

MQTT Engine

1. From the Ignition left-hand menu, navigate to Config → MQTT Engine → Servers.

2. Verify that the server Status displays Connected.

MQTT Transmission

1. From the Ignition left-hand menu, navigate to Config → MQTT Transmission → Servers.

2. Verify that the Status displays x of x.

   This indicates the number of configured transmitters that are connected.

If a transmitter does not appear as connected, verify that the transmitter has a valid Sparkplug ID. The Sparkplug ID can be configured through the Group and Edge ID or through the TagPath.

If the transmitter still does not appear as connected, review the MQTT Transmission troubleshooting guide for assistance.

Chariot

1. In the Chariot MQTT Server Web UI, navigate to Main Menu → MQTT → Client Status → Clients.

2. Verify that the number of active MQTT clients is displayed.

   The active client count should be 2 or 3, depending on the MQTT Transmission RPC Client configuration.

3. Select the option to display additional client details if more information is needed for troubleshooting or verification.