Just a few weeks ago, Amazon Web Services (AWS) announced that they added the ability for their customers to manage IoT solutions. More specifically, they are offering a managed IoT platform that allows to connect your devices using HTTP or MQTT, and that integrates with other AWS services to simplify things like message processing, persistence in S3 or DynamoDB, … you name it! And of course, this is meant to scale to billions of devices, although I have to admit I have not tested that just yet 🙂
In this article, I will show you how you can connect your Eclipse Kura gateway to AWS IoT. Since the authorization and overall security mechanisms in AWS IoT heavily rely on certificates, the only tricky bit will be for us to properly configure the Kura gateway so as it establishes a trusted connection to the AWS backend.
- You need to make sure that you are running Kura 1.3 or later, as it includes some fixes to be compatible with AWS IoT,
- You will, of course, need to have an AWS account to be able to use the AWS IoT beta.
Provision your thing, certificate and policy in AWS IoT
Most of the operations that will allow you to manage your AWS IoT fleet can be performed either from the Web UI, or using the AWS CLI command line tool.
While you will probably want to use the CLI when you will be familiar with the platform, I suggest that you start your first experiments using the web interface.
So you need to create a “Thing”, with an attached certificate and policy to allow it to communicate. The easiest way to go through this is to create the thing from the web console, and then use the “connect wizard” to connect it. See the screenshots below, this should be pretty straightforward
You will end up with 3 files that you need to download:
- A public/private key pair, just like what you used for e.g. SSH or GitHub. AWS IoT keeps track of the public key, and you will use the private key to encrypt the communications.
- A certificate used by your client (in our case Kura), to authenticate the server.
Create a Java keystore
In Java, anything involving certificates is typically done using a so-called keystore: a secured storage facility for your certificates and cryptographic keys.
We will be able to add the AWS IoT certificates and keys in our keystore right from the Kura Web UI, but we first need to manually create the keystore. We will seed this keystore with the root Certificate Authority that is used to sign AWS IoT’s certificate.
sudo mkdir /opt/eclipse/security cd /opt/eclipse/security curl https://www.symantec.com/content/en/us/enterprise/verisign/roots/VeriSign-Class%203-Public-Primary-Certification-Authority-G5.pem > /tmp/root-CA.pem sudo keytool -import -trustcacerts -alias verisign -file /tmp/root-CA.pem -keystore cacerts -storepass changeit
This will warn you that the certificate is already installed in the system-wide keystore, but add it anyways.
Setup SSL communication settings in Kura
First, we need to make sure that the SSLManagerService is properly configured to use our freshly created keystore.
/opt/eclipse/security/cacerts(this should be the default value already,
changeit(or whichever password you picked earlier, when creating the keystore).
Next, in the ‘Settings’ section of the Kura UI, we have access to a pretty convenient way to add new keys or certificate to your keystore. This is where we want to add our private key, and AWS IoT’s certificate, that will be used for SSL mutual authentication.
Now all is left to do is head over to the “SSL Mutual Authentication” tab in the settings, and input the following:
- Private key: the contents of the file in which you just put the PKCS8 version of the private key,
- Private key storage password:
changeit(or whichever password you picked earlier, when creating the keystore),
- Public key: the contents of the certificate file,
- Storage alias: this has to be the same information you have in the MqttDataTransport config section for
topic.context.account-name. Default value is
account-name. This alias is important since it’s used by Kura to actually use the correct key/certificate pair when establishing the MQTT communication.
A few last tweaks
As there are several limitations in the MQTT broker available at AWS IoT, you will need to change some of the default settings in Kura. In particular, the broker won’t let you subscribe or publish on topics prefixed by the ‘$’ sign (except for the
$aws/ topic hierarchy).
- CloudService: adjust the topic.control-prefix setting so as it doesn’t include a dollar sign. This prefix control where things like your device “birth certificate” are being published. If it has a dollar-prefix, you will be in trouble since AWS will just drop your MQTT connection!
- MqttDataTransport: change the
lwt.topicso as it does not have a topic with a dollar prefix anymore. And, last but not least, change the broker URL to the one associated with your AWS IoT account. It should be something like:
mqtts://AHFXKRXXXXXXX.iot.us-east-1.amazonaws.com:8883(mind the mqtts protocol, and the port 8883)
That’s it! You should be good to go!
From now on, all your Kura bundles that are using the DataService or the CloudService will be talking to the AWS IoT backend. Therefore if your Kura application is sending JSON payloads, you will be able to set up custom rules to store your data in DynamoDB or invoke Lambda functions. You may also want to experiment with the Thing Shadow API to have the ability to manage your gateway or its apps even when it is offline.
And you? What are you going to build with Eclipse Kura and AWS IoT?
8 replies on “Tutorial: Connecting Eclipse Kura to AWS IoT”
Anything similar for using Paho? Any tips?
To make it work, I must to clear the username and the password in the MqttDataTransport (but when I restart kura it fill with default values and I need to clear again)
and disable “publish.retain ” in greenhouse publisher
thanks for this tutorial. Are there any news on Kura to allow username and passwords to be NULL – to be able to connect to AWS IoT after a restart of Kura ?
I am pretty sure this is fixed in the upcoming Kura 2.0 release. More specifically, this was addressed with this bug.
Great news. Is there already a Release Date for Kura 2.0
I am looking forward
I have converted the private key.But I am getting the error below while applying certificates.Please help!
You should check the contents of the kura.log file in /var/log, it is likely you will find a more detailed error trace there. Feel free to post it here, or, better, on kura-dev mailing list: https://dev.eclipse.org/mailman/listinfo/kura-dev
Thanks a lot Benjamin!
I haven’t created the java keystore, but a reboot was required to make it work.