Connect to AWS IoT Core with Asavie IoT Connect cloud service connectors

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

Prerequisites
The user has:

  • a SIM and data bundle available in Asavie IoT Connect
  • an active AWS account with administration rights
  • 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)
  • 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 AWS 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 AWS IoT Core endpoint details
Configure the Asavie IoT Connect cloud connector with an AWS IoT Core endpoint name <AWScoreEPname>. Add the AWS Core address <AWScore> e.g. (xxxx.iot.xx-xxx-x.amazonaws.com), 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":"<AWScoreEPname>", "Port":8883, "EndpointType":"TLS", "Host": "<AWScore>"}'

 

3. Configure a cloud connector group name, used by Asavie IoT Connect when provisioning AWS IoT Core credentials
Create the Asavie IoT Connect cloud connector group, this is used to group SIMs that require credentials in AWS IoT Core. Requires the <AWScoreEPname> 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": "<AWScoreEPname>"}'

 

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 AWS IoT Core 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 AWS IAM User Access key ID <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 AWS Core endpoint 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 AWS IoT Core. 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>"}'