Controlling access to AWS resources using tags

You can use tags to control access to your AWS 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 Tags for AWS Identity and Access Management 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 AWS resources based on tags. Use the information in the following section to control access to other AWS resources, including IAM resources, without tagging IAM users or roles.

Before you use tags to control access to your AWS resources, you must understand how AWS grants access. AWS is composed of collections of resources. An Amazon EC2 instance is a resource. An Amazon S3 bucket is a resource. You can use the AWS API, the AWS CLI, or the AWS 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.

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 in AWS Identity and Access Management.

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 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 AWS service supports controlling access using tags, see AWS 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:

You can create an IAM policy visually, using JSON, or by importing an existing managed policy. For details, see Define custom IAM permissions with customer managed policies.

Controlling access to AWS 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. Some services support only the service-specific version of this key and not the global version.

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: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:sqs:us-east-2::${aws:PrincipalTag/team}-queue"
      }
}

Controlling access during AWS 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 to an AWS 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: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. 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 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 AWS 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"
                ]
            }
        }
}