Pre-provisioning hooks - AWS IoT Core

Pre-provisioning hooks

When using AWS IoT fleet provisioning, you can set up a Lambda function to validate parameters passed from the device before allowing the device to be provisioned. This Lambda function must exist in your account before you provision a device because it's called every time a device sends a request through RegisterThing. For devices to be provisioned, your Lambda function must accept the input object and return the output object described in this section. The provisioning proceeds only if the Lambda function returns an object with "allowProvisioning": True.

Important

AWS recommends using pre-provisioning hooks when creating provisioning templates to allow more control of which and how many devices your account onboards.

Pre-provision hook input

AWS IoT sends this object to the Lambda function when a device registers with AWS IoT.

{ "claimCertificateId" : "string", "certificateId" : "string", "certificatePem" : "string", "templateArn" : "arn:aws:iot:us-east-1:1234567890:provisioningtemplate/MyTemplate", "clientId" : "221a6d10-9c7f-42f1-9153-e52e6fc869c1", "parameters" : { "string" : "string", ... } }

The parameters object passed to the Lambda function contains the properties in the parameters argument passed in the RegisterThing request payload.

Pre-provision hook return value

The Lambda function must return a response that indicates whether it has authorized the provisioning request and the values of any properties to override.

The following is an example of a successful response from the pre-provisioning function.

{ "allowProvisioning": true, "parameterOverrides" : { "Key": "newCustomValue", ... } }

"parameterOverrides" values will be added to "parameters" parameter of the RegisterThing request payload.

Note
  • If the Lambda function fails or doesn't return the "allowProvisioning" parameter in the response, the provisioning request will fail and the error will be returned in the response.

  • The Lambda function must finish running and return within 5 seconds, otherwise the provisioning request fails.

Pre-provisioning hook Lambda example

Python

An example of a pre-provisioning hook Lambda in Python.

import json def pre_provisioning_hook(event, context): print(event) return { 'allowProvisioning': True, 'parameterOverrides': { 'DeviceLocation': 'Seattle' } }
Java

An example of a pre-provisioning hook Lambda in Java.

Handler class:

package example; import java.util.Map; import java.util.HashMap; import com.amazonaws.services.lambda.runtime.Context; import com.amazonaws.services.lambda.runtime.RequestHandler; public class PreProvisioningHook implements RequestHandler<PreProvisioningHookRequest, PreProvisioningHookResponse> { public PreProvisioningHookResponse handleRequest(PreProvisioningHookRequest object, Context context) { Map<String, String> parameterOverrides = new HashMap<String, String>(); parameterOverrides.put("DeviceLocation", "Seattle"); PreProvisioningHookResponse response = PreProvisioningHookResponse.builder() .allowProvisioning(true) .parameterOverrides(parameterOverrides) .build(); return response; } }

Request class:

package example; import java.util.Map; import lombok.Builder; import lombok.Data; import lombok.AllArgsConstructor; import lombok.NoArgsConstructor; @Data @Builder @AllArgsConstructor @NoArgsConstructor public class PreProvisioningHookRequest { private String claimCertificateId; private String certificateId; private String certificatePem; private String templateArn; private String clientId; private Map<String, String> parameters; }

Response class:

package example; import java.util.Map; import lombok.Builder; import lombok.Data; import lombok.AllArgsConstructor; import lombok.NoArgsConstructor; @Data @Builder @AllArgsConstructor @NoArgsConstructor public class PreProvisioningHookResponse { private boolean allowProvisioning; private Map<String, String> parameterOverrides; }