Connect to Azure IoT Hub with Asavie IoT Connect cloud service connectors

Using the following instructions developers can proxy MQTT messages securely to Azure IoT Hub, eliminating the need for certificates on the device.

Prerequisites
The user has:

  • a SIM and data bundle available in Asavie IoT Connect
  • an active Azure account with administration rights
  • Azure IAM Users policy with registryReadWrite, Access key ID and Secret access key (https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-security)
  • a cellular enabled device with the ability to send MQTT messages
  • an Asavie IoT Connect network topology set up for MQTT cloud connectors
  • REST API toolkit e.g. cURL

NOTE: User assigned variables are denoted by <some_variable>, substitute your own values for the indicated variable. The IAM User Access key ID and Secret access key are not stored in Asavie IoT Connect. A security best practice is to delete the Azure IAM user credentials on completion of the provisioning step.

 

1. Obtain an Asavie IoT Connect API and Network key
The Asavie API access and Network key details are available in the Asavie IoT Connect web portal, under the account details menu in the top right-hand corner under the submenu “Access Asavie API”. The portal also shows the Account Key, referred to as the Foreign Account Key <FAK> in the proceeding commands. Listed under the Account Key is the Network Key which is required in steps 4 and 6.

Using https://api.provisioning.asavie.com, obtain a valid security token (active for 60mins) using the API Username::Secret keypair.

From the response note down the access_token which will be used as part of the Authorization: Bearer details for proceeding Asavie API commands.

curl -i -X POST https://api.provisioning.asavie.com/v1/authtoken -d "grant_type=client_credentials&client_id=<AsavieAPIuser>&client_secret=<AsavieAPIsecret>"

 

2. Configure Asavie IoT Connect with Azure IoT Hub endpoint details
Configure the Asavie IoT Connect cloud connector with an Azure IoT Hub endpoint name <AZhubEPname>. Add the Azure IoT Hub address <AZhub> e.g. (iot-hub.azure-devices.net), the target for MQTT data originating from the SIMs.

curl -i -X POST https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/endpoints \
-H "Authorization: Bearer <apiToken>" \
-H "Content-Type: application/json" \
-d '{"Name":"<AZhubEPname>", "Port":8883, "EndpointType":"TLS", "Host": "<AZhub>"}'

 

3. Configure a cloud connector group name, used by Asavie IoT Connect when provisioning Azure IoT Hub credentials
Create the Asavie IoT Connect cloud connector group, this is used to group SIMs that require credentials in Azure IoT Hub. Requires the <AZhubEPname> from the previous step.

curl -i -X POST https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/groups \
-H "Authorization: Bearer <apiToken>" \
-H "Content-Type: application/json" \
-d '{"Name":"<myCloudConnectorGroupName>","EndpointName": "<AZhubEPname>"}'

 

4. Attach SIM details to the Asavie IoT Connect cloud connector group name
Assign an active Asavie IoT Connect SIM phone number <CLI> to the cloud connector group. SIM details are available in the Asavie IoT Connect web portal. Alternatively, use the API to query for SIM details. Requires <myCloudConnectorGroupName> from the previous step.
The following command is used to list SIM details:

curl -i -X GET https://api.provisioning.asavie.com/v1/accounts/<FAK>/networks/<FK>/devices/apns/ -H "Authorization: Bearer <apiToken>"

The following command is used to associate the SIM to the cloud service connector group. The Network Key <NK> is available in the web portal:

curl -i -X POST https://api.provisioning.asavie.com/v1/accounts/<FAK>/networks/<NK>/devices/apns/<CLI>/cloudconnectordetails \
-H "Authorization: Bearer <apiToken>" \
-H "Content-Type: application/json" \
-d '{"GroupName":"<myCloudConnectorGroupName>"}'

 

5. Provision Azure IoT Hub and associate the identities, certificates and policies to each of the SIMs in the Asavie IoT Connect cloud connector group
The cloud provisioning step requires the Azure IAM User cloud access key <IAMuserKey> and secret access key <IAMuserSecret>.

curl -X POST https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/groups/<myCloudConnectorGroupName>/provision \
  -H "Authorization: Bearer <apiToken>" \
  -H "Content-Type: application/json" \
  -d '{"cloudAccessKeyName": "<IAMuserKey>", "cloudAccessKeyValue": "<IAMuserSecret>"}'

 

6. Validate the configuration

The following command lists the active SIM details in Asavie IoT Connect:

curl -i -X GET https://api.provisioning.asavie.com/v1/accounts/<FAK>/networks/<FK>/devices/apns/ -H "Authorization: Bearer <apiToken>"

Validate that the Azure IoT Hub details are correctly assigned to the SIM <CLI>. The Network Key <NK> is available in the web portal:

curl -i -X GET https://api.provisioning.asavie.com/v1/accounts/<FAK>/networks/<NK>/devices/apns/<CLI>/cloudconnectordetails -H "Authorization: Bearer <apiToken>"

 

Congratulations, your devices are now ready to send MQTT data to Azure IoT Hub. A security best practice is to now reset your API access secret in the Asavie IoT Connect web portal.

 

Finally, the following instructions may be of use for in-life management of cloud connectivity
Update all certificates assigned to SIMs:

curl -X POST https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/groups/<myCloudConnectorGroupName>/provision \
  -H "Authorization: Bearer <apiToken>" \
  -H "Content-Type: application/json" \
  -d '{"cloudAccessKeyName": "<IAMuserKey>", "cloudAccessKeyValue": "<IAMuserSecret>"}'

 

Or, if you wish to point the SIMs to a new cloud endpoint, simply create new endpoint:

curl -i -X POST https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/endpoints \
-H "Authorization: Bearer <apiToken>" \
-H "Content-Type: application/json" \
-d '{"Name":"<NewCloudEndpointName>", "Port":8883, "EndpointType":"TLS", "Host": "<NewIoTCloudAddress>"}'

Update the cloud connector group to point to the new cloud endpoint:

curl -i -X PATCH https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/groups/<ExistingCloudConnectorGroupName> \
-H "Authorization: Bearer <apiToken>" \
-H "Content-Type: application/json" \
-d '{"EndpointName": "<NewCloudEndpointName>"}'

Provision the SIM group with new credentials:

curl -X POST https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/groups/<NewCloudEndpointName>/provision \
  -H "Authorization: Bearer <apiToken>" \
  -H "Content-Type: application/json" \
  -d '{"cloudAccessKeyName": "<UserKey>", "cloudAccessKeyValue": "<UserSecret>"}'