Skip to main content

Integrate with Microsoft Azure IoT Hub

Microsoft Azure IoT Hub is a popular messaging service for connecting devices to cloud-based IoT solutions. Devices can send or receive messages from IoT Hub using the MQTT 3.1.1 protocol.

The Azure IoT Hub supports device authentication using mutual TLS (mTLS), using either X.509 thumbprint authentication or X.509 CA authentication. Learn more.

This tutorial describes how to configure DigiCert​​®​​ Device Trust Manager to issue x.509 device certificates and use them for mutual TLS (mTLS) authentication with the Azure IoT Hub using x.509 CA authentication over MQTT 3.1.1 protocol.

Note

This tutorial uses DigiCert​​®​​ TrustEdge MQTT client to perform mTLS from a device to Azure IoT Hub. However, you can use any MQTT 3.1.1 client of your choice.

What you will accomplish

By completing this tutorial, you will:

  • Configure Device Trust Manager to issue device certificates

  • Set up Azure IoT Hub with X.509 CA authentication

  • Issue certificates to test IoT devices

  • Establish secure mTLS connections between devices and Azure IoT Hub

  • Verify successful authentication using the MQTT protocol

Before you begin

Before starting this tutorial, ensure you have the following resources and access:

Access and accounts:

  • Azure subscription: An active Azure account with permissions to create IoT Hub resources. The free tier is sufficient for testing

    Contact your company’s Azure subscription administrator to create an Azure login with sufficient permissions to create an Azure IoT Hub resource.

  • DigiCert® ONE account: Your DigiCert® ONE account must have the Solution Administrator role in Device Trust Manager

    Contact your DigiCert​​®​​ account representative to set up your DigiCert® ONE account.

  • Device Trust Manager account: An active Device Trust Manager account

    Contact your DigiCert account representative to provide you with a user account with the Solution Administrator role in Device Trust Manager.

  • Certificate Authority: A Root CA and an Intermediate CA configured in Device Trust Manager for issuing certificates

Hardware and software:

  • IoT test device: A physical or virtual machine running Ubuntu 22.04 or later

  • TrustEdge MQTT client: Installed on a test device for performing mTLS authentication

  • OpenSSL: Command-line tool for certificate operations (included with Ubuntu).

Documentation:

Review the following documents before proceeding:

Set up a test device

Configure a Linux-based test device that acts as your IoT device throughout this tutorial. For this tutorial, we use a virtual or physical machine running Ubuntu 22.04 LTS. We refer to this device as TestIoTDevice01 throughout this documentation.

  1. Log in to your test device (TestIoTDevice01) using SSH or direct console access.

  2. Download and install TrustEdge on the device.

Set up Device Trust Manager

To perform this action, you must have a user role that contains the Solution administrator permission.

Sign in:

  1. Sign in to DigiCert ONE.

  2. In the Managers (grid icon) menu, select Device Trust.

Create a division:

  1. In the Device Trust Manager menu, go to Divisions.

    Learn more about Divisions in Device Trust Manager.

  2. Select Create division.

  3. Enter a Name for the division and, optionally, a description.

  4. Select a Primary zone from the dropdown under the Rendezvous zones section.

  5. (Optional) Select a Secondary zone from the dropdown under the Rendezvous zones section as a backup.

  6. Click Create new division.

Create a certificate profile:

  1. In the Device Trust Manager menu, go to Certificate management > Certificate profiles.

    Learn more about Certificate profiles in Device Trust Manager.

  2. Click Create certificate profile.

  3. Enter a Name for the certificate profile.

  4. Use DigiCert ONE as the CA source, or choose one from the list.

  5. Under Template, select either End entity or Intermediate CA, depending on your requirement.

  6. Choose a certificate template that this certificate profile will use. Configurable custom field options are loaded based on your chosen template.

    Note

  7. Select which divisions can use the certificate profile.

    1. All divisions: The certificate profile is available for use by all divisions in the account, making it an account-wide profile.

    2. Specific divisions: Select one or more divisions that should have access to the certificate profile. The profile will only be available to the chosen divisions.

  8. Under Custom fields to include in certificate, configure fields as needed. For example, you could enable the common name, set it as required, and specify a default value.

  9. Select Create to save the certificate profile.

Create a certificate management policy:

  1. In the Device Trust Manager menu, go to Certificate management > Certificate management policies.

    Learn more about Certificate management policies in Device Trust Manager.

  2. Select Create certificate management policy.

  3. Enter a Name for the certificate management policy.

  4. Choose a Division to assign the policy to.

  5. Under the Select the certificate management model, choose Policy will be used for certificate issuance only. Requires an Essentials license.

    The scope of this tutorial is only to implement certificate issuance, not device management; hence, we recommend choosing the above certificate management model.

  6. Under the Certificate management methods select Single certificate request through portal and REST API and register a single device.

    The scope of this tutorial is to request a certificate through the Device Trust Manager portal; hence, we recommend choosing the above certificate management method.

  7. Select Next  to proceed to the certificate settings.

  8. Select the End entity certificate profile you have already created (as part of certificate profile creation).

    The End entity certificate profile defines the certificate structure, including subject fields, extensions, and validity period.

    Optionally, you can also select the default Basic client certificate profile.

  9. Select an Issuing CA from the available options. This is the Certificate Authority that will sign the certificates issued under this policy.

    Learn more about Issuing CA in Device Trust Manager.

  10. Under the Keypair generation settings, select Server-side keypair generation.

  11. Under the Default key type and key size for when DigiCert generates the keypair, select RSA 2048 for the keypair.

    You can choose whether the private key is generated on the device or server-side and delivered to the device in the certificate response. However, considering the scope of this tutorial, we recommend choosing the above methods.

  12. Click Next.

  13. Select Finish to create the certificate management policy.

Download the Issuing CA:

You will need to upload this CA certificate to Azure IoT Hub to establish trust.

  1. In DigiCert® ONE, in the Manager menu (grid at top right), select Private CA.

  2. Under Manage CAs, select Intermediates.

  3. On the Intermediate Certificate Authorities page, find the certificate you want to download.

  4. Click More actions > Download the certificate as a .pem file.

  5. Save the downloaded CA.

Request a device certificate

Issue a device certificate from Device Trust Manager for your test IoT device.

  1. In the Device Trust Manager menu, go to Certificate management > Certificates.

  2. Select Request certificate > Request a certificate for a device.

  3. From the Device Group dropdown menu, select an appropriate device group.

  4. From the Certificate management policy dropdown menu, select the certificate management policy associated with the device group.

  5. On the Key generation type step:

    Note

    The Key generation type option is displayed based on your selection of the Device group and the Certificate management policy.

    1. I have the keypairs and will provide the CSRs or public keys in the request:

      • Upload a CSV file or a zipped CSV containing the device data. You can download the provided template for formatting guidance.

    2. Key pairs will be generated server side by this application, and the private key and certificate will be included in response:

      • Select the Key generation type dropdown menu.

  6. Provide a Common name for the certificate.

  7. Optionally, provide an Organization name.

  8. Click Add Value to provide an organization unit value (optional).

  9. Provide a Description (optional).

  10. Click Submit certificate request.

  11. Save the password.

  12. Download the certificate after successful submission of the certificate request.

Extract the certificate and the private key

Use OpenSSL to extract the certificate and the private key from the downloaded PKCS#12 file.

  1. Extract the certificate:

    Run the following command to extract the certificate. Enter the saved password when prompted for Import Password:

    openssl pkcs12 -in <filename>.pfx -clcerts -nokeys -out device_cert.pem

  2. Extract the encrypted private key:

    Run the following command to extract the private key. Enter the saved password when prompted for Import Password. You will also be prompted to enter a PEM passphrase twice to protect the extracted key; enter the same password for the PEM passphrase also:

    openssl pkcs12 -in <filename>.pfx -nocerts -out device_key_secure.pem

  3. Remove the passphrase from the private key:

    Run the following command to remove the passphrase from the private key. Enter the saved password when prompted to enter a PEM passphrase for the private key:

    openssl rsa -in device_key_secure.pem -out device_key_insecure.pem

  4. Copy the device_cert.pem and device_key_insecure.pem files to your test IoT device.

Set up the Azure IoT Hub

Create and configure an Azure IoT Hub instance to accept X.509 CA-signed device connections:

Create the IoT Hub Resource:

  1. Sign in to the Azure Portal with your Azure subscription credentials.

  2. From the Azure home page, under Azure services, select Create a resource.

  3. In the search box, type IoT Hub.

  4. Select the IoT Hub tile from the search results.

  5. Select Create.

Configure the IoT Hub settings:

  1. Complete the following fields:

    • Subscription: Your Azure subscription details

    • Resource Group: New or existing resource group name

    • IoT Hub Name: Globally unique name for your IoT Hub

    • Tier: Pricing tier

  2. Select Review + create.

  3. Once deployment is complete, select Go to resource.

  4. On the IoT Hub Overview page, locate and copy the Hostname field (for example, myiothub.azure-devices.net). You will need this hostname for device connections.

Upload and verify the CA certificate:

Register the issuing CA certificate on the IoT Hub to enable X.509 CA authentication.

  1. On the IoT Hub navigation bar, under Security settings, select Certificates.

  2. Select Add to upload a new certificate.

  3. Enter a friendly certificate name (for example, Contoso_Issuing_CA).

  4. Browse and select the Issuing CA PEM file you have downloaded.

  5. Enable the option Set certificate status to verified on upload.

  6. Select Save.

Register the device on IoT Hub

Create a device identity on Azure IoT Hub that will authenticate using X.509 CA-signed certificates.

  1. On the Azure IoT Hub management interface, go to Device management > Devices.

  2. Select Add Device.

  3. Enter a name for the Device ID (for example, TestIoTDevice01).

  4. Select X.509 CA Signed for the authentication.

  5. Select Save to create the device.

Your device is now registered and ready to authenticate using its certificate.

Perform mTLS Authentication

Use the MQTT client installed on the device to authenticate with IoT Hub using mTLS over TCP port 8883.

Note

IoT Hub does not support custom MQTT topics. You must use the IoT Hub predefined topic structures. For more information, see Communicate with an IoT hub using the MQTT protocol.

Execute the following command on your test IoT device to establish an mTLS connection and publish a test message to IoT Hub:

trustedge mqtt \
--mqtt_version 3.1.1 \
--mqtt_servername myiothub.azure-devices.net \
--mqtt_pub_topic devices/TestIoTDevice01/messages/events/ \
--mqtt_pub_message "test message" \
--mqtt_port 8883 \
--mqtt_client_id TestIoTDevice01 \
--mqtt_username myiothub.azure-devices.net/TestIoTDevice01/?api-version=2021-04-12 \
--mqtt_transport SSL \
--ssl_key_file device_key_insecure.pem \
--ssl_cert_file device_cert.pem \
--ssl_ca_file DigiCertGlobalRootG2.crt.pem

Command breakdown:

--mqtt_version: MQTT protocol version. It must be set to version 3.1.1

mqtt_servername: IoT Hub hostname in the format of <hostname>.azure-devices.net

--mqtt_pub_topic: MQTT topic for publishing telemetry messages. Must follow IoT Hub's predefined format of devices/<devicename>/messages/events/

--mqtt_pub_message: The message payload to publish to IoT Hub

--mqtt_port: TCP port for secure MQTT connections. It must be set to port 8883

--mqtt_client_id: MQTT client identifier. Must match the <devicename> registered in IoT Hub

--mqtt_username: MQTT username in IoT Hub's required format of <hostname>.azure-devices.net/<devicename>?api-version=2021-04-12

--mqtt_transport: Transport protocol. Must be set to SSL for TLS-encrypted connections.

--ssl_key_file: Path to the device's private key file in PEM format. For example, device_key_insecure.pem file is generated in the above command

--ssl_cert_file: Path to the device's X.509 certificate file in PEM format. For example, device_cert.pem file is generated in the above command

--ssl_ca_file: DigiCert Global Root G2 public root CA used by the IoT Hub azure-devices.net public endpoint.

You can download the DigiCert Global Root G2 public root CA from https://cacerts.digicert.com/DigiCertGlobalRootG2.crt.pem

Expected output:

If mTLS authentication is successful, your output resembles the example below:

SSL Certificate is trusted
Connection Success!
Calling MQTT_publish
Exit flag set...

Use HiveMQ MQTT CLI (alternative client)

The HiveMQ MQTT CLI is an alternative MQTT client that supports X.509 authentication. This example shows the equivalent connection using HiveMQ:

mqtt pub -V 3 \
  -h "myiothub.azure-devices.net" \
  -p 8883 \
  -i "TestIoTDevice01" \
  -u "myiothub.azure-devices.net/TestIoTDevice01/?api-version=2021-04-12" \
  -s \
  --cafile "DigiCertGlobalRootG2.crt.pem" \
  --cert "device_cert.pem" \
  --key  "device_key_insecure.pem" \
  -t "devices/TestIoTDevice01/messages/events/" \
  -m '{"temp":23.4}' \
  -q 1 -d
In this section: