Asavie IoT Connect Cloud Service Connector Application Note · enabling connection to different AWS...
Transcript of Asavie IoT Connect Cloud Service Connector Application Note · enabling connection to different AWS...
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 3
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]
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 4
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.
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 5
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 6
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 7
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 8
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 9
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.
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 10
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 11
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.
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 12
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.
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 13
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>"
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 14
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 15
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}}'
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 16
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
c. HEADER – Authorization: Bearer <apiToken>, Content-Type: application/json
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 \
-H "Authorization: Bearer <apiToken>" \
-H "Content-Type: application/json" \
-d '{"Name":"<myCloudConnectorGroup>","Endpoints": ["<AWScoreEP>"]}'
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 17
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
c. HEADER – Authorization: Bearer <apiToken>, Content-Type: application/json
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
-H "Authorization: Bearer <apiToken>" \
-H "Content-Type: application/json" \
-d "<myCloudConnectorGroup>"
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 18
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
c. HEADER – Authorization: Bearer <apiToken>, Content-Type: application/json
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>" \
-H "Content-Type: application/json" \
-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"}'
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 19
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
c. HEADER – Authorization: Bearer <apiToken>, Content-Type: application/json
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 \
-H "Authorization: Bearer <apiToken>" \
-H "Content-Type: application/json" \
-d '{"VaultName":"<VaultName>","VaultPassword":"<VaultPassword>","CredentialType":1}'
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 20
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.
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 21
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:
https://api.provisioning.asavie.com/
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.
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 22
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 23
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 24
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 25
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 26
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
Asavie IoT Connect application note
© 2018 Asavie IoT Connect Version draft 27
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.