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.

Create a Soracom account
Purchase IoT SIM and device
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.

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
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.
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

Go to the Microsoft Azure Portal and find Azure IoT Hub Device Provisioning Service > DPS created in Step 1.
Click on Settings > Certificates > + Add.

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

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.

Go to the Microsoft Azure Portal and find Azure IoT Hub Device Provisioning Service > DPS created in Step 1.
Click on Settings > Manage enrollments > + Add enrollment group.

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.

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.

Go to the Microsoft Azure Portal and find Azure IoT Hub Device Provisioning Service > DPS created in Step 1.
Click on Settings > Shared access policies > +Add.

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.

Click Save.

A shared access policy is created.
Click on the created shared access policy.
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.

Global device endpoint
ID Scope

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

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:

Shared access policy
- Access policy's name: Denoted as ${shared_access_policy_name} above
- Access policy's primary key: Denoted as ${primary_key} above
X.509 certificates
- Intermediate CA Certificate Private Key: In the Microsoft tutorial, it is ./private/azure-iot-test-only.intermediate.nopass.key.pem
- Intermediate CA Certificate: In the Microsoft tutorial, it is ./certs/azure-iot-test-only.intermediate.cert.pem
- Root CA Certificate: In the Microsoft tutorial, it is ./certs/azure-iot-test-only.root.ca.cert.pem

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.

Global device endpoint: Denoted as ${global_device_endpoint} above
X.509 credentials name: Configured in Step 3
Azure IoT credentials name: Configured in Step 3
ID scope: Denoted as ${id_scope} above

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.

Authentication using Soracom Air's cellular connection
Authentication by Soracom Endorse

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.

registerAzureIotDevice: Register Azure IoT Hub devices
getAzureIotDeviceRegistrationStatus: retrieve credentials for registered Azure IoT Hub devices

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.

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.

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.

Use of SIM card reader or USB dongle Soracom has confirmed that the following devices can be used
- Soracom Onyx LTE™ USB Modem SC-QGLC4-C1
- MS2131i-8 (Huawei USB Dongle)
- Gemalto Card Reader USB-TR HWP119316 (Card Reader)

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.

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.

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.

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.

Go to the Microsoft Azure Portal and find Azure IoT Hub > Azure IoT Hub created in Step 1.
Click on Device Management > Devices.
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.

Install the Mosquitto client on the device that is using the Soracom IoT SIM.
```
sudo apt-get install mosquitto-clients
```
Install Azure CLI on your PC.

For more information, refer to the Microsoft document: How to Install the Azure CLI.
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...
```

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.

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

Go to the Microsoft Azure Portal and find Azure IoT Hub > IoT Hub created in Step 1.
Click on Device Management > Devices, then click on ${device_id}.

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.

Go to the Microsoft Azure Portal and find Azure IoT Hub > IoT Hub created in Step 1.
Click on Device Management > Devices
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.