AWS Identity and Access Management
User Guide

Tagging IAM Identities

You can use IAM tags to add custom attributes to an IAM user or role using a tag key–value pair. For example, to add location information to a user, you can add the tag key location and the tag value us_wa_seattle. Or you could use three separate location tag key–value pairs: loc-country = us, loc-state = wa, and loc-city = seattle. You can use tags to control an identity's access to resources or to control what tags can be attached to an identity. To learn more about using tags to control access, see Controlling Access Using IAM Tags.

Choose an AWS Tag Naming Convention

When you begin attaching tags to your IAM users and roles, choose your tag naming convention carefully and apply the same convention to all of your AWS tags. This is especially important if you use tags in policies to control access to AWS resources. If you already use tags in AWS, review your naming convention and adjust it accordingly. To learn more about creating a naming strategy, see AWS Tagging Strategies.

Note

If your account is a member of AWS Organizations, examine any service control policies that restrict access based on tags. Then make sure that those policies use key names with a similar naming convention as your accounts. If you use tags with one set of key names in the organization and a different set of key names in your accounts, permissions might not work as you intend.

Rules for Tagging IAM Identities

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

Naming Tags

Observe the following conventions when formulating a tag naming convention for IAM identities:

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

  • Tag key–value pairs 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=foo tag and you add the department=bar tag, it replaces the first tag. A second tag is not added.

  • You cannot create a tag key or value that begins with the text aws:. This tag prefix is reserved for AWS 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.

    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 include Engineering, including Engineering:QA. To learn more about using tags in policies, see Controlling Access Using IAM Tags.

Applying and Editing Tags

Observe the following conventions when attaching tags to IAM identities:

  • You can tag users or roles but not groups or policies.

  • You cannot use Tag Editor to tag IAM identities. Tag Editor does not support IAM tags. For information about using Tag Editor with other services, see Working with Tag Editor in the AWS Management Console User Guide.

  • To tag an IAM identity, you must have specific permissions. To tag or untag roles and users, you must also have permission to list tags. For more information, see Permissions Required for Tagging IAM Identities following.

  • There are limits to the number and size of tags you can attach to a user or role. For details, see Limitations on IAM Entities and Objects.

  • You can apply the same tag to multiple IAM identities. For example, if 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.

  • An IAM identity 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 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.

Permissions Required for Tagging IAM Identities

You must configure permissions to allow an IAM identity (such as a user, group, or role) to tag other identities. You can specify one or all of the following IAM tag actions in an IAM policy:

  • iam:ListRoleTags

  • iam:ListUserTags

  • iam:TagRole

  • iam:TagUser

  • iam:UntagRole

  • iam:UntagUser

To allow an IAM identity to add, list, or remove a tag for a specific user

Add the following statement to the permissions policy for the IAM identity that needs to manage tags. Use your account number and replace <username> with the name of the user that needs to be managed. To learn how to create a policy using this example JSON policy document, see Creating Policies on the JSON Tab.

{ "Effect": "Allow", "Action": [ "iam:ListUserTags", "iam:TagUser", "iam:UntagUser" ], "Resource": "arn:aws:iam:*:<account-number>:user/<username>" }

To allow an IAM user to self-manage tags

Add the following statement to the permissions policy for users to allow users to manage their own tags. To learn how to create a policy using this example JSON policy document, see Creating Policies on the JSON Tab.

{ "Effect": "Allow", "Action": [ "iam:ListUserTags", "iam:TagUser", "iam:UntagUser" ], "Resource": "arn:aws:iam:*:user/${aws:username}" }

To allow an IAM identity to add a tag to a specific user

Add the following statement to the permissions policy for the IAM identity that needs to add, but not remove, tags for a specific user.

Note

The iam:AddRoleTags and iam:AddUserTags actions require that you also include the iam:ListRoleTags and iam:ListUserTags actions.

To use this policy, replace <username> with the name of the user that needs to be managed. To learn how to create a policy using this example JSON policy document, see Creating Policies on the JSON Tab.

{ "Effect": "Allow", "Action": [ "iam:ListUserTags", "iam:TagUser" ], "Resource": "arn:aws:iam:*:<account-number>:user/<username>" }

To allow an IAM identity to add, list, or remove a tag for a specific role

Add the following statement to the permissions policy for the IAM identity that needs to manage tags, replacing <rolename> with the name of the role that needs to be managed. To learn how to create a policy using this example JSON policy document, see Creating Policies on the JSON Tab.

{ "Effect": "Allow", "Action": [ "iam:ListRoleTags", "iam:TagRole", "iam:UntagRole" ], "Resource": "arn:aws:iam:*:<account-number>:role/<rolename>" }

Alternatively, you can use an AWS managed policy such as IAMFullAccess to provide full access to IAM.

Managing Tags on IAM Identities (Console)

You can manage tags for IAM users or roles from the AWS Management Console.

To manage tags on users or roles (console)

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane of the console, choose Roles or Users and then choose the name of the identity that you want to edit.

  3. Choose the Tags tab and then complete one of the following actions:

    • Choose Add tags if the identity does not yet have tags.

    • Choose Edit tags to manage the existing set of tags.

  4. Add or remove tags to complete the set of tags. Then choose Save changes.

Managing Tags on IAM Identities (AWS CLI or AWS API)

You can list, attach, or remove tags for IAM users and roles. You can use the AWS CLI or the AWS API to manage tags for IAM users and roles.

To list the tags currently attached to an IAM role (AWS CLI or AWS API)

To list the tags currently attached to an IAM user (AWS CLI or AWS API)

To attach tags to an IAM role (AWS CLI or AWS API)

To attach tags to an IAM user (AWS CLI or AWS API)

To remove tags from an IAM role (AWS CLI or AWS API)

To remove tags from an IAM user (AWS CLI or AWS API)

For information about attaching tags to resources for other AWS services, see the documentation for those services.

For information about using tags to set more granular permissions with IAM permissions policies, see IAM Policy Elements: Variables and Tags.