How to provision devices using AWS-IoT?
The Internet of Things (IoT) has revolutionized the way we interact with the world. From smart homes to connected cities, IoT enables devices to collect, share, and act on data in real-time. This connectivity not only improves efficiency and convenience but also opens new opportunities for innovation in various industries.
What is Provisioning in IoT?
Provisioning in IoT refers to the process of registering, configuring, and securing devices so they can effectively communicate with an IoT platform. This includes assigning credentials, setting up security policies, and installing necessary software. Efficient provisioning is crucial for the management and scalability of any IoT network, ensuring that devices are ready to operate from the moment they are connected.
What is AWS IoT Fleet Provisioning?
AWS IoT Core offers a robust solution for device provisioning known as Fleet Provisioning. This tool allows an automated and secure registration and configuration of large numbers of devices, significantly reducing the time and effort required to bring new units online.
In this article, we will explore how to use AWS IoT Fleet Provisioning to efficiently provision devices, ensuring smooth and secure integration into your IoT network.
Devices in AWS IoT
In AWS IoT, devices are known as “things.” A thing is the virtual representation of a device that can connect to the IoT network via MQTT. Each thing has a unique certificate and private key to connect to the network.
The following code is the simplest connection of a device to AWS IoT using the
import { mqtt, iot } from 'aws-iot-device-sdk-v2';
const config = iot.AwsIotMqttConnectionConfigBuilder
.new_mtls_builder_from_path('certificate-filepath', 'private-key-filepath')
.with_certificate_authority_from_path(undefined, 'certificate-authority-filepath')
.with_client_id('client-id')
.with_endpoint('endpoint')
.build();
const connection = new mqtt.MqttClient().new_connection(config);How to obtain certificates?
The simplest way to obtain connection certificates and private key is to create a single thing in the AWS
You also need to select or create a policy for the certificate; the policy grants permissions for the device with the new certificate to connect, publish, and subscribe to the required MQTT topics. If this is your first time setting up a policy and you are not using the resources for production, you can use a policy with full access like the following:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "*",
"Resource": "*"
}
]
}The above policy will allow you to use all actions and resources specific to IoT Core described
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:Connect",
"Resource": "arn:aws:iot:us-east-1:123456789:client/my-client"
},
{
"Effect": "Allow",
"Action": "iot:Subscribe",
"Resource": "arn:aws:iot:us-east-1:123456789:topicfilter/some/topic"
}
]
}The above policy will allow connection only with a clientId called “my-client” and subscription to the “some/topic” topic.
At the end of the form, you will get the necessary files for connection once, download them and use them to configure your device.
...
.new_mtls_builder_from_path('certificate-filepath', 'private-key-filepath')
...What is a Certificate Authority (CA)?
A certificate authority (CA) is a trusted entity that issues and manages digital certificates. In the context of IoT, a CA validates that the devices connecting to the network are legitimate and trustworthy. You can set up your own CA to generate your certificates or use the one from Amazon that you downloaded in the previous step (Amazon Root CA 1).
...
.with_certificate_authority_from_path(undefined, 'certificate-authority-filepath')
...Should I do this with all my devices?
The previous steps are correct if you are experimenting with IoT-Core and the number of devices is small, however, if you are looking to automate the configuration of your devices and scale your business, Fleet Provisioning might be a better alternative.
Step by step to provision devices with AWS IoT Fleet Provisioning
The goal of provisioning is to automatically create a new "thing" when a new device comes online and get the necessary certificate and private key to communicate with the network. AWS provides two methods for fleet provisioning:
Provisioning by claim
Provisioning by trusted user
In this entry, we focus on provisioning by trusted user.
What is a Claim?
A claim is a provisional certificate and private key with limited permissions that the device will use to connect to AWS IoT for the first time and obtain the final credentials after completing the provisioning process.
What is a trusted user?
A trusted user is a user with permissions to generate an AWS IoT claim, which will be used to provision a device.
IoT Templates
The first step in configuring provisioning is to create an IoT template from the
Attributes
Thing groups
Policies
To create the template, select the provisioning by trusted user option and enable the state.
In the form, you will be asked to create two roles:
Provisioning role: grants the AWSIoTThingsRegistration permission group so that the template can use AWS IoT services to register a new thing.
User provisioning role: grants only the CreateProvisioningClaim permission so that the user can get a claim if they have access and know the name of an IoT template.
You can also enable a pre-provisioning action to verify the provisioning, more details
Finally, you will be asked to create a policy for the device; remember that the result of provisioning will be the credentials for your device to connect to AWS, so this policy should have the necessary permissions to connect, publish, or subscribe to the topics of interest, as we discussed in previous sections.
Editing an IoT template
The IoT template is simply a JSON format of the characteristics selected in the previous form. A simple template might look like this:
{
"Parameters": {
"MyParameter": {
"Type": "String"
}
},
"Resources": {
"policy_name": {
...
},
"certificate": {
...
},
"thing": {
"Type": "AWS::IoT::Thing",
"OverrideSettings": {
"AttributePayload": "MERGE",
"ThingGroups": "DO_NOTHING",
"ThingTypeName": "REPLACE"
},
"Properties": {
"AttributePayload": {
"myParameter": {
"Ref": "MyParameter"
}
},
"ThingGroups": [],
"ThingName": {"Ref": "MyParameter"}
}
}
},
"DeviceConfiguration": {}
}Let's look at the important parts:
Parameters: these are the names of the variables that should be sent from the device during the provisioning process and that the template will use to name the thing and other resources. Other sections of the template can access these variables using the Ref keyword.
..."ThingName": {"Ref": "MyParameter"}Thing: These are the characteristics of the thing to be created, including its properties and how to override them. The AttributePayload property allows you to save key information for the device.
DeviceConfiguration: These are the properties that can be sent from AWS IoT to the device at the end of provisioning.
Generate a claim to start provisioning
Once the template is created, a user can use it to generate a claim and start provisioning. To obtain the claim, you need AWS credentials (accessKeyId and secretAccessKey) and the following permission:
{
"Sid": "IotProvisioningPermissions",
"Effect": "Allow",
"Action": [
"iot:CreateProvisioningClaim"
],
"Resource": [
"*"
]
}The following code is a simple version of how to generate a claim using the
import { CreateProvisioningClaimCommand, IoTClient } from "@aws-sdk/client-iot";
const iotClient = new IoTClient({
region: 'AWS_REGION',
credentials: {
accessKeyId: 'AWS_ACCESS_KEY_ID',
secretAccessKey: 'AWS_SECRET_ACCESS_KEY',
}
});
iotClient.send(new CreateProvisioningClaimCommand({
templateName: 'template-name'
})).then((claim) => {
...
});The content of the claim will be similar to the following:
{
"certificateId": "string",
"certificatePem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
"expiration": "2024-06-26T16:44:29.000Z",
"keyPair": {
"PrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n....\n-----END RSA PRIVATE KEY-----\n",
"PublicKey": "-----BEGIN PUBLIC KEY-----\n....\n-----END PUBLIC KEY-----\n"
}
}You must provide the claim content to the device, which will use the certificatePem and PrivateKey to connect to AWS and continue provisioning.
Complete provisioning
Each claim is valid for only 5 minutes, so you must send it to your device as soon as possible. How you send the claim to your device depends on your project and business model.
When the device receives the claim, it should connect to AWS IoT using the certificatePem and PrivateKey. It will also need the certificate authority (CA); however, since the CA is generic for all of AWS (or for your company if you use a custom CA), you can retain the value in your device.
To connect to AWS IoT, you can use the MQTT client provided in previous sections or similar ones. Once connected, the provisioning will consist of two parts: obtaining the final credentials and activating the credentials.
Obtaining final credentials
With the following steps, you will obtain the final credentials (certificate and private key) to connect to AWS IoT. However, the credentials will not be activated until the second part is completed.
Subscribe to the MQTT topics: $aws/certificates/create/json/accepted and $aws/certificates/create/json/rejected.
Publish an empty message to the topic $aws/certificates/create/json.
You must wait to receive a message on the /accepted or /rejected topics.
If the topic is /rejected, something went wrong, and you must terminate the provisioning.
If the topic is /accepted, you will receive something similar to:
{
"certificateId": "string",
"certificatePem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
"privateKey": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n",
"certificateOwnershipToken": "string"
}Save the certificatePem and privateKey on your device; these will be the final credentials to connect to AWS IoT.
Activating final credentials
Once the credentials have been generated with the previous steps, it is necessary to activate them. For this, the following steps are required:
Subscribe to the topics $aws/provisioning-templates/template-name/provision/json/accepted and $aws/provisioning-templates/template-name/provision/json/rejected. Replace template-name with the name of the template we created earlier.
Publish a message to the topic $aws/provisioning-templates/template-name/provision/json. The message must contain the certificateOwnershipToken from the previous message response and the parameter values that were added at the beginning of the IoT template. The message may look similar to the following:
{
"certificateOwnershipToken": "value",
"parameters": {
"MyParameter": "value"
}
}You must wait to receive a message on the /accepted or /rejected topics.
If the topic is /rejected, something went wrong, and you must terminate the provisioning.
If the topic is /accepted, you will receive a response with the thingName and deviceConfiguration, which contains the values you have configured in the DeviceConfiguration key of the IoT template.
{
"deviceConfiguration": {
...
},
"thingName": "name"
}Use the new credentials to configure your device's MQTT client.
Following these steps, the device will be able to obtain the final credentials and connect to AWS IoT, a new thing will be automatically registered in AWS IoT, and you will be able to communicate with your device through MQTT.
We'd love to discuss your upcoming IoT project and how we can support you in achieving your goals. Schedule a call with us here:
