AWS iot high security documentation change
Summary
Added detailed section 'Using pre-provisioning hooks with the AWS CLI' including security guidance about cross-service confused deputy prevention
Security assessment
Explicitly addresses cross-service confused deputy prevention with specific policy recommendations, which is a security vulnerability mitigation
Diff
diff --git a/iot/latest/developerguide/provision-wo-cert.md b/iot/latest/developerguide/provision-wo-cert.md index 2d07090b1..86ebd69a0 100644 --- a//iot/latest/developerguide/provision-wo-cert.md +++ b//iot/latest/developerguide/provision-wo-cert.md @@ -5 +5 @@ -Provisioning by claimProvisioning by trusted user +Provisioning by claimProvisioning by trusted userUsing pre-provisioning hooks with the AWS CLI @@ -176,0 +177,123 @@ The device is now ready to communicate normally with AWS IoT. +## Using pre-provisioning hooks with the AWS CLI + +The following procedure creates a provisioning template with pre-provisioning hooks. The Lambda function used here is an example that can be modified. + +###### To create and apply a pre-provisioning hook to a provisioning template + + 1. Create a Lambda function that has a defined input and output. Lambda functions are highly customizable. `allowProvisioning` and `parameterOverrides` are required for creating pre-provisioning hooks. For more information about creating Lambda functions, see [Using AWS Lambda with the AWS Command Line Interface](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-awscli.html). + +The following is an example of a Lambda function output: + + { + "allowProvisioning": True, + "parameterOverrides": { + "incomingKey0": "incomingValue0", + "incomingKey1": "incomingValue1" + } + } + + 2. AWS IoT uses resource-based policies to call Lambda, so you must give AWS IoT permission to call your Lambda function. + +###### Important + +Be sure to include the `source-arn` or `source-account` in the global condition context keys of the policies attached to your Lambda action to prevent permission manipulation. For more information about this, see [Cross-service confused deputy prevention](./cross-service-confused-deputy-prevention.html). + +The following is an example using [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) give IoT permission to your Lambda. + + aws lambda add-permission \ + --function-name myLambdaFunction \ + --statement-id iot-permission \ + --action lambda:InvokeFunction \ + --principal iot.amazonaws.com + + 3. Add a pre-provisioning hook to a template using either the [create-provisioning-template](https://docs.aws.amazon.com/cli/latest/reference/iot/create-provisioning-template.html) or [update-provisioning-template](https://docs.aws.amazon.com/cli/latest/reference/iot/update-provisioning-template.html) command. + +The following CLI example uses the [create-provisioning-template](https://docs.aws.amazon.com/cli/latest/reference/iot/create-provisioning-template.html) to create a provisioning template that has pre-provisioning hooks: + + aws iot create-provisioning-template \ + --template-name myTemplate \ + --provisioning-role-arn arn:aws:iam:us-east-1:1234564789012:role/myRole \ + --template-body file://template.json \ + --pre-provisioning-hook file://hooks.json + +The output of this command looks like the following: + + { + "templateArn": "arn:aws:iot:us-east-1:1234564789012:provisioningtemplate/myTemplate", + "defaultVersionId": 1, + "templateName": myTemplate + } + +You can also load a parameter from a file instead of typing it all as a command line parameter value to save time. For more information, see [Loading AWS CLI Parameters from a File](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html). The following shows the `template` parameter in expanded JSON format: + + { + "Parameters" : { + "DeviceLocation": { + "Type": "String" + } + }, + "Mappings": { + "LocationTable": { + "Seattle": { + "LocationUrl": "https://example.aws" + } + } + }, + "Resources" : { + "thing" : { + "Type" : "AWS::IoT::Thing", + "Properties" : { + "AttributePayload" : { + "version" : "v1", + "serialNumber" : "serialNumber" + }, + "ThingName" : {"Fn::Join":["",["ThingPrefix_",{"Ref":"SerialNumber"}]]}, + "ThingTypeName" : {"Fn::Join":["",["ThingTypePrefix_",{"Ref":"SerialNumber"}]]}, + "ThingGroups" : ["widgets", "WA"], + "BillingGroup": "BillingGroup" + }, + "OverrideSettings" : { + "AttributePayload" : "MERGE", + "ThingTypeName" : "REPLACE", + "ThingGroups" : "DO_NOTHING" + } + }, + "certificate" : { + "Type" : "AWS::IoT::Certificate", + "Properties" : { + "CertificateId": {"Ref": "AWS::IoT::Certificate::Id"}, + "Status" : "Active", + "ThingPrincipalType" : "EXCLUSIVE_THING" + } + }, + "policy" : { + "Type" : "AWS::IoT::Policy", + "Properties" : { + "PolicyDocument" : { + "Version": "2012-10-17", + "Statement": [{ + "Effect": "Allow", + "Action":["iot:Publish"], + "Resource": ["arn:aws:iot:us-east-1:504350838278:topic/foo/bar"] + }] + } + } + } + }, + "DeviceConfiguration": { + "FallbackUrl": "https://www.example.com/test-site", + "LocationUrl": { + "Fn::FindInMap": ["LocationTable",{"Ref": "DeviceLocation"}, "LocationUrl"]} + } + } + +The following shows the `pre-provisioning-hook` parameter in expanded JSON format: + + { + "targetArn" : "arn:aws:lambda:us-east-1:765219403047:function:pre_provisioning_test", + "payloadVersion" : "2020-04-01" + } + + + + @@ -183 +306 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Bulk registration +Device provisioning @@ -185 +308 @@ Bulk registration -Provisioning templates +Provisioning devices that have device certificates