Add Tags to Manage Your AWS IAM Users and Roles

We made it easier for you to manage your AWS Identity and Access Management (IAM) resources by enabling you to add tags to your IAM users and roles (also known as IAM principals). Tags enable you to add customizable key-value pairs to resources, and many AWS services support tagging of AWS resources. Now, you can use tags to add custom attributes such as project name and cost center to your IAM principals. Additionally, tags on IAM principals simplify permissions management. For example, you can author a policy that allows a user to assume the roles for a specific project by using a tag. As you add roles with that tag, users gain permissions to assume those roles automatically. In a subsequent post, I will review how you can use tags on IAM principals to control access to your AWS resources.

In this blog post, I introduce the new APIs and conditions you can use to tag IAM principals, show three example policies that address three tagging use cases, and I show how to add tags to IAM principals by using the AWS Console and CLI. The first example policy grants permissions to tag principals. The second example policy requires specific tags for new users, and the third grants permissions to manage specific tags on principals.

Note: You must have the latest version of the AWS CLI to tag your IAM principals. Follow these instructions to update the AWS CLI.

New IAM APIs for tagging IAM principals

The following table lists the new IAM APIs that you must grant access to using an IAM policy so that you can view and modify tags on IAM principals. These APIs support resource-level permissions so that you can grant permissions to tag only specific principals.

In addition to the new APIs, tagging parameters now are available for the existing iam:CreateUser and iam:CreateRole APIs to enable you to tag your users and roles when they are created. I show how you can add tags to a new user later in this blog post.

Now that you know the APIs you can use to tag IAM principals, let’s review an example of how to grant permissions to tag by using an IAM policy.

Example policy 1: Grant permissions to tag specific users and all roles

To get started using tags, you must first ensure you grant permissions to do so. The following policy grants permissions to tag one IAM user and all roles.

Note: Replace <ACCOUNT-ID> with your 12-digit account number.

        
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "iam:ListUsers",
                "iam:ListRoles"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:ListUserTags",
                "iam:ListRoleTags",
                "iam:TagUser",
                "iam:TagRole",
                "iam:UntagUser",
                "iam:UntagRole"
            ],
            "Resource": [
                "arn:aws:iam:: <ACCOUNT-ID>:user/John",
                "arn:aws:iam:: <ACCOUNT-ID>:role/*"
            ]
        }
    ]
}

This policy lists all the actions required to see and modify tags for IAM principals. The Resource element of the policy grants permissions to tag one user, John, and all roles in the account by specifying the Amazon Resource Name (ARN).

Now that I have reviewed the new APIs you can use to view and modify tags on your IAM principals, let’s go over the new IAM condition keys you can use in policies.

New IAM condition keys for tagging IAM principals

The following table lists the condition keys you can use in your IAM policies to control access by using tags. In this section, I also show examples of how context keys in policies can help you grant more specific access for tagging IAM principals.

Now that I have explained both the new APIs and condition keys for tagging IAM users and roles, let’s review two more use cases with tags.

Example policy 2: Require tags for new IAM users

Let’s say I want to apply the same tags to all new IAM users so that I can track them consistently along with my other AWS resources. Now, when you create a user, you can also pass in one or more tags. Let’s say I want to ensure that all the administrators on my team apply a CostCenter tag. I create an IAM policy that includes the actions required to create and tag users. I also use the Condition element to list the tags required to be added to each new user during creation. If an administrator forgets to add a tag, the administrator’s attempt to create the user fails.

Note: These actions are creating new users by using the AWS CLI.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ThisRequiresSpecificTagsWhenYouCreateANewUsers",
            "Effect": "Allow",
            "Action": [
                "iam:CreateUser",
                "iam:TagUser"
            ],
            "Resource": "*",
            "Condition": {
                "StringLike": {
                    
                        "aws:RequestTag/CostCenter": "*"
                 
            }
	  }
        }
    ]
} 

The preceding policy grants iam:CreateUser and iam:TagUser to allow creating and tagging IAM users in the AWS CLI. The Condition element that specifies the CostCenter tag is required during creation by using the condition key aws:RequestTag.

Example policy 3: Grant permissions to manage specific tags on IAM principals

Let’s say I want an administrator on my team, Alice, to manage two tags, Project and CostCenter, for all IAM principals in our account. The following policy allows Alice to be able to assign any value to the Project tag, but limits the values she can assign to the CostCenter tag.

{
    "Version": "2012-10-17",
    "Statement": [
       {
            "Sid": "ViewAllTags", 
            "Effect": "Allow",
            "Action": [
                "iam:ListUsers",
                "iam:ListRoles",
				"iam:ListUserTags",
                "iam:ListRoleTags"
            ],
            "Resource": "*"
        },
        {
           "Sid": "TagUserandRoleWithAnyProjectNameAndTwoCostCenters",
            "Effect": "Allow",
            "Action": [
                "iam:TagUser",
                "iam:TagRole"
            ],
            "Resource": "*",
            "Condition": {
                "StringLikeIfExists": {
                    "aws:RequestTag/Project": "*",
                    "aws:RequestTag/CostCenter": [
                        "1234",
                        "5678"
                    ]
                },
                "ForAllValues:StringLike": {
                    "aws:TagKeys": [
                        "CostCenter",
                        "Project"
                    ]
                }
            }
        },
        {
           "Sid": "UntagUserandRoleProjectCostCenter",
            "Effect": "Allow",
            "Action": [
                "iam:UntagUser",
                "iam:UntagRole"
            ],
            "Resource": "*",
            "Condition": {
                "ForAllValues:StringLike": {
                    "aws:TagKeys": [
                        "CostCenter",
                        "Project"
                    ]
                }
            }
        }
    ]
}

This policy permits Alice to view, add, and remove the Project and CostCenter tags for all principals in the account. In the Condition element of the second and third statements of the policy, I use the condition, aws:RequestTag, to define the tags Alice is allowed to add or remove as well as the values she is able to assign to those tags. Alice can assign any value to the tag, Project, but is limited to two values, 1234 and 5678, for the tag, CostCenter.

Now that you understand how to grant permissions to tag IAM principals, I will show you how to run the commands to tag a new user and an existing role.

How to add tags to a new IAM user

Using the CLI
Let’s say that IAM user, John, is a new team member and needs access to AWS. To manage resources, I use the following command to create John and add the Project, CostCenter, and EmailID tags.

aws iam create-user --user-name John --tags Key=CostCenter,Value=1234, Key=EmailID,Value=john@example.com 

To give John access to the appropriate AWS actions and resources, you can use the use the CLI to attach policies to John.

Using the console
You can also add tags to a user using the AWS console through the user creation flow as shown below.

1. Sign in to the AWS Management Console and navigate to the IAM console.
2. In the left navigation pane, select Users, and then select Add user.
3. Type the user name for the new user.
4. Select the type of access this user will have. You can select programmatic access, access to the AWS Management Console, or both.
5. Select Next: Permissions.
6. On the Set permissions page, specify how you want to assign permissions to this set of new users. You can choose between Add user to group, Copy permissions from existing user, or Attach existing policies to user directly.
7. Select Next:Tags.
8. On the Add tags (optional) page, add the tags you want to attach to this principal. I add the CostCenter tag key with a value of 1234 and the EmailID tag key with value of john@example.com.
    
   
   

   Figure 1: Add tags

9. Select Next: Review.
10. Once you reviewed all the information, select Create user. This action creates your user John with the permissions and tags you attached. You can navigate to the user Details page to view this user.
    

    How to add tags to an existing IAM role

    Using the CLI
    To manage custom data for each role in my account, I need to add the following tags to all existing roles: Company, Project, Service, and CreationDate. The following command adds these tags to all existing roles. To be able to run the commands I just demonstrated, you must have permissions granted to you in an IAM policy.

    aws iam tag-role --role-name * --tags Key=Project, Key=Service

    I can define the value of the tags for a specific role, Migration, by using the following command:

    aws iam tag-role --role-name Migration --tags Key=Project,Value=IAM, Key=Service,Value=S3
    

    Using the console
    You can use the console to add tags to roles individually. To do this, on the left side, select Roles, and then select the role you want to add tags to.
     
    

    

    Figure 2: Add tags to individual roles

    To view the existing tags on the role, select the Tags tab. The image shown below shows a Migration role in my account with two existing tags: Project with value IAM and key Service with value S3. To add tags or edit the existing tags, select Edit tags.
     
    

    

    Figure 3: Edit tags

    Summary

    When you tag IAM principals, you add custom attributes to the users and roles in your account to make it easier to manage your IAM resources. In this post, I reviewed the new APIs and condition keys and showed three policy examples that address use cases to grant permissions to tag your IAM principals. In a subsequent post, I will review how you can use tags on IAM principals to control access to AWS resources and other accounts.

    If you have comments about this post, submit them in the Comments section below. If you have questions about or suggestions for this solution, start a new thread on the IAM forum.

    Want more AWS Security news? Follow us on Twitter.