Connecting to Azure IoT Hub

Configure an Azure IoT Device

This section assumes that you have a Microsoft Azure account and have created an “IoT Hub” resource. Before the MQTT connector can send data to the IoT Hub, a “Device” needs to be configured as a recipient of such data. In this example, a single “Device” with self-signed X509 certificate authentication is created:

  1. Go to your IoT Hub in the Azure portal; note down the “Hostname” for your IoT Hub.
  2. On the left, under “Device management”, select “Devices”.
  3. Click on “Add Device”.
  4. Enter a name for the device as the device ID, for example “mqttconnector1”.
  5. As the “Authentication type”, select “X509 Self Signed” or, preferably, “X509 CA Signed”. For CA (Certificate Authority) signed certificates ensure that you have a CA certificate configured in IoT Hub.
  6. Create an MQTT Client in Dataristix, go to the client’s “Configuration” node, select the “Client Certificate” tab, and click on the “Copy thumbprint” toolbar button.
  7. Back in Azure, paste the thumbprint as the primary and secondary thumbprint in the “Create a device” form.
  8. Leave “Connect this device to an IoT hub” enabled and click “Save” to create the device.

Trust the IoT Hub Certificate Authority

Certificates installed as trusted roots on the operating system are not automatically trusted by MQTT clients. Certificate authorities that should be trusted must be added to the MQTT connector’s Certificate Authority settings.

Azure IoT Hub server certificates are issued by the “DigiCert Global Root G2” certificate authority. Obtain this certificate directly from DigiCert rather than exporting it from a TLS connection in the browser, so that you can be sure the certificate has not been substituted along the way:

  1. Download the certificate in PEM format from DigiCert’s list of root certificates at https://www.digicert.com/kb/digicert-root-certificates.htm. Locate “DigiCert Global Root G2” and download the “PEM” file, or download it directly from https://cacerts.digicert.com/DigiCertGlobalRootG2.crt.pem.

  2. Verify the downloaded certificate before importing it. On Windows, double-click the file, select the “Details” tab and compare the “Thumbprint” (shown by Windows as the SHA-1 value) with the value published on the DigiCert page.

    Alternatively, if OpenSSL is available, run:

    openssl x509 -in DigiCertGlobalRootG2.crt.pem -noout -subject -enddate -fingerprint -sha256

    Do not import the certificate if the thumbprint does not match.

  3. In Dataristix, open the MQTT connector’s root configuration settings and, under “Certificate Authority”, click the “Add” toolbar button. Select the downloaded file as the certificate file and leave the key file blank; the certificate authority’s private key is not needed to trust server certificates.

  4. Confirm that “DigiCert Global Root G2” is now listed as a certificate authority.

Note

The “DigiCert Global Root G2” certificate is valid until 2038, so this step normally needs to be done only once. Microsoft publishes the root certificate authorities used by Azure services at Azure Certificate Authority details. Should Microsoft change the root certificate authority for IoT Hub in future, obtain the new root certificate from the issuing certificate authority’s website in the same way.

Configure the MQTT client

You can configure the MQTT client manually to connect to the Azure IoT Hub or with “IoT Assistance”. The following steps describe the steps taken when choosing “IoT Assistance”.

Select the “Configuration” node of the MQTT client to configure in the navigation panel, then click the “IoT Assistance” button in the toolbar.

../_images/mqtt-client-iot-assistance.png

Select the “Azure” option int the dialog that opens.

../_images/mqtt-client-iot-assistance-dlg1.png

Click “Next” and fill out the details in the following form.

../_images/mqtt-client-iot-assistance-dlg3.png

Enter the IoT connection details:

( 1 ) The hostname of your IoT hub.

( 2 ) The device ID configured in IoT hub.

Finally, click “Finish” ( 3 ) to configure the MQTT client.

You can now review the settings and test the connection.

Note

Test the connection using the actual MQTT client ID, not a randomized client ID. If the connection fails because the Azure IoT server certificate is not trusted, ensure that the certificate authority has been added as described in Trust the IoT Hub Certificate Authority. For testing purposes only, you can also check “Accept any server certificate” in the MQTT client configuration.

Limitations

MQTT support of Azure IoT hub devices is limited and generally MQTT topics cannot be freely chosen. If you plan to publish values to IoT hub then MQTT topics should take on the form

devices/{device id}/messages/events/{tag}

The MQTT connector supports “Custom Topic Paths” in the MQTT client’s topic settings for this purpose. For example, in a generic “Publish” topic the custom topic path could be configured as

devices/mqttconnector1/messages/events/

to send tag values to the IoT hub. A tag called “temperature” that is connected to the MQTT “Publish” topic in Tasks would then have the tag value published as

devices/mqttconnector1/messages/events/temperature