# Securing users and devices with AWS IoT Jobs Securing users and devices for Jobs To authorize users to use AWS IoT Jobs with their devices, you must grant them permissions by using IAM policies. The devices must then be authorized by using AWS IoT Core policies to connect securely to AWS IoT, receive job executions, and update the execution status. ## Required policy type for AWS IoT Jobs The following table shows the different types of policies that you must use for authorization. For more information about the required policy to use, see [Authorization](iot-authorization.md). **Required policy type** | Use case | Protocol | Authentication | Control plane/data plane | Identity type | Required policy type | | --- | --- | --- | --- | --- | --- | | Authorize an administrator, operator, or Cloud Service to work securely with Jobs | HTTPS | AWS Signature Version 4 authentication (port 443) | Both control plane and data plane | Amazon Cognito Identity, IAM, or federated user | IAM policy | | Authorize your IoT device to work securely with Jobs | MQTT/HTTPS | TCP or TLS mutual authentication (port 8883 or 443) | Data plane | X.509 certificates | AWS IoT Core policy | To authorize AWS IoT Jobs operations that can be performed both on the control plane and data plane, you must use IAM policies. The identities must have been authenticated with AWS IoT to perform these operations, which must be [Amazon Cognito identities](cognito-identities.md) or [IAM users, groups, and roles](iam-users-groups-roles.md). For more information about authentication, see [Authentication](authentication.md). The devices must now be authorized on the data plane by using AWS IoT Core policies to connect securely to the device gateway. The device gateway enables devices to securely communicate with AWS IoT, receive job executions, and update the job execution status. Device communication is secured by using secure [MQTT](mqtt.md) or [HTTPS publish](http.md) communication protocols. These protocols use [X.509 client certificates](x509-client-certs.md) that are provided by AWS IoT to authenticate the device connections. The following shows how you authorize your users, cloud services, and devices to use AWS IoT Jobs. For information about control plane and data plane API operations, see [AWS IoT jobs API operations](jobs-api.md). **Topics** + [ ## Required policy type for AWS IoT Jobs ](#jobs-required-policy) + [ # Authorizing users and cloud services to use AWS IoT Jobs ](iam-policy-users-jobs.md) + [ # Authorizing your devices to securely use AWS IoT Jobs on the data plane ](iot-data-plane-jobs.md) # Authorizing users and cloud services to use AWS IoT Jobs Authorizing Jobs users and cloud services To authorize your users and cloud services, you must use IAM policies on both the control plane and data plane. The policies must be used with HTTPS protocol and must use AWS Signature Version 4 authentication (port 443) to authenticate users. **Note** AWS IoT Core policies must not be used on the control plane. Only IAM policies are used for authorizing users or Cloud Services. For more information about using the required policy type, see [Required policy type for AWS IoT Jobs](iot-jobs-security.md#jobs-required-policy). IAM policies are JSON documents that contain policy statements. Policy statements use *Effect*, *Action*, and *Resource* elements to specify resources, allowed or denied actions, and conditions under which actions are allowed or denied. For more information, see [IAM JSON Policy Elements Reference](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_elements.html) in the *IAM user Guide*. **Warning** We recommend that you don't use wildcard permissions, such as `"Action": ["iot:*"]` in your IAM policies or AWS IoT Core policies. Using wildcard permissions is not a recommended security best practice. For more information, see [AWS IoT policy overly permissive](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/audit-chk-iot-policy-permissive.html). ## IAM policies on the control plane On the control plane, IAM policies use the `iot:` prefix with the action to authorize the corresponding jobs API operation. For example, the `iot:CreateJob` policy action grants the user permission to use the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) API. ### Policy actions The following table shows a list of IAM policy actions and permissions to use the API actions. For information about resource types, see [Resource types defined by AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-job). For more information about AWS IoT actions, see [Actions defined by AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html). **IAM policy actions on control plane** | Policy action | API operation | Resource types | Description | | --- | --- | --- | --- | | iot:AssociateTargetsWithJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to associate a group with a continuous job. The iot:AssociateTargetsWithJob permission is checked every time a request is made to associate targets. | | iot:CancelJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html) | job | Represents the permission to cancel a job. The iot:CancelJob permission is checked every time a request is made to cancel a job. | | iot:CancelJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to cancel a job execution. The iot: CancelJobExecution permission is checked every time a request is made to cancel a job execution. | | iot:CreateJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to create a job. The iot: CreateJob permission is checked every time a request is made to create a job. | | iot:CreateJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to create a job template. The iot: CreateJobTemplate permission is checked every time a request is made to create a job template. | | iot:DeleteJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html) | job | Represents the permission to delete a job. The iot: DeleteJob permission is checked every time a request is made to delete a job. | | iot:DeleteJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobTemplate.html) | jobtemplate | Represents the permission to delete a job template. The iot: CreateJobTemplate permission is checked every time a request is made to delete a job template. | | iot:DeleteJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to delete a job execution. The iot: DeleteJobExecution permission is checked every time a request is made to delete a job execution. | | iot:DescribeJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html) | job | Represents the permission to describe a job. The iot: DescribeJob permission is checked every time a request is made to describe a job. | | iot:DescribeJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to describe a job execution. The iot: DescribeJobExecution permission is checked every time a request is made to describe a job execution. | | iot:DescribeJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html) | jobtemplate | Represents the permission to describe a job template. The iot: DescribeJobTemplate permission is checked every time a request is made to describe a job template. | | iot:DescribeManagedJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeManagedJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeManagedJobTemplate.html) | jobtemplate | Represents the permission to describe a managed job template. The iot: DescribeManagedJobTemplate permission is checked every time a request is made to describe a managed job template. | | iot:GetJobDocument | [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html) | job | Represents the permission to get the job document for a job. The iot:GetJobDocument permission is checked every time a request is made to get a job document. | | iot:ListJobExecutionsForJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html) | job | Represents the permission to list the job executions for a job. The iot:ListJobExecutionsForJob permission is checked every time a request is made to list the job executions for a job. | | iot:ListJobExecutionsForThing | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html) | thing | Represents the permission to list the job executions for a job. The iot:ListJobExecutionsForThing permission is checked every time a request is made to list the job executions for a thing. | | iot:ListJobs | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html) | none | Represents the permission to list the jobs. The iot:ListJobs permission is checked every time a request is made to list the jobs. | | iot:ListJobTemplates | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobTemplates.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobTemplates.html) | none | Represents the permission to list the job templates. The iot:ListJobTemplates permission is checked every time a request is made to list the job templates. | | iot:ListManagedJobTemplates | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListManagedJobTemplates.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListManagedJobTemplates.html) | none | Represents the permission to list the managed job templates. The iot:ListManagedJobTemplates permission is checked every time a request is made to list the managed job templates. | | iot:UpdateJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html) | job | Represents the permission to update a job. The iot:UpdateJob permission is checked every time a request is made to update a job. | | iot:TagResource | [https://docs.aws.amazon.com/iot/latest/apireference/API_TagResource.html](https://docs.aws.amazon.com/iot/latest/apireference/API_TagResource.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Grants permission to tag a specific resource. | | iot:UntagResource | [https://docs.aws.amazon.com/iot/latest/apireference/API_UntagResource.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UntagResource.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Grants permission to untag a specific resource. | ### Basic IAM policy example The following example shows an IAM policy that allows the user permission to perform the following actions for your IoT thing and thing group. In the example, replace: + *region* with your AWS Region, such as `us-east-1`. + *account-id* with your AWS account number, such as `57EXAMPLE833`. + *thing-group-name* with the name of your IoT thing group for which you're targeting jobs, such as `FirmwareUpdateGroup`. + *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `MyIoTThing`. **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "iot:CreateJobTemplate", "iot:CreateJob" ], "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:thinggroup/thing-group-name" }, { "Action": [ "iot:DescribeJob", "iot:CancelJob", "iot:DeleteJob" ], "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:job/*" }, { "Action": [ "iot:DescribeJobExecution", "iot:CancelJobExecution", "iot:DeleteJobExecution" ], "Effect": "Allow", "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/thing-123", "arn:aws:iot:us-east-1:123456789012:job/*" ] } ] } ``` ### IAM policy example for IP based authorization You can restrict *principals* from making API calls to your control plane endpoint from specific IP addresses. To specify the IP addresses that can be allowed, in the Condition element of your IAM policy, use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip) global condition key. Using this condition key can also deny access to other AWS services from making these API calls on your behalf, such as AWS CloudFormation. To allow access to these services, use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice) global condition key with the aws:SourceIp key. This makes sure that the source IP address access restriction applies only to requests that are made directly by a principal. For more information, see [AWS: Denies access to AWS based on the source IP](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html). The following example shows how to allow only a specific IP address that can make API calls to the control plane endpoint. The `aws:ViaAWSService` key is set to `true`, which allows other services to make API calls on your behalf. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:CreateJobTemplate", "iot:CreateJob" ], "Resource": [ "*" ], "Condition": { "IpAddress": { "aws:SourceIp": "123.45.167.89" }, "Bool": { "aws:ViaAWSService": "false" } } }] } ``` ## IAM policies on the data plane IAM policies on the data plane use the `iotjobsdata:` prefix to authorize jobs API operations that users can perform. On the data plane, you can grant a user permission to use the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API by using the `iotjobsdata:DescribeJobExecution` policy action. **Warning** Using IAM policies on the data plane is not recommended when targeting AWS IoT Jobs for your devices. We recommend that you use IAM policies on the control plane for users to create and manage jobs. On the data plane, for authorizing devices to retrieve job executions and update the execution status, use [AWS IoT Core policies for HTTPS protocol](iot-data-plane-jobs.md#iot-jobs-data-http). ### Basic IAM policy example The API operations that must be authorized are usually performed by you typing CLI commands. The following shows an example of a user performing a `DescribeJobExecution` operation. In the example, replace: + *region* with your AWS Region, such as `us-east-1`. + *account-id* with your AWS account number, such as `57EXAMPLE833`. + *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `myRegisteredThing`. + `job-id` is the unique identifier for the job that's targeted using the API. ``` aws iot-jobs-data describe-job-execution \ --endpoint-url "https://account-id.jobs.iot.region.amazonaws.com" \ --job-id jobID --thing-name thing-name ``` The following shows a sample IAM policy that authorizes this action: **** ``` { "Version":"2012-10-17", "Statement": { "Action": [ "iotjobsdata:DescribeJobExecution" ], "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:thing/thing-123" } } ``` ### IAM policy examples for IP based authorization You can restrict *principals* from making API calls to your data plane endpoint from specific IP addresses. To specify the IP addresses that can be allowed, in the Condition element of your IAM policy, use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip) global condition key. Using this condition key can also deny access to other AWS services from making these API calls on your behalf, such as AWS CloudFormation. To allow access to these services, use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice) global condition key with the `aws:SourceIp` condition key. This makes sure that the IP address access restriction only applies to requests that are directly made by the principal. For more information, see [AWS: Denies access to AWS based on the source IP](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html). The following example shows how to allow only a specific IP address that can make API calls to the data plane endpoint. **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iotjobsdata:*" ], "Resource": [ "*" ], "Condition": { "IpAddress": { "aws:SourceIp": "123.45.167.89" }, "Bool": { "aws:ViaAWSService": "false" } } }] } ``` The following example shows how to restrict specific IP addresses or address ranges from making API calls to the data plane endpoint. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action": [ "iotjobsdata:*" ], "Condition": { "IpAddress": { "aws:SourceIp": [ "123.45.167.89", "192.0.2.0/24", "203.0.113.0/24" ] } }, "Resource": [ "*" ] } ] } ``` ### IAM policy example for both control plane and data plane If you perform an API operation on both the control plane and data plane, your control plane policy action must use the `iot:` prefix, and your data plane policy action must use the `iotjobsdata:` prefix. For example, the `DescribeJobExecution` API can be used in both the control plane and data plane. On the control plane, the [DescribeJobExecution](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) API is used to describe a job execution. On the data plane, the [ DescribeJobExecution](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API is used to get details of a job execution. The following IAM policy authorizes a user permission to use the `DescribeJobExecution` API on both the control plane and data plane. In the example, replace: + *region* with your AWS Region, such as `us-east-1`. + *account-id* with your AWS account number, such as `57EXAMPLE833`. + *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `MyIoTThing`. **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "iotjobsdata:DescribeJobExecution" ], "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:thing/thing-123" }, { "Action": [ "iot:DescribeJobExecution", "iot:CancelJobExecution", "iot:DeleteJobExecution" ], "Effect": "Allow", "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/thing-123", "arn:aws:iot:us-east-1:123456789012:job/*" ] } ] } ``` ## Authorize tagging of IoT resources For better control over jobs and job templates that you can create, modify, or use, you can attach tags to the jobs or job templates. Tags also help you discern ownership and assign and allocate costs by placing them in billing groups and attaching tags to them. When a user wants to tag their jobs or job templates that they created by using the AWS Management Console or the AWS CLI, your IAM policy must grant the user permissions to tag them. To grant permissions, your IAM policy must use the `iot:TagResource` action. **Note** If your IAM policy doesn't include the `iot:TagResource` action, then any [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) or [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) with a tag will return an `AccessDeniedException` error. When you want to tag your jobs or job templates that you created by using the AWS Management Console or the AWS CLI, your IAM policy must grant permission to tag them. To grant permissions, your IAM policy must use the `iot:TagResource` action. For general information about tagging your resources, see [Tagging your AWS IoT resources](tagging-iot.md). ### IAM policy example Refer to the following IAM policy examples granting tagging permissions: *Example 1* A user that runs the following command to create a job and tag it to a specific environment. In this example, replace: + *region* with your AWS Region, such as `us-east-1`. + *account-id* with your AWS account number, such as `57EXAMPLE833`. + *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `MyIoTThing`. ``` aws iot create-job --job-id test_job --targets "arn:aws:iot:region:account-id:thing/thingOne" --document-source "https://s3.amazonaws.com/amzn-s3-demo-bucket/job-document.json" --description "test job description" --tags Key=environment,Value=beta ``` For this example, you must use the following IAM policy: **** ``` { "Version":"2012-10-17", "Statement": { "Action": [ "iot:CreateJob", "iot:CreateJobTemplate", "iot:TagResource" ], "Effect": "Allow", "Resource": [ "arn:aws:iot:us-east-1:123456789012:job/*", "arn:aws:iot:us-east-1:123456789012:jobtemplate/*" ] } } ``` # Authorizing your devices to securely use AWS IoT Jobs on the data plane Authorizing devices to use jobs To authorize your devices to interact securely with AWS IoT Jobs on the data plane, you must use AWS IoT Core policies. AWS IoT Core policies for jobs are JSON documents containing policy statements. These policies also use *Effect*, *Action*, and *Resource* elements, and follow a similar convention to IAM policies. For more information about the elements, see [IAM JSON Policy Elements Reference](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_elements.html) in the *IAM user Guide*. The policies can be used with both MQTT and HTTPS protocols and must use TCP or TLS mutual authentication to authenticate the devices. The following shows how to use these policies across the different communication protocols. **Warning** We recommend that you don't use wildcard permissions, such as `"Action": ["iot:*"]` in your IAM policies or AWS IoT Core policies. Using wildcard permissions is not a recommended security best practice. For more information, see [AWS IoT policy overly permissive](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/audit-chk-iot-policy-permissive.html). ## AWS IoT Core policies for MQTT protocol AWS IoT Core policies for MQTT protocol grant you permissions to use the jobs device MQTT API actions. The MQTT API operations are used to work with MQTT topics that are reserved for jobs commands. For more information about these API operations, see [Jobs device MQTT API operations](jobs-mqtt-api.md). MQTT policies use policy actions such as `iot:Connect`, `iot:Publish`, `iot:Subscribe`, and `iot:Receieve` to work with the jobs topics. These policies allow you to connect to the message broker, subscribe to the jobs MQTT topics, and send and receive MQTT messages between your devices and the cloud. For more information about these actions, see [AWS IoT Core policy actions](iot-policy-actions.md). For information about topics for AWS IoT Jobs, see [Job topics](reserved-topics.md#reserved-topics-job). ### Basic MQTT policy example The following example shows how you can use `iot:Publish` and `iot:Subscribe` to publish and subscribe to jobs and job executions. In the example, replace: + *region* with your AWS Region, such as `us-east-1`. + *account-id* with your AWS account number, such as `57EXAMPLE833`. + *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `MyIoTThing`. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish", "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/events/job/*", "arn:aws:iot:us-east-1:123456789012:topic/$aws/events/jobExecution/*", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thing-123/jobs/*" ] } ] } ``` ## AWS IoT Core policies for HTTPS protocol AWS IoT Core policies on the data plane can also use the HTTPS protocol with the TLS authentication mechanism to authorize your devices. On the data plane, policies use the `iotjobsdata:` prefix to authorize jobs API operations that your devices can perform. For example, the `iotjobsdata:DescribeJobExecution` policy action grants the user permission to use the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API. **Note** The data plane policy actions must use the `iotjobsdata:` prefix. On the control plane, the actions must use the `iot:` prefix. For an example IAM policy when both control plane and data plane policy actions are used, see [IAM policy example for both control plane and data plane](iam-policy-users-jobs.md#iam-data-plane-example2). ### Policy actions The following table shows a list of AWS IoT Core policy actions and permissions for authorizing devices to use the API actions. For a list of API operations that you can perform in the data plane, see [Jobs device HTTP API](jobs-http-device-api.md). **Note** These job execution policy actions apply only to the HTTP TLS endpoint. If you use the MQTT endpoint, you must use the MQTT policy actions defined previously. **AWS IoT Core policy actions on data plane** | Policy action | API operation | Resource types | Description | | --- | --- | --- | --- | | iotjobsdata:DescribeJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iot-data-plane-jobs.html) | Represents the permission to retrieve a job execution. The iotjobsdata:DescribeJobExecution permission is checked every time a request is made to retrieve a job execution. | | iotjobsdata:GetPendingJobExecutions | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) | thing | Represents the permission to retrieve the list of jobs that are not in a terminal status for a thing. The iotjobsdata:GetPendingJobExecutions permission is checked every time a request is made to retrieve the list. | | iotjobsdata:StartNextPendingJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) | thing | Represents the permission to get and start the next pending job execution for a thing. That is, to update a job execution with status QUEUED to IN\$1PROGRESS. The iotjobsdata:StartNextPendingJobExecution permission is checked every time a request is made to start the next pending job execution. | | iotjobsdata:UpdateJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html) | thing | Represents the permission to update a job execution. The iotjobsdata:UpdateJobExecution permission is checked every time a request is made to update the state of a job execution. | ### Basic policy example The following shows an example of an AWS IoT Core policy that grants permission to perform the actions on the data plane API operations for any resource. You can scope your policy to a specific resource, such as an IoT thing. In your example, replace: + *region* with your AWS Region such as `us-east-1`. + *account-id* with your AWS account number, such as `57EXAMPLE833`. + *thing-name* with the name of the IoT thing, such as `MyIoTthing`. **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "iotjobsdata:GetPendingJobExecutions", "iotjobsdata:StartNextPendingJobExecution", "iotjobsdata:DescribeJobExecution", "iotjobsdata:UpdateJobExecution" ], "Effect": "Allow", "Resource": "arn:aws:iot:us-east-1:123456789012:thing/thing-123" } ] } ``` An example of when you must use these policies can be when your IoT devices use an AWS IoT Core policy to access one of these API operations, such as the following example of the `DescribeJobExecution` API: ``` GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument&namespaceId=namespaceId HTTP/1.1 ```