Using the following instructions developers can automate the provisioning and proxy MQTT messages securely to cloud IoT services (AWS IoT Core or Azure IoT Hub), eliminating the need for a certificate on the device.

Prerequisites

User:

• SIM and data bundle available in the portal
• Active AWS or Azure account with administration rights
• IAM Users for the cloud IoT service:
  • For AWS IoT Core:
    • AWS IAM Users policy with AWSIoTDataAccess, Access Key ID and Secret access key (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html)
  • For Azure IoT Hub:
    • 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)
• Cellular-enabled device with the ability to send MQTT messages
• 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 the service. A security best practice is to delete the cloud IAM User credentials after provisioning.

Configure your Cloud IoT Account

Configure and take note of your cloud IoT endpoint.

AWS

Browse to the AWS IoT service and select Settings noting the Endpoint, which looks like:

8aq34n5q8ffew.iot.eu-west-1.amazonaws.com.

Azure

Create an IoT Hub here: https://docs.microsoft.com/en-us/azure/iot-hub/quickstart-send-telemetry-node#create-an-iot-hub
making note of the hostname, which looks like:

$YourIoTHubName.azure-devices.net

Obtain in the Portal an API and Network Key

Under the submenu Access API>Account Details in the top right-hand corner, the portal displays:

• Account Key: referred to as the Foreign Account Key $FAK in proceeding commands
• Network Key required for the next steps.

Setup your variables and authenticate using https://ApiBaseUrl. Note the valid authorization token (active for 60mins) using both the CLIENT/USER ID and SECRET API KEY.

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

FAK="Your Account Key"
NETWORK_FK="Your Network Key"
API_USER="Your API User ID"
API_SECRET="API Secret"

curl -X POST https://ApiBaseUrl/v1/authtoken 
  -d "grant_type=client_credentials&client_id=$API_USER&client_secret=$API_SECRET"

TOKEN="Token response from the authentication call"

Configure the Cloud Connector Endpoint

Configure the endpoint name $ENDPOINT_NAME.
Add the cloud IoT endpoint address $CLOUD_ENDPOINT (xxxx.iot.xx-xxx-x.amazonaws.com or iot-hub.azure-devices.net), the target for MQTT data originating from the devices.

curl -X POST https://ApiBaseUrl/v1/accounts/$FAK/cloudconnector/endpoints 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"Name":"$ENDPOINT_NAME", "Port":8883, "EndpointType":"TLS", "Host": "$CLOUD_ENDPOINT"}'

Note: You can modify the configuration of the endpoint at any time (e.g. if you need to move to a different account or cloud). In these scenarios, you need to repeat the provisioning steps below in order to re-provision the devices to the new cloud endpoint.

Configure a Cloud Connector Group

This groups devices and links them to the created Endpoint. It requires $ENDPOINT_NAME from the previous step.

curl -X POST https://ApiBaseUrl/v1/accounts/$FAK/cloudconnector/groups 
-H "Authorization: Bearer $TOKEN" 
-H "Content-Type: application/json" 
-d '{"Name":"$GROUP_NAME","EndpointName": "$ENDPOINT_NAME"}'

Attach the device to the Cloud Connector Group

Assign an active device (identified by the SIM phone number or $CLI) to the cloud connector group where device details are available in the web portal.
Alternatively, use the API to query for device details.
Requires $GROUP_NAME from the previous step.

Use the following command to list device details:

curl -X GET https://ApiBaseUrl/v1/accounts/$FAK/networks/$NETWORK_FK/devices/apns/ 
  -H "Authorization: Bearer $TOKEN"

Use the following command to associate the device to the cloud service connector group. The Network Key $NETWORK_FK is available in the web portal:

curl -X POST https://ApiBaseUrl/v1/accounts/$FAK/networks/$NETWORK_FK/devices/apns/$CLI/cloudconnectordetails 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"GroupName":"$GROUP_NAME"}'

Note: If you get an error in this step, verify that your devices have been activated in the portal with a live/enabled state.

Provision the Devices

Provision the AWS IoT Core/Azure IoT Hub and associate the identities, certificates, and policies to each of the devices in the Cloud Connector Group.
Cloud provisioning steps require the cloud IAM User Access key ID $CLOUD_ACCESS_KEY_ID and Secret access key $CLOUD_SECRET_ACCESS_KEY.

The provisioning process will run a number of tasks for each device in the group:

For AWS IoT Core endpoints:

• In your AWS IoT Core account create:
  • Key and a self-signed X.509 Certificate
  • Thing
  • Policy (only one policy for all devices) and attach it to the Certificate
  • Attach the Certificate to the Thing
• In the Cloud Services Connector:
  • Store the private key in the Vault
  • Attach the private key to the SIM identity.

For Azure IoT Hub endpoints:

• Create a key pair and a self-signed X.509 Certificate
• In your AWS IoT Core account:
  • Create a Device and link it to the Certificate thumbprint
• In the Cloud Services Connector:
  • Store the private key in the Vault
  • Attach the private key to the SIM identity.

For both providers this is triggered by this call:

curl -X POST https://ApiBaseUrl/v1/accounts/$FAK/cloudconnector/groups/$GROUP_NAME/provision 
  -H "Authorization: Bearer $TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"cloudAccessKeyName": "$CLOUD_ACCESS_KEY_ID ", "cloudAccessKeyValue": "$CLOUD_SECRET_ACCESS_KEY"}'

Note:

• This provisioning process may take some time, depending on the number of devices in the Cloud Connector Group.
• You can repeat the provisioning process at any time, and it will re-provision the devices.
  For example, you will have to re-provision if you change the endpoint configuration or if you add new devices to the Cloud Connector Group.

Validate the Configuration

Use the following command to list the active device details:

curl -X GET https://ApiBaseUrl/v1/accounts/$FAK/networks/$NETWORK_FK/devices/apns/ 
  -H "Authorization: Bearer $TOKEN"

Verify that the Endpoint details are correctly assigned to the device$CLI. The Network Key $NETWORK_FK is available in the web portal:

curl -X GET https://ApiBaseUrl/v1/accounts/$FAK/networks/$NETWORK_FK/devices/apns/$CLI/cloudconnectordetails 
  -H "Authorization: Bearer $TOKEN"

Congratulations, your devices are now ready to send MQTT data to cloud IoT service!

You can send MQTT messages to the mqtt.asavie.network private endpoint which will be securely forwarded to your cloud IoT service.
For example, you can use Eclipse Mosquitto (https://mosquitto.org/download/) and publish a message using:

mosquitto_pub -d -h mqtt.asavie.network -p 1883 -t "test/topic" -m "Message to my topic" -V mqttv311

or if using TLS

mosquitto_pub -d -h mqtt.asavie.network -p 8883 -t "test/topic" -m "Message to my topic" -V mqttv311 --cafile DigiCertGlobalRootCA.pem

The message will be received in the corresponding topic of your cloud IoT service.

Security

• Once the provisioning process has been completed, you should delete/revoke cloud IAM API keys.