Configure MQTT Client Certificate Authentication
Summary
This tutorial explains how to configure MQTT client certificate authentication between Chariot, MQTT Engine, and MQTT Transmission using TLS/SSL client certificates. You will learn how to 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 for 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 OpenSSL 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 following certificate hierarchy will be created for:
- Root Certificate Authority (CA)
- MQTT Engine client certificate
- MQTT Transmission client certificate
Create the following folder structure:
chariotcerts/
├── ca/
└── certs/
├── engine/
└── transmission/
The Root CA acts as the trusted authority used to sign the MQTT Engine and MQTT Transmission client certificates. Chariot validates client certificates against the trusted Root CA certificates stored in the Chariot truststore.
Generate the Root CA Certificate
Generate the Root CA private key:
bash openssl genrsa -des3 -out ca/ca.key 4096
Generate the self-signed Root CA certificate:
openssl req -new -x509 -key ca/ca.key -days 3650 -out ca/ca.crt
Complete the certificate fields using the appropriate organization and domain information.
⚠️ Store the Root CA private key securely. The passphrase will be required during later steps.
After completion, the following files should exist:
chariotcerts/
├── ca/
│ ├── ca.crt
│ ├── ca.key
Generate the MQTT Engine Client Certificate
Generate the MQTT Engine private key:
openssl genrsa -out certs/engine/engine.key 4096
Generate the MQTT Engine CSR:
openssl req -new -key certs/engine/engine.key -out certs/engine/engine.csr
Sign the MQTT Engine certificate 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
Generate the MQTT Transmission Client Certificate
Generate the MQTT Transmission private key:
openssl genrsa -out certs/transmission/transmission.key 4096
Generate the MQTT Transmission CSR:
openssl req -new -key certs/transmission/transmission.key -out certs/transmission/transmission.csr
Sign the MQTT Transmission certificate 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
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
Configure SSL on Chariot
Upload Server Certificates
- Navigate to System → Certificates under the Configuration menu.
- Upload the following files:
| Configuration Field | Description |
|---|---|
| CA Chain | Certificate Authority chain file |
| Private Key | Private key associated with the server certificate |
| Certificate | Server certificate issued by the CA |
- Select Setup SSL after uploading the files.
Enable Secure MQTT
- Navigate to Server Configuration under the MQTT menu.
- Toggle Enable Secure from the options, as pictured below.
- Select Update to save the configuration.
Update the Chariot Truststore
The default Chariot truststore file is located at:
<chariot_install_dir>/security/clientcerts.jks
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
Import the Root CA certificate:
keytool -importcert -file ca/ca.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias CACertificate
Import the MQTT Engine certificate:
keytool -importcert -file certs/engine/engine.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias EngineDevice
Import the MQTT Transmission certificate:
keytool -importcert -file certs/transmission/transmission.crt -keystore <chariot_install_dir>/security/clientcerts.jks -alias TransmissionDevice1
When prompted:
Trust this certificate? [no]:
Enter:
yes
After importing the certificates, verify that the Root CA, MQTT Engine, and MQTT Transmission certificates appear in the truststore.
Configure the Chariot Client Authentication Policy
Edit the following configuration file:
<chariot_install_dir>/conf/com.cirruslink.chariot.server
Set:
clientAuthPolicy="required"
❗ Restart the Chariot service after saving the configuration changes.
Configure MQTT Engine
Upload MQTT Engine Certificates
- In Ignition, navigate to the Config tab, then MQTT Engine → Servers → Certificates.
- Upload:
| Friendly Name | File | File Description | File Location |
|---|---|---|---|
| EngineCertificate | engine.crt | MQTT Engine Certificate | chariotcerts/certs/engine |
| EngineKey | engine.key | MQTT Engine Private Key | chariotcerts/certs/engine |
Configure the MQTT Engine Connection
-
In Ignition, navigate to the Config tab, then MQTT Engine → Servers → Settings.
-
Configure the Chariot server URL using SSL:
ssl://<FQDN>:8883 -
Assign the uploaded certificates and save the configuration.
⚠️ The connection URL must use
ssl://. Non-secure connections will fail.
Configure MQTT Transmission
Upload MQTT Transmission Certificates
- In Ignition, navigate to the Config tab, then MQTT Transmission → Servers → Certificates.
- Upload:
| Friendly Name | File | File Description | File Location |
|---|---|---|---|
| TransmissionCertificate | transmission.crt | MQTT Transmission Certificate | chariotcerts/certs/transmission |
| TransmissionKey | transmission.key | MQTT Transmission Private Key | chariotcerts/certs/transmission |
Configure the MQTT Transmission Connection
- In Ignition, navigate to the Config tab, then MQTT Transmission → Servers → Settings.
- Configure the Chariot server URL using SSL and assign the uploaded certificates.
- Save the configuration after completing the setup.
Configure Anonymous Connections
Chariot MQTT Server still requires MQTT credentials for client authentication, even when TLS/SSL client certificates are used.
If MQTT clients will not provide MQTT usernames and passwords, anonymous connections must be enabled.
- In Chariot, navigate to MQTT Server → Configuration under the Configuration menu.
- Enable Allow Anonymous. A password must still be configured for the MQTT Credential, even though it will not be used for authentication.
By default, anonymous MQTT clients are allowed to publish and subscribe on # unless an
Anonymous MQTT Credential is configured. An Anonymous MQTT Credential can optionally be selected to apply publish and subscribe ACLs to anonymous client connections.
Verify Connectivity
MQTT Engine
-
In Ignition, navigate to the Config tab, then MQTT Engine → Servers → Settings.
-
Verify the server status displays Connected.
MQTT Transmission
- In Ignition, navigate to the Config tab, then MQTT Transmission → Servers.
- Verify the configured transmitters display connected status.
Chariot
- In the Chariot Web UI, navigate to MQTT under the Status tab.
- Verify the MQTT client count reflects the active MQTT Engine and MQTT Transmission connections.
- Optionally enable additional client details for troubleshooting and verification.
