Tagging IAM resources - Amazon Identity and Access Management
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.

Tagging IAM resources

A tag is a custom attribute label that you can assign to an Amazon resource. Each tag has two parts:

  • A tag key (for example, CostCenter, Environment, Project, or Purpose). Tag keys are case sensitive.

  • An optional field known as a tag value (for example, 111122223333, Production, or a team name). Omitting the tag value is the same as using an empty string. Like tag keys, tag values are case sensitive.

Together these are known as key-value pairs. For limits on the number of tags you can have on IAM resources, see IAM and Amazon STS quotas.

Tags help you identify and organize your Amazon resources. Many Amazon services support tagging, so you can assign the same tag to resources from different services to indicate that the resources are related. For example, you can assign the same tag to an IAM role that you assign to an Amazon S3 bucket. For more information about tagging strategies, see Tagging Amazon Resources in the Amazon General Reference Guide.

In addition to identifying, organizing, and tracking your IAM resources with tags, you can use tags in IAM policies to help control who can view and interact with your resources. To learn more about using tags to control access, see Controlling access to and for IAM users and roles using tags.

You can also use tags in Amazon STS to add custom attributes when you assume a role or federate a user. For more information, see Passing session tags in Amazon STS.

Choose an Amazon tag naming convention

When you begin attaching tags to your IAM resources, choose your tag naming convention carefully. Apply the same convention to all of your Amazon tags. This is especially important if you use tags in policies to control access to Amazon resources. If you already use tags in Amazon, review your naming convention and adjust it accordingly. To view tagging use cases and best practices, download the Tagging Best Practices whitepaper.

Rules for tagging in IAM and Amazon STS

A number of conventions govern the creation and application of tags in IAM and Amazon STS.

Naming tags

Observe the following conventions when formulating a tag naming convention for IAM resources, Amazon STS assume-role sessions, and Amazon STS federated user sessions:

Character requirements – Tag keys and values can include any combination of letters, numbers, spaces, and _ . : / = + - @ symbols.

Case sensitivity – Case sensitivity for tag keys differs depending on the type of IAM resource that is tagged. Tag key values for IAM users and roles are not case sensitive, but case is preserved. This means that you cannot have separate Department and department tag keys. If you have tagged a user with the Department=finance tag and you add the department=hr tag, it replaces the first tag. A second tag is not added.

For other IAM resource types, tag key values are case sensitive. That means you can have separate Costcenter and costcenter tag keys. For example, if you have tagged a customer managed policy with the Costcenter = 1234 tag and you add the costcenter = 5678 tag, the policy will have both the Costcenter and costcenter tag keys.

As a best practice, we recommend that you avoid using similar tags with inconsistent case treatment. We recommend that you decide on strategy for capitalizing tags, and consistently implement that strategy across all resource types. To learn more about best practices for tagging, see Tagging Amazon Resourcesin the Amazon General Reference.

The following lists show the differences in case sensitivity for tag keys that are attached to IAM resources.

Tag key values are not case sensitive:

  • IAM roles

  • IAM users

Tag key values are case sensitive:

  • Customer managed policies

  • Instance profiles

  • OpenID Connect identity providers

  • SAML identity providers

  • Server certificates

  • Virtual MFA devices

Additionally, the following rules apply:

  • You cannot create a tag key or value that begins with the text aws:. This tag prefix is reserved for Amazon internal use.

  • You can create a tag with an empty value such as phoneNumber = . You cannot create an empty tag key.

  • You cannot specify multiple values in a single tag, but you can create a custom multivalue structure in the single value. For example, assume that the user Zhang works on the engineering team and the QA team. If you attach the team = Engineering tag and then attach the team = QA tag, you change the value of the tag from Engineering to QA. Instead, you can include multiple values in a single tag with a custom separator. In this example, you could attach the team = Engineering:QA tag to Zhang.


    To control access to engineers in this example using the team tag, you must create a policy that allows for every configuration that might include Engineering, including Engineering:QA. To learn more about using tags in policies, see Controlling access to and for IAM users and roles using tags.

Applying and editing tags

Observe the following conventions when attaching tags to IAM resources:

  • You can tag most IAM resources, but not groups, assumed roles, access reports, hardware-based, or SMS MFA devices.

  • You cannot use Tag Editor to tag IAM resources. Tag Editor does not support IAM tags. For information about using Tag Editor with other services, see Working with Tag Editor in the Amazon Resource Groups User Guide.

  • To tag an IAM resource, you must have specific permissions. To tag or untag resources, you must also have permission to list tags. For more information, see the list of topics for each IAM resource at the end of this page.

  • The number and size of IAM resources in an Amazon account are limited. For more information, see IAM and Amazon STS quotas.

  • You can apply the same tag to multiple IAM resources. For example, suppose you have a department named AWS_Development with 12 members. You can have 12 users and a role with the tag key of department and a value of awsDevelopment (department = awsDevelopment). You can also use the same tag on resources in other services that support tagging.

  • IAM entities (users or roles) cannot have multiple instances of the same tag key. For example, if you have a user with the tag key-value pair costCenter = 1234, you can then attach the tag key-value pair costCenter = 5678. IAM updates the value of the costCenter tag to 5678.

  • To edit a tag that is attached to an IAM entity (user or role), attach a tag with a new value to overwrite the existing tag. For example, assume that you have a user with the tag key-value pair department = Engineering. If you need to move the user to the QA department, then you can attach the department = QA tag key-value pair to the user. This results in the Engineering value of the department tag key being replaced with the QA value.