Prerequisites

Security Token Service (STS) Endpoint

In your AWS account the Security Token Service (STS) Endpoint should be enabled for eu-central-1 region.

iot:Data-ATS Endpoint

In your AWS account the iot:Data-ATS Endpoint should be enabled for region where you are rolling out AWS Integration.

IAM role permissions

To successfully roll out the CloudFormation (CFN) stack, the customer must ensure that all the permissions listed in cfn stack description are granted.

Configuration via Frontend

For setting up the AWS integration, use the Cloud Integration Wizard in the 1NCE OS portal.
Click 'New Integration' and select AWS integration as integration type.

Use a descriptive name and select the event types that you would like to receive.

Configuration of an AWS Integration in the 1NCE portal

Be aware that integration with status ROLLOUT_STARTED will be created in the Cloud Integrator and you will be taken to AWS to complete the configuration over there.
This generates a JWT that is only valid for an hour. Once the JWT becomes invalid the rollout has to be restarted.

After the configuration click proceed and you will be prompted to go to the AWS console. Continue and now AWS should be open on the 'Quick Create Stack' page. Here you will see things such as the name that was previously given, integration token, etc. If this information is correct, acknowledge AWS requirements and press 'create stack'.

It will take some time for the stack to be created. Nested stacks are shown by the filter option 'view nested' on the top. Once it is done, it should look like this in AWS and 1nceOS portal respectively:

Validate Integration

A device being able to send data is a prerequisite for this step. For more information refer to the cloud integrator documentation.

Once your stack has been rolled out, you can test your integration using one of your devices or by using Test AWS Integration endpoint. In AWS go to the IoT Core service. Navigate to the MQTT test client and subscribe to # as shown below:

Doing this will subscribe to all topics so if the stack was successfully rolled out, you should see data show up as shown below:

If the integration was successfully created, rolled out and actived, Integration Active will appear.

Edit AWS integration

It is possible to edit the 1nceOS integration options through the front-end by clicking the edit-button as shown below:

Restart AWS integration

There is a possibility that your integration fails. When this happens, it will be visible in the 1nceOS portal as shown below:

By clicking the restart button, there will be an attempt to verify the integration. During that time an event of type TEST_MESSAGE will be sent out. For more information refer to event-type documentation

Delete AWS Integration

There are two ways to delete the integration:

Front-end

You can delete your AWS Integration in the front-end of 1NCE OS or using API. In this case, you need to delete your AWS stack manually.

AWS

When the deletion is initiated from your AWS stack, there are no further actions needed. The callback function will automatically trigger the deletion of the AWS Integration in 1NCE OS.

CFN stack description

The following section describes resources that will be deployed with the stack. Stack contains 3 nested stacks.

AWS Integration Resource stack

IAM cross account role

Stack creates Cross Account IAM role with following permissions for 1NCE OS AWS account 672401624271:

'iot:DescribeEndpoint' - Retrieve the AWS IoT endpoint.
'iot:Publish' - Publish MQTT messages to AWS IoT Core.

Callback stacks

Two stacks are rolled out for callback operations:

Callback 'create' stack: Provisions resources required to complete the integration with 1NCE OS.
Callback 'delete' stack: Provisions resources that notify 1NCE OS when the stack is deleted from the customer's AWS account.

Both the 'create' and 'delete' stacks provision identical resources.

Download code lambda function

A Lambda function that downloads the actual callback Lambda function.

Callback lambda function

The 'create' callback stack Lambda function notifies the 1NCE OS that the integration rollout has been successfully completed.
The 'delete' callback stack Lambda function notifies the 1NCE OS when the CloudFormation stack is deleted from the customer's AWS account.

Notifications are sent via API calls.

S3 bucket

S3 buckets where the actual code for the 'create' and 'delete' callback Lambda functions are placed.

Stack execution IAM Role

For each stack execution IAM role with the following permissions is created:

Logs:

'logs:CreateLogGroup' - Allows creation of CloudWatch Log Groups.
'logs:CreateLogStream' - Allows creation of log streams within the created log groups.
'logs:PutLogEvents' - Allows publishing log events to the created log streams.

Customers S3 bucket:

's3:DeleteObject' - Allows deletion of objects from the specified S3 bucket.
's3:GetObject' - Allows reading objects from the specified S3 bucket.
's3:ListBucket' - Allows listing objects in the specified S3 bucket.
's3:PutObject' - Allows uploading (writing) objects to the specified S3 bucket.
's3:GetBucketPolicy' - Allows retrieval of the bucket policy for the specified S3 bucket.
's3:PutObjectTagging' - Allows adding or updating tags on an S3 object.

1NCE OS S3 bucket:

's3:GetObject' - Allows reading objects from 1NCE OS S3 bucket.
's3:GetObjectTagging' - Allows retrieving tags associated with an 1NCE OS S3 object.
's3:ListBucket' - Allows listing objects in the 1NCE OS S3 bucket.

AWS Configuration