Asavie IoT Connect Cloud Service Connector Application Note · enabling connection to different AWS IoT core regions from a single Asavie IoT Connect account. 1.1 Provisioning flow

Asavie IoT Connect Cloud Service Connector Application Note

Asavie IoT Connect application note

© 2018 Asavie IoT Connect Version draft 2

Table of Contents

1 Asavie IoT Connect cloud service connector overview..................................... 4 1.1 Provisioning flow overview ................................................................................ 5

2 Enabling Asavie with access to the AWS cloud ................................................ 6 2.1 Configure AWS user role for Asavie access ......................................................... 6 2.2 Retrieving Asavie API Credentials ...................................................................... 8

3 Provisioning Asavie IoT Connect Cloud Service Connector .............................. 10 3.1 Method 1: Quick start provisioning .................................................................. 11 3.2 Method 2: (Alternative) Provisioning script ...................................................... 12

3.2.1 AWS Thing identity and certificates ................................................................ 12 3.2.2 Thing Policy ...................................................................................................... 13 3.2.3 AWS Thing creation, command line instructions ............................................ 13 3.2.4 Create the Asavie IoT Connect cloud service connector vault ........................ 14

3.2.4.1 Authenticate ............................................................................................................ 14 3.2.4.2 Create cloud connector endpoint ............................................................................ 15 3.2.4.3 Create cloud connector group ................................................................................. 16 3.2.4.4 Assign SIM to cloud connector group ...................................................................... 17 3.2.4.5 Store key in cloud connector vault .......................................................................... 18 3.2.4.6 Set device credentials .............................................................................................. 19

4 Preparing the cellular device ......................................................................... 20 4.1 Insert the SIM and power on ........................................................................... 20 4.2 APN configuration for the cellular modem ....................................................... 20 4.3 Configure the MQTT client host ....................................................................... 20

5 Validating the provisioning flow .................................................................... 21

6 Sending MQTT messages from the cellular device .......................................... 25

7 Appendix: Commands and Code Snippets ...................................................... 26 7.1 Flattening security certificates using the command line .................................... 26 7.2 Useful AWS CLI commands .............................................................................. 26 7.3 Useful Asavie API commands ........................................................................... 27

7.3.1 Get the network details ................................................................................... 27 7.3.2 Retrieve the list of SIMs ................................................................................... 27 7.3.3 List existing Asavie IoT Connect cloud service connector vaults: .................... 27 7.3.4 Delete an Asavie IoT Connect cloud service connector vault: ........................ 27



Prerequisites • The user has active SIMs in Asavie IoT Connect

• The user has access to the Asavie IoT Connect account

• The Asavie IoT Connect network topology** is set up for MQTT cloud connectors.

• The user has an AWS account in which they can set up a programable user

• The user has a cellular IoT device that is transmitting MQTT messages

• For script provisioning the user requires a basic understanding of REST APIs and has the necessary OS (Windows, Linux or Mac) toolkits and AWS CLI SDK installed

** Log into the Asavie IoT Connect account (http://aws.iotconnect.asavie.com/) > browse to the “Network Settings” tab and select the “Network Profile” submenu tab. Under the Network (Title), check that the label reads “MQTT Cloud Connector Network Settings”.

Disclaimer MQTT Cloud Services Connector is in early access Beta stage. It is a fully functional release of the service but there are possibilities that it could contain some bugs and performance issues. There is no SLA or technical support obligation and is therefore suitable for limited production use cases.

Annotation

• User defined variables are denoted by <myVariables>, substitute your own values for the indicated variable.

TL;DR Jump to section 3.13.1 Quick Start Provisioning to get your cellular devices connected with AWS IoT Core within minutes. Support Details Please contact our support team if at any time you need assistance, as a completely managed service we will be happy to schedule a time with you to help you get connected. Email us at: [email protected]

http://aws.iotconnect.asavie.com/

mailto:[email protected]



1 Asavie IoT Connect cloud service connector overview

The application note provides an overview of Asavie IoT Connect cloud service connector and the steps necessary to securely connect the cellular IoT device MQTT application to the cloud service of AWS IoT Core within minutes. In addition, the application note demonstrates an automation use case for scale, which uses the Asavie IoT Connect API – https://api.provisioning.asavie.com/. The default Asavie API setting is read/write for the cloud service connector only, all other commands are read only. What is the MQTT Cloud Connector? Asavie MQTT Cloud Connector is a MQTT proxy that will forward traffic from the devices you choose in your private network to the public MQTT broker of your choice (e.g. AWS IoT Core, Azure IoT Hub). The proxy endpoint is private, accessible only to IoT devices in your account. The devices use plain MQTT to the proxy endpoint over a secure private channel, and the proxy forwards the traffic to your MQTT broker, leveraging the network authentication. The proxy will use the appropriate authentication and transport mechanism. For example, a common pattern would be for the proxy to use TLS and client X.509 certificate per device when connecting to the MQTT broker. The MQTT broker endpoint, the type of authentication and the certs to use per device are part of the configuration process for the MQTT Cloud Connector.

Figure 1: Asavie IoT Connect topology architecture

Asavie IoT Connect cloud service connector eliminates the need to manage cloud certificates on the cellular edge device. This has unique advantages for the end-user which include: minimal software development effort at the cellular IoT edge, reduced resource requirements of CPU, memory and power (ideal for constrained devices) and future proofed connectivity. Ultimately, by moving the burden of cloud access and certificate management into the private Asavie network, the user retains the flexibility to manage IoT device connectivity from a centralized management portal. This further helps to reduce the total cost of ownership of the IoT deployment by reducing data expenditure and eliminating unnecessary on-site visits to update device certificates.

https://api.provisioning.asavie.com/



The Asavie IoT Connect administrator (or user) will require AWS credentials as a “programmatic user” that has full access permissions. Data only access is required if you wish to use web-sockets for proof of concept deployments. The preferred and recommended approach, which is demonstrated in this application note, is to create unique identities and certs for each cellular IoT device i.e. (require Full IoT Access permissions). Note that the AWS account credentials are not retained or stored by Asavie. A secure key managed service (KMS) vault in the Asavie private network is used to store the IoT device credentials. The Asavie KMS vault is only accessed by the Asavie MQTT proxy when an authenticated and authorized flow from the cellular IoT device is received in the Asavie private network. The set-up steps require that the user define the SIM IDs that the Asavie IoT Connect service will proxy the MQTT data for. Users can have multiple cloud service connector SIM groups enabling connection to different AWS IoT core regions from a single Asavie IoT Connect account.

1.1 Provisioning flow overview

Note: Validate that the network topology is configured for Asavie IoT Connect cloud service connectors. In the Asavie IoT Connect web UI browse to Network Settings > Network Profile. Under the Network Title check that the label reads “MQTT Cloud Connector Network Settings” Highlighted below are the 4 basic provisioning steps that this document covers, in order to securely connect and proxy the cellular IoT device MQTT traffic to the AWS IoT Core:

Figure 2: Asavie IoT Connect provisioning flows for AWS

Configure AWS IoT Core Thing Identity and certs

Provision certs to Asavie Cloud

connector vault

Configure device APN and MQTT client host

set as mqtt.asavie.network

Send MQTT data and validate operational

success



2 Enabling Asavie with access to the AWS cloud

2.1 Configure AWS user role for Asavie access

1. Login into the AWS Console

2. Go to: IAM -> Users -> Add User

3. Fill in the username e.g. <MyAsavieTestUser> and select programmatic

access box, select “Next:Permissions”

Figure 3: AWS IAM add user

4. Select the "Attach existing policies directly" option, then select

AWSIoTFullAccess. Select “Next:Review”.

Figure 4: AWS IAM assign user policy for IoT access



5. Review the details and create the user. Finally, note the Access key ID and

secret. Note that the API credentials are used in “Method 1: Quick start

provisioning” setup. In method 2 you will require need to use the Access key

ID only if you want to setup your AWS IoT account through the AWS CLI

tool

Figure 5: AWS IAM user credentials

6. Browse to the AWS IoT service, select the “Settings” menu and note the AWS

IoT Core Endpoint details e.g. 8aq34n5q8ffew.iot.eu-west-1.amazonaws.com.

Figure 6: AWS IoT Core dashboard



2.2 Retrieving Asavie API Credentials

1. Log into the Asavie IoT Connect portal (https://aws.iotconnect.asavie.com/)

Figure 7: Asavie IoT Connect login

2. Click on the account details in the right-hand top corner to view the Asavie IoT

Connect API details. In the menu displayed, select “Access AsavieAPI”. In the pop-up window copy the CLIENT ID (referenced later as <AsavieAPIuser>) and SECRET (referenced as <AsavieAPIsecret>). Note the Account ID as highlighted below. The Account ID is referenced as the “Foreign Account Key” (FAK) in the Asavie API.

Figure 8: Asavie IoT Connect API credentials

https://aws.iotconnect.asavie.com/



3. A recommended security best practice is to create a fresh API Key/Secret pairing, each time you wish to use the cloud service connector API. Once the setup is complete, RESET the API pairing.



3 Provisioning Asavie IoT Connect Cloud Service Connector

The user can choose to use the Asavie Quick Start provisioning tool (see section 3.1) or

alternatively build a script to enable the Thing in both AWS and Asavie IoT Connect (see

section 3.2). Please choose to use one method only.

(NOTE: In the early access program the Asavie quick start provisioning tool is web-based and

uses javascript. The JS script runs locally on the user PC. The result is that there are no AWS

account details stored in Asavie IoT Connect.)

In both methods, the following are a list of key actions that enable Asavie IoT Connect to

securely proxy on behalf of the device to the cloud mile. The process of connecting devices to

the cloud is based on the recommended AWS security best practices.

In both provisioning methods the following are the essential steps undertaken:

1. Create the cloud identity and X.509 certificates assign as active and apply policy

2. Configure the Asavie IoT Connect cloud service connector vault in the Asavie IoT

Connect account network, then upload the cloud certificates to the Asavie vault

3. Assign SIMs to the cloud connector group

If desired, a user can create multiple cloud service connectors in the Asavie IoT Connect

account, by simply repeating the steps. If the user wishes to re-use the SIM they must first

remove the SIM from the current cloud connector group and assign it to the new cloud

connector group with the new certificates for the new AWS account or AWS IoT Core region.

Before commencing, note the following credentials are required (see the previous sections on

how to obtain the details):

• Asavie IoT Connect API Key/Secret

• AWS programmable user API Key/Secret

• AWS IoT Core destination address



3.1 Method 1: Quick start provisioning

Browse to https://provisioner.asavie.network/aws-bootstrap.html and enter the details as

previously created in the AWS IAM service, along with the AWS IoT Core Endpoint details.

Figure 9: Asavie provisioner for AWS cloud service connectors

1. Fill in the form as follows:

a. API endpoint (specific to your region of operations):

i. EU: https://api.provisioning.asavie.com/

ii. APAC: https://asaviepsapacprovisioningsvc.azurewebsites.net

iii. US: (coming Soon, use EU for now)

b. API Username = (see section 2.2 for details)

c. API Secret = (see section 2.2 for details)

d. Account Name = (use Asavie IoTConnect Account ID, see section 2.2)

e. AWS Region = e.g. eu-west-1 (use AWS IoT Core region setting)

f. AWS API Key = (AWS IAM User Security Credentials, see section 2.1)

g. Secret Access Key = (the secret key per section 2.1, if you don’t have it

delete the existing key and create a new one)

h. SIM details = Log into the Asavie IoT Connect portal (or see the email from

Asavie support for details). Enter the SIM details and press the “+” symbol to

add additional SIMs to the cloud service connector.

i. Select “Bootstrap Devices” to continue

2. A status bar will appear, highlighting each provisioning step success state. On

successful completion the bar will turn green.

Congratulations, you are now ready to start using Asavie IoT Connect cloud service

connector. To ensure the devices are connected JUMP to SECTION 4 – Validating the

provisioning flow.


https://asaviepsapacprovisioningsvc.azurewebsites.net/



NOTE: At this point we recommend you disable or delete the AWS API Keys. You will not

need them again unless you want to configure your account again or add new devices.

3.2 Method 2: (Alternative) Provisioning script

Note: Users require access to the AWS CLI with IAM IoT permissions to continue.

The goal of this method is to create an automation script for managing scaled deployments,

the choice of scripting tool is outside the scope of this document.

However, if you are unfamiliar with using REST APIs, there are various toolkits available to

help you get started - program e.g. (Postman), browser plugin e.g. (Firefox – Resting) or

alternatively command line programs for scripting e.g. (curl or wget).

The following example uses the command line tool curl (available as a npm package install

on most OS types - https://www.npmjs.com/). The following sections step through each of the

commands required, which can be used as part of a complete script (see Appendices for

examples).

3.2.1 AWS Thing identity and certificates

The user can chose to log into the AWS IoT Core console and create certificates and assign policies - (https://docs.aws.amazon.com/iot/latest/developerguide/create-device-certificate.html). If you choose to provision the certs through the AWS console, download and store certificates on your local PC. The user must flatten the certificate files for use with the Asavie API (see the Appendix Code Snippets for suggested instruction set). In the sections to follow AWS certs are provisioned using the AWS command line.

https://www.npmjs.com/

https://docs.aws.amazon.com/iot/latest/developerguide/create-device-certificate.html

https://docs.aws.amazon.com/iot/latest/developerguide/create-device-certificate.html



3.2.2 Thing Policy

As per the AWS IoT security recommendations all Things in AWS require an IoT Core security policy. If the policy is to be attached via a command line, ensure to save a “policy.json” file locally. The policy shown below is used in the command lines that follow, it is attached to the certificate as part of an in-line script function. Example AWS IoT Core policy with data privileges:

{

"Version": "2012-10-17",

"Statement": [

{

"Effect": "Allow",

"Action": [

"iot:Connect",

"iot:Publish",

"iot:Subscribe",

"iot:Receive",

"iot:GetThingShadow",

"iot:UpdateThingShadow",

"iot:DeleteThingShadow"

],

"Resource": "*"

}

]

}

3.2.3 AWS Thing creation, command line instructions

For more details on the AWS CLI reference, visit: https://docs.aws.amazon.com/cli/latest/reference/iot/index.html#cli-aws-iot Shown below is the basic AWS command line set, which is required as part of the Asavie IoT Connect cloud service. They include AWS Thing identity creation, certificate creation and assignment, plus AWS IoT Core policy assignment:

aws iot create-thing --thing-name "<myCellularThingName>"

aws iot create-keys-and-certificate --set-as-active

aws iot create-policy --policy-name "<myPuBSubPolicy>" --policy-

document file://<Directory:\\PubSub.json>

aws iot attach-principal-policy --principal "<certificateARN>" -–

policy-name "<myPubSubPolicy>"

aws iot attach-thing-principal --thing-name "<myCellularThingName>" -

-principal "<certificateARN>"



3.2.4 Create the Asavie IoT Connect cloud service connector vault

3.2.4.1 Authenticate

Using https://api.provisioning.asavie.com, obtain a valid security token (active for 60mins),

the API Username::Secret keypair and Foreign Account Key <FAK> or Account ID can be

found in the Asavie UI web portal (see section 2.2)

From the response note down the access_token which will be used as part of the

Authorization: Bearer details all other Asavie API commands.

1. Retrieve the security access_token:

a. METHOD – POST

b. URL – https://api.provisioning.asavie.com/v1/authtoken

c. BODY- grant_type=client_credentials&client_id=<AsavieAPIuser>

>&client_secret=<AsavieAPIsecret>

Example:

curl -i -X POST https://api.provisioning.asavie.com/v1/authtoken -d

"grant_type=client_credentials&client_id=<AsavieAPIuser>&client_secret=<AsavieAPIsecre

t>"

Figure 10: Asavie API response for authroization access_token




3.2.4.2 Create cloud connector endpoint

Create a cloud connector endpoint by assigning it a name <AWScoreEP>. Add the AWS

IoT Core ARN (see section 2.1 step 6) <AWSCoreIoTARN> as the target for the cloud

connector endpoint. The step requires the assigned <vaultName> and returned CryptoKey

<vaultPassword> from the previous step.

a. METHOD – POST

b. URL – https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/en

dpoints

c. HEADER – Authorization: Bearer <apiToken>, Content-Type: application/json

d. BODY- {

"Name": <AWScoreEP>,

"Port":8883,

"EndpointType”:2,

"Host": <AWSCoreIoTARN>

}

Example:

NOTE: curl for WINDOWS requires that the user mark quotes with a backslash in the data

payload

WINDOWS curl -i -X POST

https://api.provisioning.asavie.com/v1/accounts/1234mark/cloudconnector/endpoints -H

"Authorization: Bearer <apiToken>" -H "Content-Type: application/json" -d

"{\"Name\":\"awsMark1\", \"Port\":8883,\"EndpointType\":2, \"Host\":\"a34zw5ktqhsc3w-

ats.iot.eu-west-1.amazonaws.com\"}"

LINUX 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":"<AWScoreEP>", "Port":8883, "EndpointType":2, "Host": "<AWSCoreIoTARN>",

"Credentials": {"VaultName":"<vaultName>", "VaultPassword":"<vaultPassword>",

"CredentialType":1}}'



3.2.4.3 Create cloud connector group

Create a cloud connector group for the endpoint. This enables users to easily add further

SIMs in the future. Requires the <AWScoreEP> from the previous step.

a. METHOD – POST

b. URL – https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/gr

oups


d. BODY- {

"Name": <myCloudConnectorGroup>,

"Endpoints": ["<AWScoreEP>"]

}

Example:

WINDOWS

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\":\"<myCloudConnectorGroup>\",\"Endpoints\": [\"<AWScoreEP>\"]}"

LINUX

curl -i -X POST

https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/groups \



-d '{"Name":"<myCloudConnectorGroup>","Endpoints": ["<AWScoreEP>"]}'



3.2.4.4 Assign SIM to cloud connector group

Assign an active Asavie IoT Connect SIM phone number (CLI) to the cloud connector

endpoint group. For this step you will need:

• SIMI CLI. You can get this from the IoT Connect web UI or alternatively use the

API to query for SIMs list (see 7.3.2 Retrieve the list of SIMs).

• Network Foreign Key. You can use the API to query the network details (see

7.3.1 Get the network details)

• Cloud connector group <myCloudConnectorGroup> from previous step.

a. METHOD – PUT

b. URL - https://api.provisioning.asavie.com/v1/accounts/<FAK>/networks/<Network

ForeignKey>/devices/apns/<CLI>/cloudconnectorgroup


a. BODY – "<myCloudConnectorGroup>"

Example:

// Add SIM to cloud connector group

EXAMPLE <CLI> = 204043888827197

WINDOWS

curl -i -X PUT

https://api.provisioning.asavie.com/v1/accounts/<FAK>/networks/<NetworkForeignKey>/dev

ices/apns/<CLI>/cloudconnectorgroup -H "Authorization: Bearer <apiToken>" -H "Content-

Type: application/json" -d "\"<myCloudConnectorGroup>\""

LINUX

curl -i -X PUT

https://api.provisioning.asavie.com/v1/accounts/<FAK>/networks/<NetworkForeignKey>/dev

ices/apns/<CLI>/cloudconnectorgroup



-d "<myCloudConnectorGroup>"



3.2.4.5 Store key in cloud connector vault

With the newly created API access_token <apiToken> create the cloud connector vault,

by assigning it a name <vaultName>. In addition, the command is used to upload the

AWS certificates (captured from the AWS Thing creation section).

From the response note down the vault CryptoKey, which will be used in the next

steps:

a. METHOD - POST

b. URL – https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/va

ults


d. BODY- {

"Name": <vaultName>,

"Certificate": <AWScertificate>,

"Privatekey": <AWSprivateKey>

}

EXAMPLE

Observation: curl for windows requires that the json payload data double quotes be marked by

the back slash.

Note: certificates need to be flattened to be used as part of the API call (see Appendix 7.1).

Windows

curl -i -X POST

https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/vaults -H

"Authorization: Bearer <apiToken>" -H "Content-Type: application/json" -d "{\"Name\":

\"<vaultName>\", \"Certificate\": \"-----BEGIN CERTIFICATE-----\nMIIDWjCCAkKgAwIBA

gIVAN9MX0tWma6wDpo NUBFDypz40ie/MA0GCSqGSIb3D-----END CERTIFICATE-----\n\",

\"PrivateKey\": \"-----BEGIN RSA PRIVATE KEY-----\n btG7CTlrOZmzVDgB1Mt1TROj IKNLfYHjnUMBcorq66R\n-----END RSA PRIVATE KEY-----\n\"}"

Linux

curl -i -X POST

https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/vaults -H

"Authorization: Bearer <apiToken>" \


-d '{"Name": "<vaultName>", "Certificate": "-----BEGIN CERTIFICATE-----

\nMIIDWjCCAkKgAwIBAgIVAN9MX0 tWma6wDpoNUBFDypz40ie/MA0GCSqGSIb3D-----END CERTIFICATE--

---\n", "PrivateKey": "-----BEGIN RSA PRIVATE KEY---btG7CTlrOZmzVDgB1Mt1TROjIKNLf

YHjnUMBcorq66R\n----- END RSA PRIVATE KEY-----\n"}'



Figure 11: Asavie API response for new vault creation includes the vault password (Cryptokey)

3.2.4.6 Set device credentials

Set credentials for individual device. The url requires the <CLI> detail of the SIM

and cloud vault name and password from the step X.

a. METHOD – PUT

b. URL - https://api.provisioning.asavie.com/v1/accounts/<FAK>/networks/<Network

ForeignKey>/devices/apns/<CLI>/cloudconnectorcredential


e. BODY – "Credentials":{

"VaultName":<vaultName>,

"VaultPassword":<vaultPassword>,

"CredentialType":1

}

WINDOWS

curl -i -X PUT

https://api.provisioning.asavie.com/v1/accounts/testmqttccbg/networks/<networkid>/devi

ces/apns/<CLI>/cloudconnectorcredential

-H "Authorization: Bearer <apiToken>" -H "Content-Type: application/json" -d

"{\"VaultName\":\"<VaultName>\",\"VaultPassword\":\"<VaultPassword>\",\"CredentialType

\":1}"

LINUX

curl -i -X PUT

https://api.provisioning.asavie.com/v1/accounts/testmqttccbg/networks/<networkid>/devi

ces/apns/<CLI>/cloudconnectorcredential \



-d '{"VaultName":"<VaultName>","VaultPassword":"<VaultPassword>","CredentialType":1}'

https://api.provisioning.asavie.com/v1/accounts/%3cFAK%3e/networks/%3c

https://api.provisioning.asavie.com/v1/accounts/testmqttccbg/networks/%3cnetworkid%3e/devices/apns/%3cCLI%3e/cloudconnectorcredential

https://api.provisioning.asavie.com/v1/accounts/testmqttccbg/networks/%3cnetworkid%3e/devices/apns/%3cCLI%3e/cloudconnectorcredential



4 Preparing the cellular device

4.1 Insert the SIM and power on

1. The Asavie supported subscriber identity module (SIM) arrives in a credit card

holder, simply pop out the SIM and insert into the device. Attach the antenna and

power up the device.

Figure 12 : SIM in-situ in the sample device, check the device instruction manual for SIM orientation

4.2 APN configuration for the cellular modem

1. Each cellular device requires the Access Point Name (APN) to be configured: a. APN = <SIM dependent, please check the Asavie IoT Connect FAQ for more

details> b. Authentication type = PAP-CHAP c. Username/Password = data/data

4.3 Configure the MQTT client host

1. Configure the MQTT client to send traffic to “mqtt.asavie.network”

Note: traffic is sent in the clear from the cellular IoT device i.e. MQTT. The MQTT message is secured through the cellular network based on the cellular 3GPP standards. The traffic then passes from the cellular core through the Asavie managed secure private links, assuring the message is always in a private network and un-exposed to the internet. Finally, using the Asavie IoT Connect cloud service connector the MQTT traffic is encapsulated using the cloud credentials to MQTTS, securing the cloud mile journey to the public internet facing domain of the cloud IoT service.



5 Validating the provisioning flow

1) Open the AWS IoT Core Device Dashboard and note the successful connection attempt

from the device to the AWS IoT Core dashboard

Figure 13: AWS IoT Core dashboard

2) In the early access program for Asavie IoT Connect cloud service connector, users are

required to use the Asavie API to validate their configuration:


a) If you require further assistance, we recommend that you schedule a free on-boarding

call with Asavie support, who will assist you in maximizing the potential from the

Asavie API.

b) Using a REST client e.g. Postman or CURL, call the Asavie API and validate the

AWS IoT endpoint details, SIM details and check that the AWS certificate vault are

created. The following steps are a minimal set of API calls, which are implemented

using the Resting plugin on Firefox.




3) Using https://api.provisioning.asavie.com, obtain a valid security token (active for

60mins), the AsavieAPIuser and AsavieAPIsecret are as accessible from the Asavie IoT

Connect web portal (see section 2.2)

Retrieve a security access_token:

a. METHOD – POST

b. URL – https://api.provisioning.asavie.com/v1/authtoken

c. BODY- grant_type=client_credentials&client_id=<AsavieAPIuser>

>&client_secret=<AsavieAPIsecret>

Figure 14: Firefox RESTing plugin

4) From the response copy the “access_token” key which is used in the next request

Figure 15: Firefox RESTing plugin response window




5) Validate that the AWS IoT core endpoint detail is correct in the Cloud Connector, the

Foreign Account Key <FAK> is the Asavie IoT Connect Account ID (see section 2.2)

The <apiToken> is the access_token from the previous step.

a) METHOD – GET

b) URL - https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconn

ector/endpoints

c) HEADER – Authorization: Bearer <apiToken>

* Note: that there is a character space between Bearer and the first character of the

token

d) The “Host” name from the API response should equal the AWS IoT Core Endpoint

service host name (see section 2.1).

* Note: All MQTT traffic generated by the SIM will arrive at this target.

Figure 16: Validate Asavie API response data, ensure it matches AWS IoT Core ARN



6) Validate that the SIM is configured in the Asavie IoT Connect Account ID or <FAK>.

a) METHOD – GET

b) URL – https://api.provisioning.asavie.com/v1/accounts/<FAK>/hardware/

sims

c) HEADER – Authorization: Bearer <apiToken>

d) The “CLI” and “SIMNumber” variables should match the SIM details as per the

Asavie IoT Connect web portal.

* Note: the “CLI” or SIM number is used in the next step to validate that the SIM is

part of the configure cloud connector group.

Figure 17: Validate Asavie API response data, ensure CLI/SIMNumber are correct



6 Sending MQTT messages from the cellular device

1) Ensure that AWS IoT Connect Topology is set as “Internet+VPN+CloudConnector”

• In the Asavie IoT Connect web UI, browse to Network Settings > Network Profile.

Under the Network Title check that label reads “MQTT Cloud Connector

Network Settings”

2) With the Asavie SIM inserted in the cellular device, configure the APN of the device

(further details in the FAQ link available from the IoT Connect portal)

3) Configure the MQTT client host as “mqtt.asavie.network”

4) In AWS subscribe to the topic that your client is publishing to e.g. “inTopic/message”

• On successful boot-up and connection to the cellular device to the network, the

MQTT application messages will appear in the AWS IoT Core

Figure 18: AWS IoT Core successfully showing the MQTT message



7 Appendix: Commands and Code Snippets

7.1 Flattening security certificates using the command line

WINDOWS: Create a batch script in the local directory in which the private and public keys

are stored. Note there should be no trailing white space at the end of each line.

@echo off

setlocal enabledelayedexpansion

set privatekey=36cc1ba9ea-private.pem.key

set publickey=36cc1ba9ea-public.pem.key

set outstring=

for /F "delims=" %%a in (%privatekey%) do set outstring=!outstring!\n%%a

echo "PrivateKey: "%outstring%"

set outstring=

for /F "delims=" %%a in (%publickey%) do set outstring=!outstring!\n%%a

echo "Certificate": "%outstring%"

LINUX:

Step1. cat certificate.pem.crt | sed 's/$/\\n/' | tr -d '\n'

Step2. cat private.pem.key | sed 's/$/\\n/' | tr -d '\n'

7.2 Useful AWS CLI commands

Create and store AWS certificates locally:

aws iot create-keys-and-certificate –set-as-active –certificate-pem-outfile cert.pem –

public-key-outfile publicKey.pem –private-key-outfile privateKey.pem

Temporarily block a Thing connecting to AWS, set certificate status “INACTIVE”:

aws iot update-certificate --certificate-id <certifciateID --new-status INACTIVE



7.3 Useful Asavie API commands

7.3.1 Get the network details

Note the ForeignKey field in the response. It is required in different steps of the process

(indicated as <NetworkForeignKey>

curl -i -X GET https://api.provisioning.asavie.com/v1/accounts/testmqttccbg/networks/

-H "Authorization: Bearer <apiToken>"

7.3.2 Retrieve the list of SIMs

Note the CLI field for each SIM in the response. It is required in different steps of the process

curl -i -X GET https://api.provisioning.asavie.com/v1/accounts/<FAK>/hardware/sims -H

"Authorization: Bearer <apiToken>"

7.3.3 List existing Asavie IoT Connect cloud service connector vaults: curl -i -X GET

https://api.provisioning.asavie.com/v1/accounts/<FAK/cloudconnector/vaults -H

"Authorization: Bearer <apiToken>"

7.3.4 Delete an Asavie IoT Connect cloud service connector vault: curl -i -X DELETE

https://api.provisioning.asavie.com/v1/accounts/<FAK>/cloudconnector/vaults/<vaultName

> -H "Authorization: Bearer <apiToken>"

Asavie Technologies LTD Corporate Headquarters 100 Mount Street Lower, Dublin 2, D02 TY46, Ireland P +353 1 6763585 E [email protected] W www.asavie.com

Asavie, the Asavie logo, PassBridge, the PassBridge SDN logo, AccessMyLan, the AccessMyLan logo, Moda and the Moda logo, IoT Connect and IoT Connect logo are trademarks of Asavie Technologies Limited. All other trademarks, service marks and trade names are the property of their respective owners. As we are always seeking to improve our products, the information in this document gives only a general indication of the product capability and suitability, none of which shall form part of any contract. We reserve the right to make design changes without notice. © 2018 Asavie Technologies Limited. All rights reserved.

mailto:[email protected]?subject=Asavie%20Proposal

http://www.asavie.com/

Documents

Asavie IoT Connect Cloud Service Connector Application Note · enabling connection to different AWS IoT core regions from a single Asavie IoT Connect account. 1.1 Provisioning flow