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® On-Premise Agent (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 or in addition to credentials authentication. Additionally, you can add your own Certificate Authority's (CA) certificate to validate your MQTT server's certificate on each connection.

danger

Although you can turn off TLS or allow untrusted certificates, please do not do it for production environments! Doing so could leave your data vulnerable to interception or tampering by malicious actors.

Here's an example of a settings.json file with TLS, client certificate authentication, and CA certificate trust configurations:

 {
   "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}"
       }
     }
   }
 }

TLS Settings Fields

Definition of the TLS fields in the settings.json file:

Line	Field	Type	Values	Default	Required?	Description
16	`TLS-Enabled`	Boolean	`true`, `false`	`true`	No	Enables or disables communication over TLS.
17	`Allow-Untrusted-Certificates`	Boolean	`true`, `false`	`false`	No	When set to `true`, trust any certificate sent by the server including self-signed certificates
18	`Client-Certificate-Mode`	Enum	`Base64`, `Raw`, `Path`	`Path`	If `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.
19	`Client-Certificate`	String		`null`	No	The 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`
20	`Private-Key-Mode`	Enum	`Base64`, `Raw`, `Path`	`Path`	If `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.
21	`Private-Key`	String		`null`	No	The private key of the client certificate. If you set this field, you must also set the following fields: - `Private-Key-Mode`
22	`CA-Certificate-Mode`	Enum	`Base64`, `Raw`, `Path`	`Path`	If `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.
23	`CA-Certificate`	String		`null`	No	The 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:

Type	Description	Example
`Base64`	Enter 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. See Example using Base64 Certificate Strings	`LS0tLSWo5STV6VlprUGZLDQpzb2FzNmpn` … `otLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0t`
`Raw`	Enter 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. See Example using Raw Certificate Strings	`-----BEGIN CERTIFICATE-----\nMIIDWjCCAkKgAwIBAgI` … `vW3g8wRr6lzmvqJNeBYhg==\n-----END CERTIFICATE-----`
`Path`	Enter the path to a certificate file in the containers. For this mode, supply the certificate file using volume mounts or Docker secrets. See Example using Path to Certificate Files	`/run/secrets/clientcert.pem`

Example: 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"
       }
     }
   }
 }

Example: 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-----"
       }
     }
   }
 }

Example: 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 are using certificate files, you can mount them using volume mounts.

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

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

Add your certificate files to the directory.

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

Next Steps

After setting up the OPA, you can complete the additional setup steps in the order of your choosing. Depending on your progress so far, you may have already completed some of the following. Finish any of the steps below that you haven't done yet:

Configure MQTT subscriptions: Declare the topics the OPA listens to and how it decodes their payloads into sensors. For more information, see Configure MQTT Subscriptions.
Map your tags to assets: Use smart tag mapping to connect your MQTT tags to meters and assets in MaintainX. For more information, see Smart Tag Mapping for OT Data.

TLS Settings Fields​

Certificate Modes​

Example: Base64 Certificate Strings​

Example: Raw Certificate Strings​

Example: Path to Certificate Files​

Additional On-Premise Agent setup when using Certificate Files​

Next Steps​