Tags for Amazon Identity and Access Management 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
, orPurpose
). -
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.
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.
Note
For details about case sensitivity for tag keys and tag key values, see Case sensitivity.
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 the Tagging Amazon resources User 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 Pass session tags in Amazon STS.
Topics
- Choose an Amazon tag naming convention
- Rules for tagging in IAM and Amazon STS
- Tag IAM users
- Tag IAM roles
- Tag customer managed policies
- Tag OpenID Connect (OIDC) identity providers
- Tag IAM SAML identity providers
- Tag instance profiles for Amazon EC2 roles
- Tag server certificates
- Tag virtual MFA devices
- Pass 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.
Note
If your account is a member of Amazon Organizations, see Tag policies in the Organizations user guide to learn more about using tags in Organizations.
Best practices for tag naming
These are some best practices and naming conventions for tags.
Ensure that tag names are used consistently. For example, the tags
CostCenter
and costcenter
are different, so one might be
configured as a cost allocation tag for financial analysis and reporting and the other one
might not be. Similarly, the Name
tag appears in the Amazon Console for many
resources, but the name
tag does not. For details about case sensitivity for
tag keys and tag key values, see Case sensitivity.
A number of tags are predefined by Amazon or created automatically by various Amazon services. Many Amazon-defined tags names use all lowercase, with hyphens separating words in the name, and prefixes to identify the source service for the tag. For example:
-
aws:ec2spot:fleet-request-id
identifies the Amazon EC2 Spot Instance Request that launched the instance. -
aws:cloudformation:stack-name
identifies the Amazon CloudFormation stack that created the resource. -
elasticbeanstalk:environment-name
identifies the application that created the resource.
Consider naming your tags using all lowercase, with hyphens separating words, and a prefix identifying the organization name or abbreviated name. For example, for a fictitious company named AnyCompany, you might define tags such as:
-
anycompany:cost-center
to identify the internal Cost Center code -
anycompany:environment-type
to identify whether the environment is development, test, or production -
anycompany:application-id
to identify the application the resource was created for
The prefix ensures that tags are clearly identified as having been defined by your
organization and not by Amazon or a third-party tool that you may be using. Using all
lowercase with hyphens for separators avoids confusion about how to capitalize a tag name.
For example, anycompany:project-id
is simpler to remember than
ANYCOMPANY:ProjectID
, anycompany:projectID
, or
Anycompany:ProjectId
.
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 a strategy for capitalizing tags, and consistently implement that strategy across all resource types. To learn more about best practices for tagging, see Tagging Amazon Resources in the Amazon Web Services 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 theteam = QA
tag, you change the value of the tag fromEngineering
toQA
. Instead, you can include multiple values in a single tag with a custom separator. In this example, you could attach theteam = Engineering:QA
tag to Zhang.Note
To control access to engineers in this example using the
team
tag, you must create a policy that allows for every configuration that might includeEngineering
, includingEngineering: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, or hardware-based 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 ofdepartment
and a value ofawsDevelopment
(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 paircostCenter = 5678
. IAM updates the value of thecostCenter
tag to5678
. -
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 thedepartment = QA
tag key-value pair to the user. This results in theEngineering
value of thedepartment
tag key being replaced with theQA
value.