Skip to main content
Chariot v2.0.0 - v2.6.0

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/

Generate the Root CA Certificate​

Generate the Root CA private key:

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​

  1. Navigate to System → Certificates under the Configuration menu.

  2. Upload the following files:

Configuration FieldDescription
CA ChainCertificate Authority chain file
Private KeyPrivate key associated with the server certificate
CertificateServer certificate issued by the CA
  1. Select Setup SSL after uploading the files.

Enable Secure MQTT​

  1. Navigate to the MQTT Server tab.

  2. Enable Secure and 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

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​

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

  2. Upload:

Friendly NameFileFile DescriptionFile Location
EngineCertificateengine.crtMQTT Engine Certificatechariotcerts/certs/engine
EngineKeyengine.keyMQTT Engine Private Keychariotcerts/certs/engine

Configure the MQTT Engine Connection​

  1. In Ignition, navigate to the Config tab, then MQTT Engine → Servers → Settings.

  2. Configure the Chariot server URL using SSL: ssl://<FQDN>:8883

  3. 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​

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

  2. Upload:

Friendly NameFileFile DescriptionFile Location
TransmissionCertificatetransmission.crtMQTT Transmission Certificatechariotcerts/certs/transmission
TransmissionKeytransmission.keyMQTT Transmission Private Keychariotcerts/certs/transmission

Configure the MQTT Transmission Connection​

  1. In Ignition, navigate to the Config tab, then MQTT Transmission → Servers → Settings.

  2. Configure the Chariot server URL using SSL and assign the uploaded certificates.

  3. 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.

  1. In the Chariot Web UI, navigate to MQTT Server Configuration under the Configuration tab
  2. Enable Allow Anonymous
  3. An Anonymous MQTT Credential can be selected to apply publish and subscribe ACLs to anonymous client connections. (optional)

Verify Connectivity​

MQTT Engine​

  1. In Ignition, navigate to the Config tab, then MQTT Engine → Servers.
  2. Verify the server Status displays Connected

MQTT Transmission​

  1. In Ignition, navigate to the Config tab, then MQTT Transmission → Servers.
  2. Verify the configured transmitters are connected by the Connected status showing "1 of 1".

Chariot​

  1. In the Chariot Web UI, navigate to MQTT under the Status tab.
  2. Verify the MQTT client count reflects the active MQTT Engine and MQTT Transmission connections.