# Controlling access and labeling jobs using tags
Using tags

You can label and control access to your S3 Batch Operations jobs by adding *tags*. Tags can be used to identify who is responsible for a Batch Operations job. The presence of job tags can grant or limit a user's ability to cancel a job, activate a job in the confirmation state, or change a job's priority level. You can create jobs with tags attached to them, and you can add tags to jobs after they're created. Each tag is a key-value pair that can be included when you create the job or updated later.

**Warning**  
Make sure that your job tags don't contain any confidential information or personal data.

Consider the following tagging example: Suppose that you want your Finance department to create a Batch Operations job. You could write an AWS Identity and Access Management (IAM) policy that allows a user to invoke `CreateJob`, provided that the job is created with the `Department` tag assigned the value `Finance`. Furthermore, you could attach that policy to all users who are members of the Finance department.

Continuing with this example, you could write a policy that allows a user to update the priority of any job that has the desired tags, or cancel any job that has those tags. For more information, see [Controlling permissions for Batch Operations using job tags](batch-ops-job-tags-examples.md).

You can add tags to new S3 Batch Operations jobs when you create them, or you can add them to existing jobs. 

Note the following tag restrictions:
+ You can associate up to 50 tags with a job as long as they have unique tag keys.
+ A tag key can be up to 128 Unicode characters in length, and tag values can be up to 256 Unicode characters in length.
+ The key and values are case sensitive.

For more information about tag restrictions, see [User-Defined Tag Restrictions](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/allocation-tag-restrictions.html) in the *AWS Billing and Cost Management User Guide*.

## API operations related to S3 Batch Operations job tagging


Amazon S3 supports the following API operations that are specific to S3 Batch Operations job tagging:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetJobTagging.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetJobTagging.html) – Returns the tag set associated with a Batch Operations job. 
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutJobTagging.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutJobTagging.html) – Replaces the tag set associated with a job. There are two distinct scenarios for S3 Batch Operations job tag management using this API action:
  + Job has no tags – You can add a set of tags to a job (the job has no prior tags).
  + Job has a set of existing tags – To modify the existing tag set, you can either replace the existing tag set entirely, or make changes within the existing tag set by retrieving the existing tag set using [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetJobTagging.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetJobTagging.html), modify that tag set, and use this API action to replace the tag set with the one you have modified.
**Note**  
If you send this request with an empty tag set, S3 Batch Operations deletes the existing tag set on the object. If you use this method, you are charged for a Tier 1 Request (`PUT`). For more information, see [Amazon S3 pricing](https://aws.amazon.com/s3/pricing).  
To delete existing tags for your Batch Operations job, the `DeleteJobTagging` action is preferred because it achieves the same result without incurring charges.
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteJobTagging.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_DeleteJobTagging.html) – Deletes the tag set associated with a Batch Operations job. 

# Creating a Batch Operations job with job tags used for labeling
Creating a job

You can label and control access to your Amazon S3 Batch Operations jobs by adding *tags*. Tags can be used to identify who is responsible for a Batch Operations job. You can create jobs with tags attached to them, and you can add tags to jobs after they are created. For more information, see [Controlling access and labeling jobs using tags](batch-ops-job-tags.md).

## Using the AWS CLI


The following AWS CLI example creates an S3 Batch Operations `S3PutObjectCopy` job using job tags as labels for the job. 

1. Select the action or `OPERATION` that you want the Batch Operations job to perform, and choose your `TargetResource`.

   ```
   read -d '' OPERATION <<EOF
   {
     "S3PutObjectCopy": {
       "TargetResource": "arn:aws:s3:::amzn-s3-demo-destination-bucket"
     }
   }
   EOF
   ```

1. Identify the job `TAGS` that you want for the job. In this case, you apply two tags, `department` and `FiscalYear`, with the values `Marketing` and `2020` respectively.

   ```
   read -d '' TAGS <<EOF
   [
     {
       "Key": "department",
       "Value": "Marketing"
     },
     {
       "Key": "FiscalYear",
       "Value": "2020"
     }
   ]
   EOF
   ```

1. Specify the `MANIFEST` for the Batch Operations job.

   ```
   read -d '' MANIFEST <<EOF
   {
     "Spec": {
       "Format": "EXAMPLE_S3BatchOperations_CSV_20180820",
       "Fields": [
         "Bucket",
         "Key"
       ]
     },
     "Location": {
       "ObjectArn": "arn:aws:s3:::amzn-s3-demo-manifest-bucket/example_manifest.csv",
       "ETag": "example-5dc7a8bfb90808fc5d546218"
     }
   }
   EOF
   ```

1. Configure the `REPORT` for the Batch Operations job.

   ```
   read -d '' REPORT <<EOF
   {
     "Bucket": "arn:aws:s3:::amzn-s3-demo-completion-report-bucket",
     "Format": "Example_Report_CSV_20180820",
     "Enabled": true,
     "Prefix": "reports/copy-with-replace-metadata",
     "ReportScope": "AllTasks"
   }
   EOF
   ```

1. Run the`create-job` action to create your Batch Operations job with inputs set in the preceding steps.

   ```
   aws \
       s3control create-job \
       --account-id 123456789012 \
       --manifest "${MANIFEST//$'\n'}" \
       --operation "${OPERATION//$'\n'/}" \
       --report "${REPORT//$'\n'}" \
       --priority 10 \
       --role-arn arn:aws:iam::123456789012:role/batch-operations-role \
       --tags "${TAGS//$'\n'/}" \
       --client-request-token "$(uuidgen)" \
       --region us-west-2 \
       --description "Copy with Replace Metadata";
   ```

## Using the AWS SDK for Java


To create an S3 Batch Operations job with tags using the AWS SDK for Java, you can use the S3Control client to configure job parameters including manifest location, job operations, reporting settings, and tags for organization and tracking purposes.

For examples of how to create S3 Batch Operations jobs with tags using the AWS SDK for Java, see [Create a batch job to copy objects](https://docs.aws.amazon.com/AmazonS3/latest/API/s3-control_example_s3-control_CreateJob_section.html) in the *Amazon S3 API Reference*.

# Deleting the tags from an S3 Batch Operations job
Deleting tags

You can use these examples to delete the tags from an Amazon S3 Batch Operations job.

## Using the AWS CLI
Delete the tags from a Batch Operations job

The following example deletes the tags from a Batch Operations job using the AWS CLI.

```
aws \
    s3control delete-job-tagging \
    --account-id 123456789012 \
    --job-id Example-e25a-4ed2-8bee-7f8ed7fc2f1c \
    --region us-east-1
```

## Delete the job tags of a Batch Operations job


To delete the tags of an S3 Batch Operations job using the AWS SDK for Java, you can use the S3Control client with the job ID to remove all tags associated with the batch operations job.

For examples of how to delete job tags with the AWS SDK for Java, see [Delete tags from a batch job](https://docs.aws.amazon.com/AmazonS3/latest/API/s3-control_example_s3-control_DeleteJobTagging_section.html) in the *Amazon S3 API Reference*.

# Adding job tags to an existing Batch Operations job
Putting job tags

You can use the [https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutJobTagging.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_PutJobTagging.html) API operation to add job tags to your existing Amazon S3 Batch Operations jobs. For more information, see the following examples.

## Using the AWS CLI


The following is an example of using `s3control put-job-tagging` to add job tags to your S3 Batch Operations job by using the AWS CLI. To use the examples, replace the *`user input placeholders`* with your own information.

**Note**  
If you send this request with an empty tag set, Batch Operations deletes the existing tag set on the object. However, if you use this approach, you are charged for a Tier 1 Request (`PUT`). For more information, see [Amazon S3 pricing](https://aws.amazon.com/s3/pricing).  
Instead, to delete existing tags for your Batch Operations job, we recommend using the `DeleteJobTagging` operation because it achieves the same result without incurring charges.

1. Identify the job `TAGS` that you want for the job. In this case, you apply two tags, `department` and `FiscalYear`, with the values `Marketing` and `2020` respectively.

   ```
   read -d '' TAGS <<EOF
   [
     {
       "Key": "department",
       "Value": "Marketing"
     },
     {
       "Key": "FiscalYear",
       "Value": "2020"
     }
   ]
   EOF
   ```

1. Run the following `put-job-tagging` command with the required parameters:

   ```
   aws \
       s3control put-job-tagging \
       --account-id 123456789012 \
       --tags "${TAGS//$'\n'/}" \
       --job-id Example-e25a-4ed2-8bee-7f8ed7fc2f1c \
       --region us-east-1
   ```

## Using the AWS SDK for Java


To put tags on an S3 Batch Operations job using the AWS SDK for Java, you can use the S3Control client to add or update tags with key-value pairs for organization and tracking purposes.

For examples of how to put job tags with the AWS SDK for Java, see [Add tags to a batch job](https://docs.aws.amazon.com/AmazonS3/latest/API/s3-control_example_s3-control_PutJobTagging_section.html) in the *Amazon S3 API Reference*.

# Getting the tags of a S3 Batch Operations job
Getting job tags

To retrieve the tags of an Amazon S3 Batch Operations job, you can use the `GetJobTagging` API operation. For more information, see the following examples.

## Using the AWS CLI


The following example gets the tags of a Batch Operations job using the AWS CLI. To use this example, replace the *`user input placeholders`* with your own information.

```
aws \
    s3control get-job-tagging \
    --account-id 123456789012 \
    --job-id Example-e25a-4ed2-8bee-7f8ed7fc2f1c \
    --region us-east-1
```

## Using the AWS SDK for Java


To get the tags of an S3 Batch Operations job using the AWS SDK for Java, you can use the S3Control client with the job ID to retrieve all tags associated with the batch operations job and return them as a list.

For examples of how to get job tags with the AWS SDK for Java, see [Get tags from a batch job](https://docs.aws.amazon.com/AmazonS3/latest/API/s3-control_example_s3-control_GetJobTagging_section.html) in the *Amazon S3 API Reference*.

# Controlling permissions for Batch Operations using job tags
Controlling permissions

To help you manage your Amazon S3 Batch Operations jobs, you can add *job tags*. With job tags, you can control access to your Batch Operations jobs and enforce that tags be applied when any job is created. 

You can apply up to 50 job tags to each Batch Operations job. By using tags, you can set granular policies to restrict the set of users that can edit the job. Job tags can grant or limit a user’s ability to cancel a job, activate a job in the confirmation state, or change a job’s priority level. In addition, you can enforce that tags be applied to all new jobs, and specify the allowed key-value pairs for the tags. You can express all of these conditions by using [AWS Identity and Access Management (IAM) policy language](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_iam-tags.html). For more information, see [Actions, resources, and condition keys for Amazon S3](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html) in the *Service Authorization Reference*.

For more information about the permissions to S3 API operations by S3 resource types, see [Required permissions for Amazon S3 API operations](using-with-s3-policy-actions.md).

The following example shows how you can use S3 Batch Operations job tags to grant users permission to create and edit only the jobs that are run within a specific department (for example, the Finance or Compliance department). You can also assign jobs based on the stage of development that they are related to, such as QA or Production.

In this example, you use S3 Batch Operations job tags in IAM policies to grant users permission to create and edit only the jobs that are being run within their department. You assign jobs based on the stage of development that they are related to, such as QA or Production. 

The following examples use the following departments, with each department using Batch Operations in different ways:
+ Finance
+ Compliance
+ Business Intelligence
+ Engineering

**Topics**
+ [

## Controlling access by assigning tags to users and resources
](#job-tags-examples-attaching-tags)
+ [

## Tagging Batch Operations jobs by stage and enforcing limits on job priority
](#tagging-jobs-by-stage-and-enforcing-limits-on-job-priority)

## Controlling access by assigning tags to users and resources


In this scenario, the administrators are using [attribute-based access control (ABAC)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html). ABAC is an IAM authorization strategy that defines permissions by attaching tags to both users and AWS resources.

Users and jobs are assigned one of the following department tags:

**Key : Value**
+ `department : Finance`
+ `department : Compliance`
+ `department : BusinessIntelligence`
+ `department : Engineering`
**Note**  
Job tag keys and values are case sensitive.

Using the ABAC access control strategy, you grant a user in the Finance department permission to create and manage S3 Batch Operations jobs within their department by associating the tag `department=Finance` with their user.

Furthermore, you can attach a managed policy to the IAM user that allows any user in their company to create or modify S3 Batch Operations jobs within their respective departments. 

The policy in this example includes three policy statements:
+ The first statement in the policy allows the user to create a Batch Operations job provided that the job creation request includes a job tag that matches their respective department. This is expressed using the `"${aws:PrincipalTag/department}"` syntax, which is replaced by the user’s department tag at policy evaluation time. The condition is satisfied when the value provided for the department tag in the request `("aws:RequestTag/department")` matches the user’s department. 
+ The second statement in the policy allows users to change the priority of jobs or update a job’s status provided that the job the user is updating matches the user’s department. 
+ The third statement allows a user to update a Batch Operations job’s tags at any time via a `PutJobTagging` request as long as (1) their department tag is preserved and (2) the job they’re updating is within their department. 

------
#### [ JSON ]

****  

```
{
      "Version":"2012-10-17",		 	 	 
      "Statement": [
            {
                  "Effect": "Allow",
                  "Action": "s3:CreateJob",
                  "Resource": "*",
                  "Condition": {
                        "StringEquals": {
                              "aws:RequestTag/department": "${aws:PrincipalTag/department}"        
                }      
            }    
        },
            {
                  "Effect": "Allow",
                  "Action": [
                        "s3:UpdateJobPriority",
                        "s3:UpdateJobStatus"      
            ],
                  "Resource": "*",
                  "Condition": {
                        "StringEquals": {
                              "aws:ResourceTag/department": "${aws:PrincipalTag/department}"        
                }      
            }    
        },
            {
                  "Effect": "Allow",
                  "Action": "s3:PutJobTagging",
                  "Resource": "*",
                  "Condition": {
                        "StringEquals": {
                              "aws:RequestTag/department": "${aws:PrincipalTag/department}",
                              "aws:ResourceTag/department": "${aws:PrincipalTag/department}"        
                }      
            }    
        }  
    ]
}
```

------

## Tagging Batch Operations jobs by stage and enforcing limits on job priority


All S3 Batch Operations jobs have a numeric priority, which Amazon S3 uses to decide in what order to run the jobs. For this example, you restrict the maximum priority that most users can assign to jobs, with higher priority ranges reserved for a limited set of privileged users, as follows:
+ QA stage priority range (low): 1-100
+ Production stage priority range (high): 1-300

To do this, introduce a new tag set representing the stage of the job:

**Key : Value**
+ `stage : QA`
+ `stage : Production`

### Creating and updating low-priority jobs within a department


This policy introduces two new restrictions on S3 Batch Operations job creation and update, in addition to the department-based restriction:
+ It allows users to create or update jobs in their department with a new condition that requires the job to include the tag `stage=QA`.
+ It allows users to create or update a job’s priority up to a new maximum priority of 100.

```
{
        "Version": "2012-10-17",		 	 	 
        "Statement": [
        {
        "Effect": "Allow",
        "Action": "s3:CreateJob",
        "Resource": "*",
        "Condition": {
            "StringEquals": {
                "aws:RequestTag/department": "${aws:PrincipalTag/department}",
                "aws:RequestTag/stage": "QA"
            },
            "NumericLessThanEquals": {
                "s3:RequestJobPriority": 100
            }
        }
    },
    {
        "Effect": "Allow",
        "Action": [
            "s3:UpdateJobStatus"
        ],
        "Resource": "*",
        "Condition": {
            "StringEquals": {
                "aws:ResourceTag/department": "${aws:PrincipalTag/department}"
            }
        }
    },
    {
        "Effect": "Allow",
        "Action": "s3:UpdateJobPriority",
        "Resource": "*",
        "Condition": {
            "StringEquals": {
                "aws:ResourceTag/department": "${aws:PrincipalTag/department}",
                "aws:ResourceTag/stage": "QA"
            },
            "NumericLessThanEquals": {
                "s3:RequestJobPriority": 100
            }
        }
    },
    {
        "Effect": "Allow",
        "Action": "s3:PutJobTagging",
        "Resource": "*",
        "Condition": {
            "StringEquals": {
                "aws:RequestTag/department" : "${aws:PrincipalTag/department}",
                "aws:ResourceTag/department": "${aws:PrincipalTag/department}",
                "aws:RequestTag/stage": "QA",
                "aws:ResourceTag/stage": "QA"
            }
        }
    },
    {
        "Effect": "Allow",
        "Action": "s3:GetJobTagging",
        "Resource": "*"
    }
    ]
}
```

### Creating and updating high-priority jobs within a department


A small number of users might require the ability to create high priority jobs in either QA or Production. To support this need, you create a managed policy that’s adapted from the low-priority policy in the previous section. 

This policy does the following: 
+ Allows users to create or update jobs in their department with either the tag `stage=QA` or `stage=Production`.
+ Allows users to create or update a job’s priority up to a maximum of 300.

------
#### [ JSON ]

****  

```
{
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
                "Effect": "Allow",
                "Action": "s3:CreateJob",
                "Resource": "*",
                "Condition": {
                      "ForAnyValue:StringEquals": {
                            "aws:RequestTag/stage": [
                                  "QA",
                                  "Production"        
                    ]      
                },
                      "StringEquals": {
                            "aws:RequestTag/department": "${aws:PrincipalTag/department}"      
                },
                      "NumericLessThanEquals": {
                            "s3:RequestJobPriority": 300      
                }    
            }  
        },
          {
                "Effect": "Allow",
                "Action": [
                      "s3:UpdateJobStatus"    
            ],
                "Resource": "*",
                "Condition": {
                      "StringEquals": {
                            "aws:ResourceTag/department": "${aws:PrincipalTag/department}"      
                }    
            }  
        },
          {
                "Effect": "Allow",
                "Action": "s3:UpdateJobPriority",
                "Resource": "*",
                "Condition": {
                      "ForAnyValue:StringEquals": {
                            "aws:ResourceTag/stage": [
                                  "QA",
                                  "Production"        
                    ]      
                },
                      "StringEquals": {
                            "aws:ResourceTag/department": "${aws:PrincipalTag/department}"      
                },
                      "NumericLessThanEquals": {
                            "s3:RequestJobPriority": 300      
                }    
            }  
        },
          {
                "Effect": "Allow",
                "Action": "s3:PutJobTagging",
                "Resource": "*",
                "Condition": {
                      "StringEquals": {
                            "aws:RequestTag/department": "${aws:PrincipalTag/department}",
                            "aws:ResourceTag/department": "${aws:PrincipalTag/department}"      
                },
                      "ForAnyValue:StringEquals": {
                            "aws:RequestTag/stage": [
                                  "QA",
                                  "Production"        
                    ],
                            "aws:ResourceTag/stage": [
                                  "QA",
                                  "Production"        
                    ]      
                }    
            }  
        }  
    ]
}
```

------