AWS iot-sitewise medium security documentation change
Summary
Added AWS CLI procedures for creating IoT policies, things, and asset models; updated policy examples to use specific resource patterns and added security notes
Security assessment
The changes restrict IoT policy resource ARNs from wildcard (*) to SiteWiseTutorialDevice* patterns, implementing principle of least privilege. Added warnings about certificate security storage and explicit policy restrictions address potential over-permissive access risks. The 'Important' note about CLI size limits vs console restrictions indicates security-conscious guidance.
Diff
diff --git a/iot-sitewise/latest/userguide/ingest-data-from-iot-things.md b/iot-sitewise/latest/userguide/ingest-data-from-iot-things.md index 6c20f4c30..c835a608f 100644 --- a//iot-sitewise/latest/userguide/ingest-data-from-iot-things.md +++ b//iot-sitewise/latest/userguide/ingest-data-from-iot-things.md @@ -67,0 +68,5 @@ In this procedure, create an AWS IoT policy that allows your AWS IoT things to a +Console + + +Use the following procedure to create an IoT policy using the AWS IoT Core console: + @@ -84,6 +88,0 @@ In this procedure, create an AWS IoT policy that allows your AWS IoT things to a -JSON - - -**** - - @@ -96 +95 @@ JSON - "Resource": "arn:aws:iot:region:account-id:client/*" + "Resource": "arn:aws:iot:region:account-id:client/SiteWiseTutorialDevice*" @@ -136 +135 @@ JSON - "Resource": "arn:aws:iot:region:account-id:thing/*" + "Resource": "arn:aws:iot:region:account-id:thing/SiteWiseTutorialDevice*" @@ -140,0 +140 @@ JSON + 8. Choose **Create**. @@ -142 +141,0 @@ JSON -This policy enables your AWS IoT devices to establish connections and communicate with device shadows using MQTT messages. For more information about MQTT messages, see [What is MQTT?](https://aws.amazon.com/what-is/mqtt/). To interact with device shadows, your AWS IoT things publish and receive MQTT messages on topics that start with `$aws/things/`thing-name`/shadow/`. This policy incorporates a thing policy variable known as `${iot:Connection.Thing.ThingName}`. This variable substitutes the connected thing's name in each topic. The `iot:Connect` statement sets limitations on which devices can establish connections, ensuring that the thing policy variable can only substitute names starting with `SiteWiseTutorialDevice`. @@ -144 +142,0 @@ This policy enables your AWS IoT devices to establish connections and communicat -For more information, see [Thing policy variables](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policy-variables.html) in the _AWS IoT Developer Guide_. @@ -146 +143,0 @@ For more information, see [Thing policy variables](https://docs.aws.amazon.com/i -###### Note @@ -148 +145 @@ For more information, see [Thing policy variables](https://docs.aws.amazon.com/i -This policy applies to things whose names start with `SiteWiseTutorialDevice`. To use a different name for your things, you must update the policy accordingly. +AWS CLI @@ -150 +146,0 @@ This policy applies to things whose names start with `SiteWiseTutorialDevice`. T - 8. Choose **Create**. @@ -151,0 +148 @@ This policy applies to things whose names start with `SiteWiseTutorialDevice`. T +###### Important @@ -152,0 +150 @@ This policy applies to things whose names start with `SiteWiseTutorialDevice`. T +This policy uses wildcards to stay within AWS IoT SiteWise CLI size limits. For more restrictive permissions with explicit topic paths, create the policy through the AWS IoT SiteWise console instead. For more information, see the IoT policy example provided on the tab. @@ -153,0 +152,51 @@ This policy applies to things whose names start with `SiteWiseTutorialDevice`. T +Use the following AWS CLI command to create an IoT policy: + + + aws iot create-policy \ + --policy-name "SiteWiseTutorialDevicePolicy" \ + --policy-document '{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "iot:Connect", + "Resource": "arn:aws:iot:region:account-id:client/SiteWiseTutorialDevice*" + }, + { + "Effect": "Allow", + "Action": ["iot:Publish", "iot:Receive"], + "Resource": [ + "arn:aws:iot:region:account-id:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*" + ] + }, + { + "Effect": "Allow", + "Action": "iot:Subscribe", + "Resource": [ + "arn:aws:iot:region:account-id:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*" + ] + }, + { + "Effect": "Allow", + "Action": [ + "iot:GetThingShadow", + "iot:UpdateThingShadow", + "iot:DeleteThingShadow" + ], + "Resource": "arn:aws:iot:region:account-id:thing/SiteWiseTutorialDevice*" + } + ] + }' + +To verify that your policy was created successfully, use the following command: + + + aws iot get-policy --policy-name "SiteWiseTutorialDevicePolicy" + +This policy enables your AWS IoT devices to establish connections and communicate with device shadows using MQTT messages. For more information about MQTT messages, see [What is MQTT?](https://aws.amazon.com/what-is/mqtt/). To interact with device shadows, your AWS IoT things publish and receive MQTT messages on topics that start with `$aws/things/`thing-name`/shadow/`. This policy incorporates a thing policy variable known as `${iot:Connection.Thing.ThingName}`. This variable substitutes the connected thing's name in each topic. The `iot:Connect` statement sets limitations on which devices can establish connections, ensuring that the thing policy variable can only substitute names starting with `SiteWiseTutorialDevice`. + +For more information, see [Thing policy variables](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policy-variables.html) in the _AWS IoT Developer Guide_. + +###### Note + +This policy applies to things whose names start with `SiteWiseTutorialDevice`. To use a different name for your things, you must update the policy accordingly. @@ -158,0 +208,3 @@ In this procedure, you create and configure an AWS IoT thing. You can designate +Console + + @@ -204,0 +257,60 @@ This is the only time that you can download your thing's certificate and keys, w +AWS CLI + + +Follow these steps to create and configure an AWS IoT thing using the AWS CLI: + + 1. Open a command line and run the following command to create a directory for this tutorial: + + mkdir iot-sitewise-rule-tutorial + + 2. Navigate to the tutorial directory: + + cd iot-sitewise-rule-tutorial + + 3. Run the following command to create a directory for your thing's certificates: + + mkdir device1 + +If you're creating additional things, increment the number in the directory name accordingly to keep track of which certificates belong to which thing. + + 4. Create an AWS IoT thing: + + aws iot create-thing --thing-name "SiteWiseTutorialDevice1" + +###### Important + +The thing name must match the name pattern used in the policy that you created in Step 1. Otherwise, your device can't connect to AWS IoT. + + 5. Create a certificate and save the files. Note the certificate ARN from the output - you'll need it in the next steps: + + aws iot create-keys-and-certificate \ + --set-as-active \ + --certificate-pem-outfile "device1/device.pem.crt" \ + --public-key-outfile "device1/public.pem.key" \ + --private-key-outfile "device1/private.pem.key" + + 6. Attach the policy you created in Step 1 to the certificate: + + aws iot attach-policy \ + --policy-name "SiteWiseTutorialDevicePolicy" \ + --target "certificate-arn" + + 7. Attach the certificate to the thing: + + aws iot attach-thing-principal \ + --thing-name "SiteWiseTutorialDevice1" \ + --principal "certificate-arn" + + 8. Download the Amazon root CA certificate: + + curl https://www.amazontrust.com/repository/AmazonRootCA1.pem > AmazonRootCA1.pem + +This certificate is required for your device to successfully connect to AWS IoT. + + + + +###### Important + +Store your certificates and keys securely. You cannot download these credentials again after creating them. + @@ -219,0 +332,3 @@ In this procedure, you create an asset model in AWS IoT SiteWise to represent yo +Console + + @@ -278,0 +394,106 @@ This metric property calculates each device's average memory usage every 5 minut +AWS CLI + + +Follow these steps to create an asset model using the AWS CLI: + + 1. In your tutorial directory (`iot-sitewise-rule-tutorial`), create a file named `device-model.json` with the following content: + + { + "assetModelName": "SiteWise Tutorial Device Model", + "assetModelDescription": "Model for tutorial devices that stream CPU and memory usage data", + "assetModelType": "ASSET_MODEL", + "assetModelProperties": [ + { + "name": "CPU Usage", + "dataType": "DOUBLE", + "unit": "%", + "type": { + "measurement": {} + } + }, + { + "name": "Memory Usage", + "dataType": "DOUBLE", + "unit": "%", + "type": { + "measurement": {} + } + }, + { + "name": "Average CPU Usage", + "dataType": "DOUBLE", + "unit": "%", + "type": { + "metric": { + "expression": "avg(cpu)", + "variables": [ + { + "name": "cpu",