Controlling access to Amazon resources using tags - Amazon Identity and Access Management
Controlling access to Amazon resourcesControlling access during Amazon requestsControlling access based on tag keys
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 (PDF).

Controlling access to Amazon resources using tags

You can use tags to control access to your Amazon resources that support tagging, including IAM resources. You can tag IAM users and roles to control what they can access. To learn how to tag IAM users and roles, see Tagging IAM resources. Additionally, you can control access to the following IAM resources: customer managed policies, IAM identity providers, instance profiles, server certificates, and virtual MFA devices. To view a tutorial for creating and testing a policy that allows IAM roles with principal tags to access resources with matching tags, see IAM tutorial: Define permissions to access Amazon resources based on tags. Use the information in the following section to control access to other Amazon resources, including IAM resources, without tagging IAM users or roles.

Before you use tags to control access to your Amazon resources, you must understand how Amazon grants access. Amazon is composed of collections of resources. An Amazon EC2 instance is a resource. An Amazon S3 bucket is a resource. You can use the Amazon API, the Amazon CLI, or the Amazon Web Services Management Console to perform an operation, such as creating a bucket in Amazon S3. When you do, 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.

Amazon 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, Amazon checks all the policies that apply to the context of your request. Most policies are stored in Amazon as JSON documents and specify the permissions for principal entities. For more information about policy types and uses, see Policies and permissions in IAM.

Amazon 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 How IAM works. For details about how IAM determines whether a request is allowed, see Policy evaluation logic.

Tags are another consideration in 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 Amazon service supports controlling access using tags, see Amazon services that work with IAM and look for the services that have Yes in the ABAC column. Choose the name of the service to view the authorization and access control documentation for that service.

You can then create an IAM policy that allows or denies access to a resource based on that resource's tag. In that policy, you can use tag condition keys to control access to any of the following:

  • Resource – Control access to Amazon 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 a 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 to tag an Amazon resource.

  • Any part of the authorization process – Use the aws:TagKeys condition key to control whether specific tag keys can be 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.

Note

Some services allow users to specify tags when they create the resource if they have permissions to use the action that creates the resource.

Controlling access to Amazon resources

You can use conditions in your IAM policies to control access to Amazon 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. Some services support only the service-specific version of this key and not the global version.

Warning

Do not try to control who can pass a role by tagging the role and then using the ResourceTag condition key in a policy with the iam:PassRole action. This approach does not have reliable results. For more information about permissions required to pass a role to a service, see Granting a user permissions to pass a role to an Amazon service.

This example shows how you might create an identity-based policy that allows starting or stopping Amazon EC2 instances. These operations are allowed only if the instance tag Owner has the value of the user name. This policy defines permissions for programmatic and console access. 

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:StartInstances",
                "ec2:StopInstances"
            ],
            "Resource": "arn:aws-cn:ec2:*:*:instance/*",
            "Condition": {
                "StringEquals": {"aws: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.

This example shows how you might create an identity-based policy that uses the team principal tag in the resource ARN. The policy grants permission to delete Amazon Simple Queue Service queues, but only if the queue name starts with the team name followed by -queue. For example, qa-queue if qa is the team name for the team principal tag.

{
      "Version": "2012-10-17",
      "Statement": {
        "Sid": "AllQueueActions",
        "Effect": "Allow",
        "Action": "sqs:DeleteQueue",
        "Resource": "arn:aws-cn:sqs:us-west-2::${aws:PrincipalTag/team}-queue"
      }
}

Controlling access during Amazon requests

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

This example shows how you might create an identity-based policy that allows using the Amazon EC2 CreateTags action to attach tags to an instance. You can attach tags only if the tag contains the environment key and the preprod or production values. If you want, you can 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-cn:ec2:*:*:instance/*",
        "Condition": {
            "StringEquals": {
                "aws:RequestTag/environment": [
                    "preprod",
                    "production"
                ]
            },
            "ForAllValues:StringEquals": {"aws:TagKeys": "environment"}
        }
    }
}

Controlling access based on tag keys

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

We recommend that when you use policies to control access using tags, you use the aws:TagKeys condition key. Amazon 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 stack=production and Stack=test. Key names are not case sensitive in policy conditions. This means that if you specify "aws: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, or use tag policies, available with Amazon Organizations. For more information see Tag Policies in the Organizations User Guide.

This example shows how you might create an identity-based policy that allows creating and tagging a Secrets Manager secret, but only with the tag keys environment or cost-center. The Null condition ensures that the condition evaluates to false if there are no tags in the request.

{
        "Effect": "Allow",
        "Action": [
            "secretsmanager:CreateSecret",
            "secretsmanager:TagResource"
        ],
        "Resource": "*",
        "Condition": {
            "Null": {
                "aws:TagKeys": "false"
            },
            "ForAllValues:StringEquals": {
                "aws:TagKeys": [
                    "environment",
                    "cost-center"
                ]
            }
        }
}