AWS iot-mi documentation change
Summary
Expanded documentation for setting up Amazon Kinesis integration with detailed IAM configuration steps, added structured setup procedures, and clarified notification types
Security assessment
The changes add detailed instructions for IAM role creation and permissions policies (including explicit kinesis:PutRecord permissions and trust relationships). While this improves security documentation, there is no evidence of addressing a specific existing vulnerability. The changes document security controls rather than fix security issues.
Diff
diff --git a/iot-mi/latest/devguide/managedintegrations-notifications.md b/iot-mi/latest/devguide/managedintegrations-notifications.md index 5e33c1d46..3024b034e 100644 --- a//iot-mi/latest/devguide/managedintegrations-notifications.md +++ b//iot-mi/latest/devguide/managedintegrations-notifications.md @@ -5 +5 @@ -Set up managed integrations notifications +Set up Amazon Kinesis for notificationsSet up managed integrations notificationsEvent types monitored with managed integrations @@ -9 +9,20 @@ Set up managed integrations notifications -Managed integrations notifications manage all notifications to customers facilitating real-time communication for delivering updates and insights on their devices. Whether it’s notifying customers of device events, device life cycle, or device state, managed integrations notifications play a critical role in enhancing the overall customer experience. By providing actionable information, customers can make informed decisions and optimize resource utilization. +Managed integrations notifications deliver updates and key insights from devices. Notifications include connector events, device commands, lifecycle events, OTA (Over-the-Air) updates, and error reports. These insights provide actionable information to create automated workflows, take immediate actions, or store event data for troubleshooting. + +Currently, only Amazon Kinesis data streams are supported as a destination for managed integrations notifications. You will first need to set up an Amazon Kinesis data stream and allow managed integrations access to the data stream before setting up notifications. + +## Set up Amazon Kinesis for notifications + +###### Amazon Kinesis setup steps + + * [Step 1: Create an Amazon Kinesis data stream](./managedintegrations-notifications.html#create-data-stream) + + * [Step 2: Create a permissions policy](./managedintegrations-notifications.html#create-permissions-policy) + + * [Step 3: Navigate to the IAM dashboard and select Roles](./managedintegrations-notifications.html#navigate-roles) + + * [Step 4: Use a Custom trust policy](./managedintegrations-notifications.html#custom-trust-policy) + + * [Step 5: Apply your permissions policy](./managedintegrations-notifications.html#apply-permissions-policy) + + * [Step 6: Enter a role name](./managedintegrations-notifications.html#finalize-role) + @@ -11 +29,0 @@ Managed integrations notifications manage all notifications to customers facilit -## Set up managed integrations notifications @@ -13 +30,0 @@ Managed integrations notifications manage all notifications to customers facilit -To setup managed integrations notifications, follow these steps: @@ -15 +32 @@ To setup managed integrations notifications, follow these steps: - 1. **Create an Amazon Kinesis data stream** +To setup Amazon Kinesis for managed integrations notifications, follow these steps: @@ -17 +34 @@ To setup managed integrations notifications, follow these steps: -To create a Kinesis data stream, follow the steps outlined in [Create and manage Kinesis data streams](https://docs.aws.amazon.com/streams/latest/dev/working-with-streams.html). +### Step 1: Create an Amazon Kinesis data stream @@ -19 +36 @@ To create a Kinesis data stream, follow the steps outlined in [Create and manage -Currently, only Amazon Kinesis data streams are supported as an option for a customer-managed destination for managed integrations notifications. +An Amazon Kinesis Data Stream can ingest a large amount of data in real time, durably store the data, and make the data available for consumption by applications. @@ -21 +38 @@ Currently, only Amazon Kinesis data streams are supported as an option for a cus - 2. **Create an Amazon Kinesis stream access role** +###### To create an Amazon Kinesis data stream @@ -23 +40,34 @@ Currently, only Amazon Kinesis data streams are supported as an option for a cus -Create an AWS Identity and Access Management access role that has permission to access the Kinesis stream you just created + * To create a Kinesis data stream, follow the steps outlined in [Create and manage Kinesis data streams](https://docs.aws.amazon.com/streams/latest/dev/working-with-streams.html). + + + + +### Step 2: Create a permissions policy + +Create a permissions policy that allows managed integrations to access your Kinesis data stream. + +###### To create a permissions policy + + * To create a permissions policy, copy the policy below and follow the steps outlined in [Create policies using the JSON editor](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html#access_policies_create-json-editor) + + { + "Version": "2012-10-17", + "Statement": [ + { + "Action": "kinesis:PutRecord", + "Resource": "*", + "Effect": "Allow" + } + ] + } + + + + +### Step 3: Navigate to the IAM dashboard and select Roles + +Open the IAM dashboard and click **Roles**. + +###### To navigate to the IAM dashboard + + * **Open the IAM dashboard and click Roles.** @@ -27 +76,0 @@ For more information, see [IAM role creation](https://docs.aws.amazon.com/IAM/la - 3. **Give user permissions to call the`CreateDestination` API** @@ -29 +78,66 @@ For more information, see [IAM role creation](https://docs.aws.amazon.com/IAM/la -The following policy defines the requirements for the user to call the [CreateDestination](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateDestination.html) API. If not set, the call to `CreateDestination` API will fail. + + +### Step 4: Use a Custom trust policy + +You can use a custom trust policy to grant managed integrations access to the Kinesis data stream. + +###### To use a custom trust policy + + * **Create a new role and choose Custom trust policy. Click Next.** + +The following policy allows managed integrations to assume the role. streams. + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "Service": "iotmanagedintegrations.amazonaws.com" + }, + "Action": "sts:AssumeRole" + } + ] + } + + + + +### Step 5: Apply your permissions policy + +Add the permissions policy you created in step 2 to the role. + +###### To add a permissions policy + + * **On the Add permissions page, search for and add the permissions policy you created in step 2. Click Next.** + + + + +### Step 6: Enter a role name + + * **Enter a role name and click Create role.** + + + + +## Set up managed integrations notifications + +###### Notification setup steps + + * Step 1: Give user permissions to call the CreateDestination API + + * Step 2: Call the CreateDestination API + + * Step 3: Call the CreateNotificationConfiguration API + + + + +To setup managed integrations notifications, follow these steps: + +### Step 1: Give user permissions to call the CreateDestination API + + * **Give user permissions to call the`CreateDestination` API** + +The following policy defines the requirements for the user to call the [CreateDestination](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateDestination.html) API. @@ -39 +153 @@ See [ Grant a user permissions to pass a role to an AWS service](https://docs.aw - "Resource":"arn:aws:iam::accountID:role/kinesis_stream_access_role", + "Resource":"arn:aws:iam::accountID:role/ROLE_CREATED_IN_PREVIOUS_STEP", @@ -54 +167,0 @@ See [ Grant a user permissions to pass a role to an AWS service](https://docs.aw - 4. **Call the`CreateDestination` API** @@ -56 +169,7 @@ See [ Grant a user permissions to pass a role to an AWS service](https://docs.aw -After you have created your Amazon Kinesis data stream and stream access role, call the [CreateDestination](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateDestination.html) API to create your customer-managed destination where the managed integrations notifications will be routed to. For the `deliveryDestinationArn` parameter, use the `arn` from your new Amazon Kinesis data stream. + + +### Step 2: Call the CreateDestination API + + * **Call the`CreateDestination` API** + +After you have created your Amazon Kinesis data stream and stream access role, call the [CreateDestination](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateDestination.html) API to create your notification destination where the notifications will be routed to. For the `DeliveryDestinationArn` parameter, use the `arn` from your new Amazon Kinesis data stream. @@ -62,2 +181,2 @@ After you have created your Amazon Kinesis data stream and stream access role, c - "ClientToken": "Random string" - "RoleArn": "arn:aws:iam::accountID:role/kinesis_stream_access_role" + "ClientToken": "string" + "RoleArn": "arn:aws:iam::accountID:role/ROLE_CREATED_IN_PREVIOUS_STEP" @@ -66 +185,10 @@ After you have created your Amazon Kinesis data stream and stream access role, c - 5. **Call the`CreateNotificationConfiguration` API** +###### Note + +`ClientToken` is an idempotency token. If you retry a request that completed successfully initially using the same client token and parameters, then the retry attempt will succeed without performing any further actions. + + + + +### Step 3: Call the CreateNotificationConfiguration API + + * **Call the`CreateNotificationConfiguration` API** @@ -68 +196 @@ After you have created your Amazon Kinesis data stream and stream access role, c -Lastly, you will create the notification configuration that will notify you of a chosen event type by routing a notification to your customer-managed destination represented by your Amazon Kinesis data stream. Call the [CreateNotificationConfiguration](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateNotificationConfiguration.html) API to create the notification configuration. In the `destinationName` parameter, use the same destination name as initially created when you created the customer-managed destination using the `CreateDestination` API. +Lastly, use the [CreateNotificationConfiguration](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_CreateNotificationConfiguration.html) API to create the notification configuration that routes the chosen event types to your destination represented by the Kinesis data stream. In the `DestinationName` parameter, use the same destination name as when you initially called the `CreateDestination` API. @@ -73 +201 @@ Lastly, you will create the notification configuration that will notify you of a - "ClientToken": "Random string" + "ClientToken": "string" @@ -79 +207 @@ Lastly, you will create the notification configuration that will notify you of a -### Event types monitored with managed integrations +## Event types monitored with managed integrations @@ -259 +387 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Device commands and events +Tag with IAM policies