How do I use the PrincipalTag, ResourceTag, RequestTag, and TagKeys condition keys to create an IAM policy for tag-based restriction?

Resolution

The following IAM example policies use condition keys to create tag-based restriction.

Note: To determine the API actions that you can complete, it's a best practice to review API documentation for the service that you're using.

PrincipalTag condition key

Use the aws:PrincipalTag/tag-key condition key to match the tag that's attached to the principal who's making the request with the tag in the IAM policy.

The following example IAM policy provides restriction for an Amazon Simple Storage Service (Amazon S3) bucket. The Amazon S3 PutObject action denies bucket access to all users except those with the title Product-Manager:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DenyAllButProductManagers",
      "Effect": "Deny",
      "Principal": {
        "AWS": "*"
      },
      "Action": [
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::productionbucket/*"
      ],
      "Condition": {
        "StringNotEquals": {
          "aws:PrincipalTag/job-title": "Product-Manager"
        }
      }
    }
  ]
}

ResourceTag condition key

Use the aws:ResourceTag/tag-key condition key to compare the tag key-value pair that's specified in the IAM policy with the key-value pair that's attached to the AWS resource. For more information, see Controlling access to AWS resources.

You can use this condition key with the global aws:ResourceTag version and AWS services, such as ec2:ResourceTag. For more information, see Actions, resources, and condition keys for AWS services.

The following example IAM policy allows users to start, stop, and terminate instances that are in the test environment:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowOnlyForTestEnvironment",
      "Effect": "Allow",
      "Action": [
        "ec2:TerminateInstances",
        "ec2:StartInstances",
        "ec2:StopInstances"
      ],
      "Resource": "arn:aws:ec2:*:*:instance/*",
      "Condition": {
        "StringLike": {
          "ec2:ResourceTag/Env": "test"
        }
      }
    }
  ]
}

RequestTag condition key

Use the aws:RequestTag/tag-key condition key to compare the key-value pair that's passed in the user request with the tag pair that's specified in the IAM policy. You can use this condition key for actions that create a resource or resource tag and that check the tag's value.

The following example policy forces users to create a specific Env tag when the users create an Amazon Elastic Block Store (Amazon EBS) volume. Env must have the Dev, Prod or QA values:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowCreateVolumeWithEnvTag",
      "Effect": "Allow",
      "Action": "ec2:CreateVolume",
      "Resource": "arn:aws:ec2:*:*:volume/*",
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/Env": [
            "Dev",
            "Prod",
            "QA"
          ]
        }
      }
    }
  ]
}

TagKeys condition key

Use the aws:TagKeys condition key to compare the tag keys in a request with the keys that are specified in the IAM policy. This condition key validates the tag keys that are attached to a resource.

Because you can define multiple tag key-value pairs in a request, the request can have multiple values. To compare these values, use the ForAllValues or ForAnyValue set operators.

The following example policy restricts the tags that are created on an AWS resource. The Env and CostCenter tags are the only tag keys that users can create with a new Amazon EBS volume. The use of the ForAllValues set operator with aws:TagKeys allows users to attach only the required tags on the AWS resource. This policy doesn't require users to provide these tag keys in the resource creation request. Instead, the policy doesn't allow users to create tags with other key-value pairs:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": "ec2:CreateVolume",
      "Resource": "arn:aws:ec2:*:*:volume/*",
      "Condition": {
        "ForAllValues:StringEquals": {
          "aws:TagKeys": [
            "Env",
            "CostCenter"
          ]
        }
      }
    }
  ]
}

Related information

IAM tutorial: Define permissions to access AWS resources based on tags