AWS Identity and Access Management
User Guide

Controlling Access Using Tags

Before you use tags to control access, you must understand how AWS grants access. AWS is composed of collections of resources. An IAM user is a resource. An Amazon S3 bucket is a resource. When you use the AWS API, the AWS CLI, or the AWS Management Console to perform an operation (such as creating a user), you send a request for that operation. Your request specifies an action, a resource, a principal entity (user or role), a principal account, and any necessary request information. All of this information provides context.

AWS then checks that you (the principal entity) are authenticated (signed in) and authorized (have permission) to perform the specified action on the specified resource. During authorization, AWS checks all the policies that apply to the context of your request. Most policies are stored in AWS as JSON documents and specify the permissions for principal entities. For more information about policy types and uses, see Policies and Permissions.

AWS authorizes the request only if each part of your request is allowed by the policies. To view a diagram and learn more about the IAM infrastructure, see Understanding How IAM Works. For details about how IAM determines whether a request is allowed, see Policy Evaluation Logic.

Tags can complicate this process because tags can be attached to the resource or passed in the request to services that support tagging. To control access based on tags, you provide tag information in the condition element of a policy. To learn whether an AWS service supports controlling access using tags, see AWS Services That Work with IAM and look for the services that have Yes in the Authorization based on tags column. Choose the name of the service to view the authorization and access control documentation for that service.

When you create an IAM policy, you can use tag condition keys to control access to do any of the following:

  • Resource – Control access to AWS service resources based on the tags on those resources. To do this, use the ResourceTag/key-name condition key to determine whether to allow access to the resource based on the tags that are attached to the resource.

  • Request – Control what tags can be passed in an IAM request. To do this, use the aws:RequestTag/key-name condition key to specify what tag key–value pairs can be passed in a request that tags an AWS resource.

  • Tag Keys – Use the aws:TagKeys condition key to control whether specific tag keys can be used on a resource or in a request.

You can create an IAM policy visually, using JSON, or by importing an existing managed policy. For details, see Creating IAM Policies.

Controlling Access to Resources

You can use conditions in your IAM policies to control access to AWS resources based on the tags on that resource. You can do this using the global aws:ResourceTag/tag-key condition key, or a service-specific key such as aws:RequestTag/tag-key. You can also use these condition keys to allow untagging resources only with specific tag key–value pairs.

Note

Do not use the ResourceTag condition key in a policy with the iam:PassRole action. You cannot use the tag on an IAM role to control access to who can pass that role. For more information about permissions required to pass a role to a service, see Granting a User Permissions to Pass a Role to an AWS Service.

This example shows how you might create a policy that allows starting or stopping Amazon EC2 instances, but only if the instance tag Owner has the value of that user's user name. This policy also grants the permissions necessary to complete this action on the console.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:StartInstances", "ec2:StopInstances" ], "Resource": "arn:aws:ec2:*:*:instance/*", "Condition": { "StringEquals": {"ec2:ResourceTag/Owner": "${aws:username}"} } }, { "Effect": "Allow", "Action": "ec2:DescribeInstances", "Resource": "*" } ] }

You can attach this policy to the IAM users in your account. If a user named richard-roe attempts to start an Amazon EC2 instance, the instance must be tagged Owner=richard-roe or owner=richard-roe. Otherwise he will be denied access. The tag key Owner matches both Owner and owner because condition key names are not case-sensitive. For more information, see IAM JSON Policy Elements: Condition.

Controlling Access to Requests

You can use conditions in your IAM policies to control what tag key–value pairs can be passed in a request that tags an AWS resource.

This example shows how you might create a policy that allows using the Amazon EC2 CreateTags action to attach tags to an instance only if the tag contains the environment key and the preprod or production values. As a best practice, use the ForAllValues modifier with the aws:TagKeys condition key to indicate that only the key environment is allowed in the request. This stops users from including other keys, such as accidentally using Environment instead of environment.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "ec2:CreateTags", "Resource": "arn:aws:ec2:*:*:instance/*", "Condition": { "StringEquals": { "aws:RequestTag/environment": [ "preprod", "production" ] }, "ForAllValues:StringEquals": {"aws:TagKeys": "environment"} } } }

Controlling Tag Keys

You can use a condition in your IAM policies to control whether specific tag keys can be used on a resource or in a request.

As a best practice, when you use policies to control access using tags, you should use the aws:TagKeys condition key. AWS services that support tags might allow you to create multiple tag key names that differ only by case, such as tagging an Amazon EC2 instance with foo=bar1 and Foo=bar2. Key names are not case sensitive in policy conditions. This means that if you specify "ec2:ResourceTag:TagKey1": "Value1" in the condition element of your policy, then the condition matches a resource tag key named either TagKey1 or tagkey1, but not both. To prevent duplicate tags with a key that varies only by case, use the aws:TagKeys condition to define the tag keys that your users can apply.

This example shows how you might create a policy that allows creating and tagging a Secrets Manager secret, but only with the tag keys environment or cost-center.

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "secretsmanager:CreateSecret", "secretsmanager:TagResource" ], "Resource": "*", "Condition": { "ForAllValues:StringEquals": { "aws:TagKeys": [ "environment", "cost-center" ] } } } }