Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Controlling access to tags

To add, view, and delete tags, either in the Amazon KMS console or by using the API, principals need tagging permissions. You can provide these permissions in key policies. You can also provide them in IAM policies (including VPC endpoint policies), but only if the key policy allows it. The AWSKeyManagementServicePowerUser managed policy allows principals to tag, untag, and list tags on all KMS keys the account can access.

You can also limit these permissions by using Amazon global condition keys for tags. In Amazon KMS, these conditions can control access to tagging operations, such as TagResource and UntagResource.

For example policies and more information, see Controlling Access Based on Tag Keys in the IAM User Guide.

Permissions to create and manage tags work as follows.

Tag permissions in policies

You can provide tagging permissions in a key policy or IAM policy. For example, the following example key policy gives select users tagging permission on the KMS key. It gives all users who can assume the example Administrator or Developer roles permission to view tags.

{
  "Version": "2012-10-17",
  "Id": "example-key-policy",
  "Statement": [
    { 
      "Sid": "Enable IAM User Permissions",
      "Effect": "Allow",
      "Principal": {"AWS": "arn:aws:iam::111122223333:root"},
      "Action": "kms:*",
      "Resource": "*"
    },
    {
      "Sid": "Allow all tagging permissions",
      "Effect": "Allow",
      "Principal": {"AWS": [
        "arn:aws:iam::111122223333:user/LeadAdmin",
        "arn:aws:iam::111122223333:user/SupportLead"
      ]},
      "Action": [
          "kms:TagResource",
          "kms:ListResourceTags",
          "kms:UntagResource"
      ],
      "Resource": "*"
    },
    {
      "Sid": "Allow roles to view tags",
      "Effect": "Allow",
      "Principal": {"AWS": [
        "arn:aws:iam::111122223333:role/Administrator",
        "arn:aws:iam::111122223333:role/Developer"
      ]},
      "Action": "kms:ListResourceTags",
      "Resource": "*"
    }
  ]
}

To give principals tagging permission on multiple KMS keys, you can use an IAM policy. For this policy to be effective, the key policy for each KMS key must allow the account to use IAM policies to control access to the KMS key.

For example, the following IAM policy allows the principals to create KMS keys. It also allows them to create and manage tags on all KMS keys in the specified account. This combination allows the principals to use the Tags parameter of the CreateKey operation to add tags to a KMS key while they are creating it.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "IAMPolicyCreateKeys",
      "Effect": "Allow",
      "Action": "kms:CreateKey",
      "Resource": "*"
    },
    {
      "Sid": "IAMPolicyTags",
      "Effect": "Allow",
      "Action": [
        "kms:TagResource",
        "kms:UntagResource",
        "kms:ListResourceTags"
      ],
      "Resource": "arn:aws:kms:*:111122223333:key/*"
    }    
  ]
}

Limiting tag permissions

You can limit tagging permissions by using policy conditions. The following policy conditions can be applied to the kms:TagResource and kms:UntagResource permissions. For example, you can use the aws:RequestTag/tag-key condition to allow a principal to add only particular tags, or prevent a principal from adding tags with particular tag keys. Or, you can use the kms:KeyOrigin condition to prevent principals from tagging or untagging KMS keys with imported key material.

As a best practice when you use tags to control access to KMS keys, use the aws:RequestTag/tag-key or aws:TagKeys condition key to determine which tags (or tag keys) are allowed.

For example, the following IAM policy is similar to the previous one. However, this policy allows the principals to create tags (TagResource) and delete tags UntagResource only for tags with a Project tag key.

Because TagResource and UntagResource requests can include multiple tags, you must specify a ForAllValues or ForAnyValue set operator with the aws:TagKeys condition. The ForAnyValue operator requires that at least one of the tag keys in the request matches one of the tag keys in the policy. The ForAllValues operator requires that all of the tag keys in the request match one of the tag keys in the policy. The ForAllValues operator also returns true if there are no tags in the request, but TagResource and UntagResource fail when no tags are specified. For details about the set operators, see Use multiple keys and values in the IAM User Guide.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "IAMPolicyCreateKey",
      "Effect": "Allow",
      "Action": "kms:CreateKey",
      "Resource": "*"
    },
    {
      "Sid": "IAMPolicyViewAllTags",
      "Effect": "Allow",
      "Action": "kms:ListResourceTags",
      "Resource": "arn:aws:kms:*:111122223333:key/*"
    },
    {
      "Sid": "IAMPolicyManageTags",
      "Effect": "Allow",
      "Action": [
        "kms:TagResource",
        "kms:UntagResource"
      ],
      "Resource": "arn:aws:kms:*:111122223333:key/*",
      "Condition": {
          "ForAllValues:StringEquals": {"aws:TagKeys": "Project"}
      }
    }
  ]
}