Authorizing users and cloud services to use AWS IoT Jobs - AWS IoT Core

Authorizing users and cloud services to use AWS IoT Jobs

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.

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 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.

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 CreateJob API.

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. For more information about AWS IoT actions, see Actions defined by AWS IoT.

IAM policy actions on control plane
Policy action API operation Resource types Description
iot:AssociateTargetsWithJob AssociateTargetsWithJob
  • job

  • thing

  • thinggroup

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 CancelJob 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 CancelJobExecution
  • job

  • thing

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 CreateJob
  • job

  • thing

  • thinggroup

  • jobtemplate

  • package

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 CreateJobTemplate
  • job

  • jobtemplate

  • package

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 DeleteJob 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 DeleteJobTemplate 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 DeleteJobTemplate
  • job

  • thing

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 DescribeJob 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 DescribeJobExecution
  • job

  • thing

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 DescribeJobTemplate 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 DescribeManagedJobTemplate 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 GetJobDocument 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 ListJobExecutionsForJob 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 ListJobExecutionsForThing 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 ListJobs 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 ListJobTemplates 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 ListManagedJobTemplates 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 UpdateJob 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 TagResource
  • job

  • jobtemplate

  • thing

Grants permission to tag a specific resource.
iot:UntagResource UntagResource
  • job

  • jobtemplate

  • thing

Grants permission to untag a specific resource.

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:region:account-id:thinggroup/thing-group-name" }, { "Action": [ "iot:DescribeJob", "iot:CancelJob", "iot:DeleteJob", ], "Effect": "Allow", "Resource": "arn:aws:iot:region:account-id:job/*" }, { "Action": [ "iot:DescribeJobExecution", "iot:CancelJobExecution", "iot:DeleteJobExecution", ], "Effect": "Allow", "Resource": [ "arn:aws:iot:region:account-id:thing/thing-name" "arn:aws:iot:region:account-id:job/*" ] } ] }

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 aws: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 aws: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.

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": "true"} } ], }

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 DescribeJobExecution 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.

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:region:account-id:thing/thing-name", } }

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 aws: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 aws: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.

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": ["*"], } ], }

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 API is used to describe a job execution. On the data plane, the DescribeJobExecution 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:region:account-id:thing/thing-name" }, { "Action": [ "iot:DescribeJobExecution", "iot:CancelJobExecution", "iot:DeleteJobExecution", ], "Effect": "Allow", "Resource": [ "arn:aws:iot:region:account-id:thing/thing-name" "arn:aws:iot:region:account-id: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 CreateJob or CreateJobTemplate 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.

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:aws-region:account-id:job/*", "arn:aws:iot:aws-region:account-id:jobtemplate/*" ] } }