Skip to main content

MQTT TLS and Certificate Authentication

availability
Feature availability by platform, plan type, and user type
Platform:AvailableWebNot availableMobile
Plan Type:Not availableBasicNot availableEssentialAvailablePremiumAvailableEnterprise
User Type:Not availableRequesterNot availableFull UserAvailableAdministrator

By default, the MaintainX® MQTT On-Premise Agent (referred to as the OPA) uses a secure Transport Layer Security (TLS) connection to communicate with the MQTT broker. It only trusts certificates signed by recognized authorities. You can configure client certificate authentication independently of or in addition to credentials authentication. Additionally, you can add your own Certificate Authority (CA) certificate to validate your MQTT server's certificate on each connection.

danger

Don't turn off TLS or allow untrusted certificates in production environments. Malicious actors can intercept or tamper with your data when your connection isn't secure.

TLS Settings Fields​

The following table defines the TLS fields in the settings.json file. The line numbers refer to the Basic Configuration example.

LineFieldTypeValuesDefaultRequired?Description
16TLS-EnabledBooleantrue, falsetrueNoEnables or disables communication over TLS.
17Allow-Untrusted-CertificatesBooleantrue, falsefalseNoWhen set to true, trust any certificate sent by the server, including self-signed certificates.
18Client-Certificate-ModeEnumBase64, Raw, PathPathIf Client-Certificate is set.The mode used to supply the client certificate.

The required format for the Client-Certificate field changes depending on the value you provide here.

For details, see Certificate Modes.
19Client-CertificateStringnullNoThe client certificate presented to the server for authentication.

If you set this field, you must also set the following fields:

- Client-Certificate-Mode
- Private-Key
20Private-Key-ModeEnumBase64, Raw, PathPathIf Private-Key is set.The mode used to supply the client certificate's private key.

The required format for the Private-Key field changes depending on the value you provide here.

For details, see Certificate Modes.
21Private-KeyStringnullNoThe private key of the client certificate.

If you set this field, you must also set the following fields:

- Private-Key-Mode
22CA-Certificate-ModeEnumBase64, Raw, PathPathIf CA-Certificate is set.The mode used to supply the CA certificate.

The required format for the CA-Certificate field changes depending on the value you provide here.

For details, see Certificate Modes.
23CA-CertificateStringnullNoThe CA certificate of the MQTT server's certificate.

If you set this field, you must also set the following field:

- CA-Certificate-Mode

Certificate Modes​

Definition of the certificate modes in the settings.json file:

TypeDescriptionExample
Base64Enter a Base64-encoded string of the raw certificate.

Take the raw certificate string starting with -----BEGIN CERTIFICATE----- or -----BEGIN RSA PRIVATE KEY----- and encode it in base64.

For details, see Example using Base64 Certificate Strings		LS0tLSWo5STV6VlprUGZLDQpzb2FzNmpn … otLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t
RawEnter the raw certificate as a string.

If you enter the certificate as a one-line string, add the line return character \n for each line return.

For details, see Example using Raw Certificate Strings		-----BEGIN CERTIFICATE-----\nMIIDWjCCAkKgAwIBAgI … vW3g8wRr6lzmvqJNeBYhg==\n-----END CERTIFICATE-----
PathEnter the path to a certificate file in the container.

For this mode, supply the certificate file using volume mounts or Docker secrets.

For details, see Example using Path to Certificate Files		/run/secrets/clientcert.pem

Examples​

The following examples show complete settings.json files with TLS configured.

Basic Configuration​

 {
   "Integration": {
     "AccessToken": "{MaintainX-Connector-Token}"
   },
   "Mqtt": {
     "client": {
       "tcpServer": {
         "server": "{MQTT_Broker_Host}",
         "port": {MQTT-Broker-Port}
       },
       "credentials": {
         "username": "{MQTT_Broker_Username}",
         "password": "{MQTT_Broker_Password}"
       },
       "tls": {
         "useTls": {TLS-Enabled},
         "allowUntrustedCertificates": {Allow-Untrusted-Certificates},
         "ClientCertificateMode": "{Client-Certificate-Mode}",
         "ClientCertificate": "{Client-Certificate}",
         "CertificateKeyMode": "{Private-Key-Mode}",
         "CertificateKey": "{Private-Key}",
         "CertificateAuthorityMode": "{CA-Certificate-Mode}",
         "CertificateAuthority": "{CA-Certificate}"
       }
     }
   }
 }

Base64 Certificate Strings​

 {
   "Integration": {
     "AccessToken": "CfD....."
   },
   "Mqtt": {
     "client": {
       "tcpServer": {
         "server": "mqtt.broker.com",
         "port": 8883
       },
       "credentials": {
         "username": "mqtt_user",
         "password": "password123"
       },
       "tls": {
         "useTls": true,
         "allowUntrustedCertificates": false,
         "ClientCertificateMode": "Base64",
         "ClientCertificate": "LS0tLSWo5STV6VlprUGZLDQpzb2FzNmpn...c4d1JyNmx6bXZxSk5lQlloZz09DQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t",
         "CertificateKeyMode": "Base64",
         "CertificateKey": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVka...drRXBVSW5SU1RmT1FBPT0NCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0t",
         "CertificateAuthorityMode": "Base64",
         "CertificateAuthority": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS...5vWnNHNHE1V1RQNDY4U1F2dkc1DQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t"
       }
     }
   }
 }

Raw Certificate Strings​

 {
   "Integration": {
     "AccessToken": "CfD....."
   },
   "Mqtt": {
     "client": {
       "tcpServer": {
         "server": "mqtt.broker.com",
         "port": 8883
       },
       "credentials": {
         "username": "mqtt_user",
         "password": "password123"
       },
       "tls": {
         "useTls": true,
         "allowUntrustedCertificates": false,
         "ClientCertificateMode": "Raw",
         "ClientCertificate": "-----BEGIN CERTIFICATE-----\nMIIDWjCCAkKgAwIBAgI...vW3g8wRr6lzmvqJNeBYhg==\n-----END CERTIFICATE-----",
         "CertificateKeyMode": "Raw",
         "CertificateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA1Q...5Gpkd7kEpnRSTfOQA==\n-----END RSA PRIVATE KEY-----",
         "CertificateAuthorityMode": "Raw",
         "CertificateAuthority": "-----BEGIN CERTIFICATE-----\nMIIDQTCCAimgAADb....oQnoZsG4q5WTP468SQvvG5\n-----END CERTIFICATE-----"
       }
     }
   }
 }

Path to Certificate Files​

 {
   "Integration": {
     "AccessToken": "CfD....."
   },
   "Mqtt": {
     "client": {
       "tcpServer": {
         "server": "mqtt.broker.com",
         "port": 8883
       },
       "credentials": {
         "username": "mqtt_user",
         "password": "password123"
       },
       "tls": {
         "useTls": true,
         "allowUntrustedCertificates": false,
         "ClientCertificateMode": "Path",
         "ClientCertificate": "/run/secrets/clientcert.pem",
         "CertificateKeyMode": "Path",
         "CertificateKey": "/run/secrets/clientkey.pem",
         "CertificateAuthorityMode": "Path",
         "CertificateAuthority": "/run/secrets/ca.pem"
       }
     }
   }
 }

Additional On-Premise Agent Setup When Using Certificate Files​

If you're using certificate files, you can make them available to the OPA container by using volume mounts.

  1. Create a certificate directory for the OPA. Then navigate to that directory.

     mkdir -p ~/.maintainx/opa-certificates
     cd ~/.maintainx/opa-certificates

  2. Add your certificate files to the directory.

  3. Start the OPA with certificate files mounted from the $HOME/.maintainx/opa-certificates folder on your system:

     docker run -d --name on-premise-agent -v $HOME/.maintainx/sensor-connect:/config -v $HOME/.maintainx/opa-certificates:/run/secrets maintainx/on-premise-agent:latest