Provisioning with Azure IoT Hub

You can use Azure IoT Hub Device Provisioning Service (DPS) to issue certificates and register devices.

Even you have multiple devices to provision, you only need to perform Steps 1-4 once. After step 4 is completed, each device using Soracom IoT SIMs and Krypton can be provisioned with the DPS simply by following Step 5: Set the group of IoT SIM. Provisioned devices can send and receive data to and from Azure IoT Hub (IoT Hub) via MQTTS.

Prerequisites

Before using Krypton, please complete the following tasks.

  1. Create a Soracom account
  2. Purchase IoT SIM and device
  3. Prepare a Microsoft Azure account

Step 1: Create an Azure IoT Hub and DPS

Prepare the necessary resources for Microsoft Azure Portal. For more information, see Quickstart: Set up the IoT Hub Device Provisioning Service with the Azure portal.

  1. Create a resource group and create an IoT Hub.

    For more information, see the Microsoft document: Create an IoT hub.

    Note the name of the resource group and IoT Hub. The name of created resource group and IoT Hub are required to confirm the data sent to the IoT Hub using MQTT.
    The resource group name will henceforth be denoted ${resource_group_name}. Example: resource-group
    The IoT Hub name will henceforth be denoted ${iot_hub_name}. Example: iot-hub

  2. Create a DPS under the resource group created in [1].

    For more information, see the Microsoft document: Create a new IoT Hub Device Provisioning Service.

  3. Open the DPS configuration page created in [2] and link the IoT Hub created in [1].

    For more information, see the Microsoft document: Link the IoT hub and your Device Provisioning Service.

Prepare X.509 CA certificate

Purchase an X.509 CA certificate from a trusted root certificate authority. If you have purchased an X.509 CA certificate from a public root certificate authority, follow their instructions for configuration.

You can use your own X.509 CA certificate but only for test purposes. For instructions on how to issue your own X.509 CA certificate, refer to the Microsoft document: Tutorial: Using Microsoft-supplied scripts to create test certificates. The test certificate created in this step has a hard-coded password ("1234") and expires after 30 days.

Please use your own X.509 CA certificate only for testing and verification purposes. After the verification, purchase an X.509 CA certificate from a trusted root certificate authority to use Krypton in a production environment.

  • The private key of an Intermediate CA certificate created at the Microsoft tutorial cannot be used with Krypton. Delete the password from ./private/azure-iot-test-only.intermediate.key.pem created in the Microsoft document: Step 2 - Create certificates.

    1. Execute the following command
      openssl rsa -in ./private/azure-iot-test-only.intermediate.key.pem \
      > -out ./private/azure-iot-test-only.intermediate.nopass.key.pem

      The following will be displayed.

      Enter pass phrase for ./private/azure-iot-test-only.intermediate.key.pem:
    2. Enter "1234" and press Enter key. The following will be displayed.
      writing RSA key

      ./private/azure-iot-test-only.intermediate.nopass.key.pem will be saved.

  • Unlike the steps in the tutorial, you will not upload the key to the IoT Hub.

You need the following credentials to use Krypton with Azure IoT Hub.

Credentials Description
Root CA Certificate The X.509 CA certificate of the root certification authority signing the device certificate. If you created the certificate using the Bash script in Microsoft's tutorial, it is ./certs/azure-iot-test-only.root.ca.cert.pem created in the Microsoft document: Step 2 - Create Certificate.
In the steps that follow, you will upload it to the DPS *1 and the Soracom User Console credentials Sets *2.
Intermediate CA Certificate The X.509 CA certificate of the intermediate certification authority signing the device certificate. If you created the certificate using the Bash script in Microsoft's tutorial, it is ./certs/azure-iot-test-only.intermediate.cert.pem created in the Microsoft document: Step 2 - Create Certificate.
In the steps that follow, you will upload it to the DPS group enrollment *3 and the Soracom User Console credentials Sets *2.
Intermediate CA Certificate Private Key The private key of the X.509 CA certificate of the intermediate certification authority signing the device certificate. If you created the key using the Bash script in the Microsoft tutorial and deleted the password, it is ./private/azure-iot-test-only.intermediate.nopass.key.pem.
In the steps that follow, you will upload it to the Soracom User Console Credential Sets *2.

*1 For details, see Register the root CA certificate with DPS.
*2 For details, see Step 3: Register to Soracom Credential Sets.
*3 For details, see Add an enrollment group to the DPS.

Step 2: Configure DPS

Configure the DPS and gather the necessary information to use Krypton.

Register the root CA certificate with DPS

  1. Go to the Microsoft Azure Portal and find Azure IoT Hub Device Provisioning Service > DPS created in Step 1.

  2. Click on Settings > Certificates > + Add.

  3. Set the following items

    Item Description
    Certificate Name Enter any string to identify the root CA certificate. Example: Azure-IoT-Hub-CA-Cert-Test-Only-Root
    Certificate .pem or .cer file. Select the root CA certificate. If you created the certificate using the Bash script in Microsoft's tutorial, it is ./certs/azure-iot-test-only.root.ca.cert.pem created in the Microsoft document: Step 2 - Create Certificate.
    Set certificate status to verified on upload Enabled
  4. Click Save.

Add an enrollment group to the DPS

Add an enrollment group and register the intermediate CA certificate. When provisioning devices, the DPS will issue device certificates signed with the intermediate CA certificate registered in the enrollment group.

  1. Go to the Microsoft Azure Portal and find Azure IoT Hub Device Provisioning Service > DPS created in Step 1.

  2. Click on Settings > Manage enrollments > + Add enrollment group.

  3. Set the following items

    Item Setting
    Group name Enter any name to identify the enrollment group. Example: enrollment-group
    Attestation Type Select "Certificate".
    IoT Edge device Select "False". However, if you want to notify the IoT Hub that the device you are registering is an Azure IoT Edge device, select "True".
    Certificate Type Select "Intermediate Certificate".
    Primary Certificate .pem or .cer file Select the intermediate CA certificate file. If you created the certificate using the Bash script in Microsoft's tutorial, it is ./certs/azure-iot-test-only.intermediate.cert.pem created in the Microsoft document: Step 2 - Create Certificate.
  4. Click Save.

Add a shared access policy for DPS

When provisioning devices, Krypton will use the policy to register them. In the step that follows, you will register the shared access policy as Azure IoT credentials in the Soracom Credential Sets.

  1. Go to the Microsoft Azure Portal and find Azure IoT Hub Device Provisioning Service > DPS created in Step 1.

  2. Click on Settings > Shared access policies > +Add.

  3. Set the following items

    Item Description
    Name Enter any name to identify the shared access policy. The shared access policy name specified here will henceforth be denoted ${shared_access_policy_name}. Example: shared-access-policy
    Permissions Check “Enrollment write”. When checked, the checkboxes for “Enrollment read”, “Registration status read”, and “Registration status write” are also checked.
  4. Click Save.

    A shared access policy is created.

  5. Click on the created shared access policy.

  6. Click “Copy to clipboard” for the primary key to copy it.

    The primary key will henceforth be denoted ${primary_key}.

Note other information to use Krypton

To use Krypton, the following information for DPS is also required.

  1. Go to the Microsoft Azure Portal and find Azure IoT Hub Device Provisioning Service > DPS created in Step 1.

  2. Click on Overview and copy the following items

    Item Description
    Global device endpoint Global device endpoints will henceforth be denoted as ${global_device_endpoint}. Example: global.azure-devices-provisioning.net
    ID Scope ID Scope will henceforth be denoted as ${id_scope}. Example: 0ne0xxxxxxxxx

Step 3: Register to Soracom Credential Sets

Once your Azure account has been configured using the above steps, you will have the following information:

You can then set this information to credential sets using the Krypton Configuration - Register Credentials - Azure IoT Hub documentation.

Step 4: Enable and configure Krypton in the Soracom Console

Once you also configured the credential sets, you will have the following information.

You can then set this information to group configuration using the Krypton Configuration - Configure the Group documentation.

Step 5: Set the group of IoT SIM

Set the IoT SIM to the group configured in Step 4. Refer to Group basic usage documentation for setting the group.

Step 6: Connect devices to Azure

Now you are ready to provision devices using IoT SIM and Krypton. Next, provision the device.

The setup procedure varies depending on the Krypton authentication method.

Authenticate using Soracom Air for Cellular

This document provides instructions for using the following OS and software. When using other OSs or software, please configure them according to your environment.

  • OS: Linux-based OS such as Raspberry Pi
  • Programs: curl, jq

Authentication using Soracom Air for cellular invokes Soracom Krypton's API from the device using the IoT SIM. You use the following two APIs.

Log in to the device using the IoT SIM from serial, from the local network, or by using Soracom Napter.

  1. Register Azure IoT Hub devices with the registerAzureIotDevice API.

    OPERATION_ID=$(curl -v -X POST https://krypton.Soracom.io:8036/v1/provisioning/azure/iot/register \
    > -H "Content-Type: application/json" \
    > | jq -r .operationId \
    > )
    echo $OPERATION_ID

    You will see the following.

    x.xxxxxxxxxxxxxx.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The {OPERATION_ID} obtained here is used to obtain the credentials for the Azure IoT Hub device.

  1. Retrieve credentials for Azure IoT Hub with getAzureIotDeviceRegistrationStatus API.

    JSON_RESPONSE=$(curl -v https://krypton.Soracom.io:8036/v1/provisioning/azure/iot/registrations/${OPERATION_ID})
    echo $JSON_RESPONSE

    You will see the following.

    {
      "rootCaCertificate": "-----BEGIN CERTIFICATE-----\\nMIIDj...qYzmp\\n-----END CERTIFICATE-----\\n",
      "certificate": "-----BEGIN CERTIFICATE-----\\nMIIC4...sBHoE\\n-----END CERTIFICATE-----\\n",
      "privateKey": "-----BEGIN PRIVATE KEY-----\\nMIIEv...BPw==\\n-----END PRIVATE KEY-----\\n",
      "deviceId": "myDevice-29505xxxxxxxxxx",
      "operationId": "5.4e0fe...20175",
      "status": "assigned",
      "host": "iot-hub.azure-devices.net"
    }

    Depending on the status parameter in the getAzureIotDeviceRegistrationStatus response, the next steps will vary. If a value other than assigned is returned, credentials cannot be obtained.

    Parameter Value The status and next Step
    assigned The device has been successfully registered. You can connect to the IoT Hub using the credentials in the other response parameters.
    assigning Device is being registered. Call getAzureIotDeviceRegistrationStatus API again after intervals.
    Others Failed to register device. Call registerAzureIotDevice API again. If it still fails, review the Soracom and Azure settings.

    The same OPERATION_ID can be used to obtain credentials only once. To obtain the credentials again, start with registerAzureIotDevice API.

  2. Save the getAzureIotDeviceRegistrationStatus API response value to a file or variable.

    value Description
    rootCaCertificate Save the value (-----BEGIN CERTIFICATE-----\nMIIDj.. .qYzmp\n-----END CERTIFICATE-----\n) with the file name rootCaCertificate.pem. *1
    certificate Save the value (-----BEGIN CERTIFICATE-----\nMIIC4.... .sBHoE\n-----END CERTIFICATE-----\n) with the file name certificate.pem. *1
    privateKey Save the value (-----BEGIN PRIVATE KEY-----\nMIIEv. .BPw===\n-----END PRIVATE KEY-----\n) with a file name of privatekey.pem. *1
    deviceId Device Name. It will henceforth be denoted as ${device_id}. Example: myDevice-29505xxxxxxxxxxxxxx.
    host Host Name of Azure IoT Hub. It will henceforth be denoted as ${iot_hub_hostname}. Example: iot-hub.azure-devices.net.

    *1 Convert \n to newline.

    If the jq command is installed on the device, the following commands can be used to save to a file or variable.

    echo $JSON_RESPONSE | jq -r ".rootCaCertificate" | sed -e 's/\\n/\\n/g' > rootCaCertificate.pem
    echo $JSON_RESPONSE | jq -r ".certificate" | sed -e 's/\\n/\\n/g' > certificate.pem
    echo $JSON_RESPONSE | jq -r ".privateKey" | sed -e 's/\\n/\\n/g' > privatekey.pem
    device_id=$(echo $JSON_RESPONSE | jq -r ".deviceId")
    iot_hub_hostname=$(echo $JSON_RESPONSE | jq -r ".host")

Authenticate using Soracom Endorse

This document provides instructions for using the following OS and software. When using other OSs or software, please configure them according to your environment.

  • OS: Linux-based OS such as Raspberry Pi
  • Programs: jq

When using SIM authentication with Soracom Endorse, please confirm the following conditions.

  1. Download one of the following and setup

    • For the Java version of the CLI tool, use soracom-krypton-client-for-java. Install the appropriate Java runtime environment for your environment in advance.
    • For the Go language version of the CLI tool, go to krypton-client-go and download the appropriate binary file for your environment.

Following is the example for krypton-client-go.

  1. Register Azure IoT Hub devices with the registerAzureIotDevice operation.

    OPERATION_ID=$(krypton-cli -operation registerAzureIotDevice \
    > | jq -r .operationId \
    > )
    echo $OPERATION_ID

    You will see the following.

    x.xxxxxxxxxxxxxx.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The {OPERATION_ID} obtained here is used to obtain the credentials for the Azure IoT Hub device.

  1. Retrieve credentials for Azure IoT Hub with getAzureIotDeviceRegistrationStatus operation.

    JSON_RESPONSE=$(krypton-cli -operation getAzureIotDeviceRegistrationStatus -params "{\"operationId\":\"${OPERATION_ID}\"}")
    echo $JSON_RESPONSE

    You will see the following.

    {
      "rootCaCertificate": "-----BEGIN CERTIFICATE-----\\nMIIDj...qYzmp\\n-----END CERTIFICATE-----\\n",
      "certificate": "-----BEGIN CERTIFICATE-----\\nMIIC4...sBHoE\\n-----END CERTIFICATE-----\\n",
      "privateKey": "-----BEGIN PRIVATE KEY-----\\nMIIEv...BPw==\\n-----END PRIVATE KEY-----\\n",
      "deviceId": "myDevice-29505xxxxxxxxxx",
      "operationId": "5.4e0fe...20175",
      "status": "assigned",
      "host": "iot-hub.azure-devices.net"
    }

    Depending on the status parameter in the getAzureIotDeviceRegistrationStatus response, the next steps will vary. If a value other than assigned is returned, credentials cannot be obtained.

    Parameter Value The status and next Step
    assigned The device has been successfully registered. You can connect to the IoT Hub using the credentials in the other response parameters.
    assigning Device is being registered. Call getAzureIotDeviceRegistrationStatus API again after intervals.
    Others Failed to register device. Call registerAzureIotDevice API again. If it still fails, review the Soracom and Azure settings.

    The same OPERATION_ID can be used to obtain credentials only once. To obtain the credentials again, start with registerAzureIotDevice API.

  2. Save the getAzureIotDeviceRegistrationStatus response value to a file or variable.

    value Description
    rootCaCertificate Save the value (-----BEGIN CERTIFICATE-----\nMIIDj.. .qYzmp\n-----END CERTIFICATE-----\n) with the file name rootCaCertificate.pem. *1
    certificate Save the value (-----BEGIN CERTIFICATE-----\nMIIC4.... .sBHoE\n-----END CERTIFICATE-----\n) with the file name certificate.pem. *1
    privateKey Save the value (-----BEGIN PRIVATE KEY-----\nMIIEv. .BPw===\n-----END PRIVATE KEY-----\n) with a file name of privatekey.pem. *1
    deviceId Device Name. It will henceforth be denoted as ${device_id}. Example: myDevice-29505xxxxxxxxxxxxxx.
    host Host Name of Azure IoT Hub. It will henceforth be denoted as ${iot_hub_hostname}. Example: iot-hub.azure-devices.net.

    *1 Convert \n to newline.

    If the jq command is installed on the device, the following commands can be used to save to a file or variable.

    echo $JSON_RESPONSE | jq -r ".rootCaCertificate" | sed -e 's/\\n/\\n/g' > rootCaCertificate.pem
    echo $JSON_RESPONSE | jq -r ".certificate" | sed -e 's/\\n/\\n/g' > certificate.pem
    echo $JSON_RESPONSE | jq -r ".privateKey" | sed -e 's/\\n/\\n/g' > privatekey.pem
    device_id=$(echo $JSON_RESPONSE | jq -r ".deviceId")
    iot_hub_hostname=$(echo $JSON_RESPONSE | jq -r ".host")

Verify devices in Azure IoT Hub

Verify that the device has been added to the Azure IoT Hub.

  1. Go to the Microsoft Azure Portal and find Azure IoT Hub > Azure IoT Hub created in Step 1.

  2. Click on Device Management > Devices.

  3. Verify that there is a device with ${device_id} (e.g. myDevice-29505xxxxxxxxxxxx).

Communicate with IoT Hub using MQTT

Send data to IoT Hub

Use MQTT to send data from devices using the IoT SIM to the Azure IoT Hub.

In this document, data is sent from the device using Mosquitto client and monitored on the PC using Azure CLI + Azure IoT extension for Azure CLI.

  1. Install the Mosquitto client on the device that is using the Soracom IoT SIM.

    sudo apt-get install mosquitto-clients
  2. Install Azure CLI on your PC.

    For more information, refer to the Microsoft document: How to Install the Azure CLI.

  3. Monitor the data on the PC.

    ${iot_hub_name} and ${resource_group_name} are the names of the IoT Hub and Resource Group created in Step 1: Create an Azure IoT Hub and DPS.

    az iot hub monitor-events -n ${iot_hub_name} -g ${resource_group_name}

    You will see the following.

    Starting event monitor, use ctrl-c to stop...
  4. Send data from the device.

    The ${iot_hub_hostname} and ${device_id} values are taken from Step 6: Register and connect devices to the IoT Hub using Krypton.

    mosquitto_pub -d -h ${iot_hub_hostname} -p 8883 \
    > --cafile ./rootCaCertificate.pem \
    > --cert ./certificate.pem \
    > --key ./privatekey.pem \
    > -i ${device_id} -u "${iot_hub_hostname}/${device_id}/?api-version=2021-04-12" \
    > -t "devices/${device_id}/messages/events/" \
    > -m '{
    > "message": "Hello from Device with Krypton"
    > }'

    You will see the following.

    Client myDevice-29505xxxxxxxxxx sending CONNECT
    Client myDevice-29505xxxxxxxxxx received CONNACK (0)
    Client myDevice-29505xxxxxxxxxx sending PUBLISH (d0, q0, r0, m1, 'devices/myDevice-29505xxxxxxxxxx/messages/events/', ... (45 bytes))
    Client myDevice-29505xxxxxxxxxx sending DISCONNECT

    In addition, the PC displays the following to confirm that data is being sent to the IoT Hub.

        {
            "event":
                {
                    "origin": "myDevice-29505xxxxxxxxxx",
                    "module": "",
                    "interface": "",
                    "component": "",
                    "payload": "{\\"message\\": \\"Hello from Device with Krypton\\"}"
                }
        }

Receive data from IoT Hub

Using MQTT, data sent from the IoT Hub is received by devices that are using the IoT SIM.

To send data to devices, IoT Hub must be in Free or Standard tier.

  1. Start Subscribe for data on the device.

    mosquitto_sub -d -h ${iot_hub_hostname} -p 8883 \
    > --cafile ./rootCaCertificate.pem \
    > --cert ./certificate.pem \
    > --key ./privatekey.pem \
    > -i ${device_id} -u "${iot_hub_hostname}/${device_id}/?api-version=2021-04-12" \
    > -t "devices/${device_id}/messages/devicebound/#"

    You will see the following.

    Client myDevice-29505xxxxxxxxxx sending CONNECT
    Client myDevice-29505xxxxxxxxxx received CONNACK (0)
    Client myDevice-29505xxxxxxxxxx sending SUBSCRIBE (Mid: 1, Topic: devices/myDevice-29505xxxxxxxxxx/messages/devicebound/#, QoS: 0)
    Client myDevice-29505xxxxxxxxxx received SUBACK
    Subscribed (mid: 1): 0
  2. Go to the Microsoft Azure Portal and find Azure IoT Hub > IoT Hub created in Step 1.

  3. Click on Device Management > Devices, then click on ${device_id}.

  4. Click Message to Device, type "Hello from Azure Portal!" in Message Body, and click Send Message.

    Data sent from the IoT Hub is received by the device.

    Client myDevice-29505xxxxxxxxxx received PUBLISH (d0, q0, r0, m0, 'devices/myDevice-29505xxxxxxxxxx/messages/devicebound/%24.to=%2Fdevices%2FmyDevice-29505xxxxxxxxxx%2Fmessages%2FdeviceBound&%24.ct=text%2Fplain%3B%20charset%3DUTF-8&%24.ce=utf-8', ... (24 bytes))
    Hello from Azure Portal!

Optional: delete device

If the device is no longer needed or if you want to deactivate the device's credentials, remove the device from the Azure IoT Hub.

  1. Go to the Microsoft Azure Portal and find Azure IoT Hub > IoT Hub created in Step 1.

  2. Click on Device Management > Devices

  3. Check the devices to be deleted and click on Delete > Yes.

Removing a device from the IoT Hub will invalidate the credentials created by Krypton. To reconnect, perform step 6.