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.

注記

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. ［新しいディビジョンの作成］を選択します。

  3. ディビジョンの［名前］と、オプションで説明を入力します。

  4. ［ランデブーゾーン］セクションにあるドロップダウンから［プライマリーゾーン］を選択します。

  5. （オプション）バックアップとして、［ランデブーゾーン］セクションにあるドロップダウンから［セカンダリーゾーン］を選択します。

  6. ［新しいディビジョンの作成］をクリックします。

Create a certificate profile:

  1. ［Device Trust Manager］メニューで、［証明書管理］>［証明書プロファイル］を選択します。

    Learn more about Certificate profiles in Device Trust Manager.

  2. ［証明書プロファイルの作成］をクリックします。

  3. 証明書プロファイルの［名前］を入力します。

  4. CA ソースとして DigiCert ONE を使用するか、リストから選択します。

  5. ［テンプレート］セクションで、要件に応じて［エンドエンティティ］または［中間 CA］を選択します。

  6. 証明書プロファイルが使用する証明書テンプレートを選択します。設定可能なカスタムフィールドオプションは、選択したテンプレートに基づいて読み込まれます。

    注記

  7. どのディビジョンがこの証明書プロファイルを使用できるかを選択します。

    1. すべてのディビジョン: 証明書プロファイルは、アカウント内の全ディビジョンが使用できるため、アカウント全体のプロファイルとなります。

    2. 特定のディビジョン: 証明書プロファイルにアクセスできるディビジョンを 1 つ以上選択します。このプロフィールは、選ばれたディビジョンにのみ公開されます。

  8. ［証明書に含めるカスタムフィールド］で、必要に応じてフィールドを設定します。たとえば、コモンネームを有効にして必須に設定し、デフォルト値を指定することができます。

  9. ［作成］を選択して証明書プロファイルを保存します。

Create a certificate management policy:

  1. ［証明書管理ポリシーの作成］を選択します。

    Learn more about Certificate management policies in Device Trust Manager.

  2. Select Create certificate management policy.

  3. 証明書管理ポリシーの［名前］を入力します。

  4. ポリシーを割り当てる［ディビジョン］を選択します。

  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. ［次へ］を選択して証明書の設定に進みます。

  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. 利用可能なオプションから［発行 CA］を選択します。このポリシーに基づいて発行される証明書に署名する認証局。

    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. ［次へ］をクリックします。

  13. ［終了］を選択して、証明書管理ポリシーを作成します。

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. ［Device Trust Manager］メニューから［証明書管理］を選択します。

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

  3. ［デバイスグループ］ドロップダウンメニューから、適切なデバイスグループを選択します。

  4. ［証明書管理ポリシー］ドロップダウンメニューから、そのデバイスグループに関連付けられている証明書管理ポリシーを選択します。

  5. 鍵生成タイプのステップでの操作:

    注記

    デバイスグループと証明書管理ポリシーの選択に基づいて、鍵生成タイプのオプションが表示されます。

    1. 鍵ペアを持っており、リクエストの中で CSR または公開鍵を提供します:

      • デバイスデータを含む CSV ファイルまたは zip 圧縮された CSV をアップロードします。書式については、提供されているテンプレートをダウンロードしてご確認ください。

    2. 鍵ペアはこのアプリケーションによってサーバー側で生成され、秘密鍵と証明書はレスポンスに含まれます:

      • ［鍵生成タイプ］ドロップダウンメニューを選択します。

  6. 証明書の［コモンネーム］を入力します。

  7. オプションで組織名を入力します。

  8. ［値の追加］をクリックして、組織単位の値を入力します（オプション）。

  9. ［説明］を入力します（オプション）。

  10. ［証明書リクエストの提出］をクリックします。

  11. Save the password.

  12. 証明書リクエストが正常に送信されたら、証明書をダウンロードします。

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.

注記

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
このセクションの内容: