AWS Identity and Access Management
User Guide

AWS Global Condition Context Keys

You can use the Condition element of a JSON policy in IAM to test the value of keys that are included in the evaluation context of all AWS API requests. These keys provide information about the request itself or the resources that the request references. You can check that keys have specified values before allowing the action that is requested by the user. This gives you granular control over when your JSON policy statements match or don't match an incoming API request. For information about how to use the Condition element in a JSON policy, see IAM JSON Policy Elements: Condition.

This topic describes the globally available keys (with an aws: prefix), as well as the keys that are defined and provided by the IAM service (with an iam: prefix). Several other AWS services also provide service-specific keys that are relevant to the actions and resources that are defined by that service. For more information, see Actions, Resources, and Condition Keys for AWS Services. The documentation for a service that supports condition keys often has additional information. For example, for information about keys that you can use in policies for Amazon S3 resources, see Amazon S3 Policy Keys in the Amazon Simple Storage Service Developer Guide.

Note

If you use condition keys that are available only in some scenarios (such as aws:SourceIp and aws:SourceVpc), you can use the IfExists versions of the comparison operators. If the condition keys are missing from a request context (and you haven't set IfExists), the policy engine can fail the evaluation. For example, if you want to write a policy that restricts access from a particular IP range or from a particular VPC, you can construct the conditions as follows:

"Condition": {"IpAddressIfExists": {"aws:SourceIp" : ["xxx"] }, "StringEqualsIfExists" : {"aws:SourceVpc" : ["yyy"]} }

This condition matches (1) if the aws:SourceIp context key exists and has the value xxx or (2) if the aws:SourceVpc context key exists and has the value yyy. If either or both keys do not exist, the condition still matches. The test is only made if the specified key exists in the request context. If it is not there, it is treated as "I don't care."

AWS provides the following predefined condition keys for all AWS services that support IAM for access control:

aws:CurrentTime

Works with date operators.

The current date and time to check for date/time conditions.

aws:EpochTime

Works with date operators.

The current date and time in epoch or Unix time to check for date/time conditions.

aws:MultiFactorAuthAge

Works with numeric operators.

Checks how long ago (in seconds) the MFA-validated security credentials that made the request were issued using multi-factor authentication (MFA). If MFA was not used, this key is not present. See Using Multi-Factor Authentication (MFA) in AWS. Therefore, this is another key with which you should consider using the *IfExists versions of the comparison operators. This ensures that the results of the comparison are what you expect even when the key is not present in the request context.

aws:MultiFactorAuthPresent

Works with Boolean operators.

Checks whether multi-factor authentication (MFA) was used to validate the temporary security credentials that made the current request. This key is present in the request context only when the user uses temporary credentials to call the API. Such credentials are used with IAM roles, federated users, IAM users with credentials from sts:GetSessionToken, and users of the AWS Management Console. (The console uses temporary credentials that are generated on the users' behalf in the background.) The aws:MultiFactorAuthPresent key is never present when an API or CLI command is called with long-term credentials, such as standard access key pairs. Therefore we recommend that when you check for this key that you use the ...IfExists versions of the condition operators.

It is important to understand that the following Condition element is not a reliable way to check for the use of MFA:

##### THIS EXAMPLE DOES NOT WORK ##### "Effect" : "Deny", "Condition" : { "Bool" : { "aws:MultiFactorAuthPresent" : false } }

This combination of the Deny effect, Bool element, and false value denies requests that can be authenticated using MFA, but were not. This applies only to temporary credentials that support using MFA. This statement does not deny access to requests made using long-term credentials, or to requests that were authenticated using MFA. Because of the complicated logic, we do not recommend using this condition.

Also do not use the combination of the Deny effect, Null element, and true because it behaves the same way.

Instead, we recommend that you use the BoolIfExists operator to check the value.

"Effect" : "Deny", "Condition" : { "BoolIfExists" : { "aws:MultiFactorAuthPresent" : false } }

The *IfExists operator checks for the presence of the aws:MultiFactorAuthPresent and whether or not it COULD be present, as indicated by its existence. This combination of the Deny effect, BoolIfExists element, and false value denies requests that are not authenticated using MFA. It denies requests from temporary credentials that could be authenticated but do not include MFA. It also denies requests made using long-term credentials, such as IAM user access keys.

You can also use the BoolIfExists operator to allow MFA-authenticated requests and requests made using long-term credentials.

"Effect" : "Allow", "Condition" : { "BoolIfExists" : { "aws:MultiFactorAuthPresent" : true } }

This condition matches either if the key exists and is present or if the key does not exist. This combination of the Allow effect, BoolIfExists element, and true value allows requests that are authenticated using MFA, or requests that cannot be authenticated using MFA. It does not allow requests from temporary credentials that could be authenticated but do not include MFA. Use this when you don't want requests made with long-term credentials to fail.

Alternatively, you can allow only requests that are authenticated using MFA.

"Effect" : "Allow", "Condition" : { "Bool" : { "aws:MultiFactorAuthPresent" : true } }

This combination of the Allow effect, Bool element, and true value allows only MFA-authenticated requests. This applies only to temporary credentials that support using MFA. This statement does not allow access to requests made using long-term credentials, or to requests made using temporary credentials without MFA.

Do not use a policy construct similar to the following to check whether the MFA key is present:

##### THIS EXAMPLE DOES NOT WORK ##### "Effect" : "Allow", "Condition" : { "Null" : { "aws:MultiFactorAuthPresent" : false } }

This combination of the Allow effect, Null element, and false value allows only requests that can be authenticated using MFA, regardless of whether the request is actually authenticated. This allows all requests made using temporary credentials, and denies access for long-term credentials. This example does not test whether MFA-authentication was actually used.

aws:PrincipalOrgID

Works with string operators.

The identifier of an organization that you created using AWS Organizations. This global key provides an alternative to listing all the account IDs for all AWS accounts in an organization. You can use this condition key to simplify specifying the Principal element in a resource-based policy. Instead of listing all the accounts that are members of an organization, you can specify the organization ID in the condition element. When you add and remove accounts, policies that include aws:PrincipalOrgID automatically include the correct accounts and don't require manual updating.

For example, the following Amazon S3 bucket policy allows members of any account in the o-xxxxxxxxxxx organization to add an object into the policy-ninja-dev bucket.

{ "Version": "2012-10-17", "Statement": { "Sid": "AllowPutObject", "Effect": "Allow", "Principal": "*", "Action": "s3:putobject", "Resource": "arn:aws:s3:::policy-ninja-dev/*", "Condition": {"StringEquals": {"aws:PrincipalOrgID":["o-xxxxxxxxxxx"]} } } }

Note

This global condition also applies to the master account of an AWS organization.

For more information about AWS Organizations, see What Is AWS Organizations? in the AWS Organizations User Guide.

This condition key is available for only some services.

aws:PrincipalType

Works with string operators.

Checks the type of principal (user, account, federated user, etc.) for the current request.

This condition key is available for only some services.

aws:Referer

Works with string operators.

Checks who referred the client browser to the address that the request is being sent to. It is only supported by some services, such as Amazon S3, as a service that can be directly addressed by a web browser. The value comes from the referer header in the HTTPS request that is made to AWS.

Warning

This key should be used carefully: aws:referer allows Amazon S3 bucket owners to help prevent their content from being served up by unauthorized third-party sites to standard web browsers. For more information, see the link in the previous paragraph. Since the aws:referer value is provided by the caller in an HTTP header, unauthorized parties can use modified or custom browsers to provide any aws:referer value that they choose. As a result, aws:referer should not be used to prevent unauthorized parties from making direct AWS requests. It is offered only to allow customers to protect their digital content, stored in Amazon S3, from being referenced on unauthorized third-party sites.

This condition key is available for only some services.

aws:RequestedRegion

Works with string operators.

Checks whether an AWS request is made to a specific region. You can use this global condition key to control which regions your users can make calls to. To view the AWS regions for each service, see AWS Regions and Endpoints in the Amazon Web Services General Reference.

Global services, such as IAM, have a single endpoint. However, because this endpoint is physically located in the US East (N. Virginia) region, IAM calls are always made to the us-east-1 region. For example, if you create a policy that denies access to all services if the requested region is not us-west-2, the IAM calls will always fail. To view an example of how to work around this, see NotAction with Deny.

Note

The aws:RequestedRegion condition key allows you to control which endpoint of a service is invoked but does not control the impact of the operation. Some services have cross-region impacts. For example, Amazon S3 has API operations that control cross-region replication. You can invoke s3:PutBucketReplication in one region (which is affected by the aws:RequestedRegion condition key), but other regions are affected based on the replications configuration settings.

You can use this context key to limit access to AWS services within a given set of regions. For example, the following policy allows a user to view all of the Amazon EC2 instances in the AWS Management Console. However it only allows them to make changes to instances in Ireland (eu-west-1), London (eu-west-2), or Paris (eu-west-3).

{ "Version": "2012-10-17", "Statement": [ { "Sid": "InstanceConsoleReadOnly", "Effect": "Allow", "Action": [ "ec2:DescribeInstances", "ec2:DescribeIamInstanceProfileAssociations", "ec2:DescribeInstanceAttribute", "ec2:DescribeReservedInstancesOfferings", "ec2:DescribeClassicLinkInstances", "ec2:DescribeSpotInstanceRequests", "ec2:GetReservedInstancesExchangeQuote", "ec2:DescribeInstanceCreditSpecifications", "ec2:DescribeSpotFleetInstances", "ec2:DescribeScheduledInstances", "ec2:DescribeScheduledInstanceAvailability", "ec2:DescribeReservedInstancesModifications", "ec2:DescribeReservedInstances", "ec2:DescribeReservedInstancesListings", "ec2:DescribeInstanceStatus" ], "Resource": "*" }, { "Sid": "InstanceWriteRegionRestricted", "Effect": "Allow", "Action": [ "ec2:ModifyInstancePlacement", "ec2:TerminateInstances", "ec2:ImportInstance", "ec2:StartInstances", "ec2:MonitorInstances", "ec2:RunScheduledInstances", "ec2:ResetInstanceAttribute", "ec2:RunInstances", "ec2:ModifyInstanceAttribute", "ec2:StopInstances", "ec2:AssociateIamInstanceProfile", "ec2:ModifyReservedInstances" ], "Resource": "*", "Condition": {"StringEquals": {"aws:RequestedRegion": [ "eu-west-1", "eu-west-2", "eu-west-3" ]}} } ] }

This condition key is available for only some services.

aws:RequestTag/tag-key

Works with string operators.

This context key is formatted "aws:RequestTag/tag-key":"tag-value" where tag-key and tag-value are a tag key and value pair.

Checks a tag and its value in an AWS request. For example, you could check to see that the request includes the tag key "Dept" and that it has the value "Accounting".

This AWS condition key was introduced for Amazon EC2 and is supported by a limited number of additional services. Check your service to see whether it supports using this condition key.

aws:SecureTransport

Works with Boolean operators.

Checks whether the request was sent using SSL.

aws:SourceAccount

Works with string operators.

Checks whether the source of the request comes from a specific account. For example, assume that you have an S3 bucket in your account that is configured to deliver object creation events to an SNS topic. In that case, you could use this condition key to check that Amazon S3 is not being used as a confused deputy. Amazon S3 tells Amazon SNS the account that the bucket belongs to.

This condition key is available for only some services.

aws:SourceArn

Works with ARN operators.

Checks the source of the request, using the Amazon Resource Name (ARN) of the source.

This condition key is available for only some services.

aws:SourceIp

Works with IP address operators.

Checks the requester's IP address, see IP Address Condition Operators.

Note

The aws:SourceIp condition key should be used in a JSON policy only for IAM users, groups, roles, or federated users that make API calls from within the specified IP range. This policy denies access to an AWS service that makes calls on your behalf. For example, assume that you have a service role that allows AWS CloudFormation to call Amazon EC2 to stop an instance. In that case, the request is denied because the target service (Amazon EC2) sees the IP address of the calling service (AWS CloudFormation) rather than the IP address of the originating user. There is no way to pass the originating IP address through a calling service to the target service for evaluation in a JSON policy.

If the request comes from a host that uses an Amazon VPC endpoint, then the aws:SourceIp key is not available. You should instead use a VPC-specific key. For more information, see VPC Endpoints - Controlling the Use of Endpoints in the Amazon VPC User Guide.

aws:SourceVpc

Works with string operators.

Restricts access to a specific VPC. For more information, see Restricting Access to a Specific VPC in the Amazon Simple Storage Service Developer Guide. (This condition key is supported for traffic to an AWS service over a VPC endpoint.)

aws:SourceVpce

Works with string operators.

Restricts access to a specific VPC endpoint. For more information, see Restricting Access to a Specific VPC Endpoint in the Amazon Simple Storage Service Developer Guide.

This condition key is available for only some services.

aws:TagKeys

Works with string operators.

This context key is formatted "aws:TagKeys":"tag-key" where tag-key is a list of tag keys without values (for example, ["Dept","Cost-Center"]).

Checks the tag keys that are present in an AWS request. This AWS condition key was introduced for Amazon EC2 and is supported by a limited number of additional services. Check your service to see whether it supports using this condition key.

aws:TokenIssueTime

Works with date operators.

Checks the date/time that temporary security credentials were issued. This key is only present in requests that are signed using temporary security credentials. For more information about temporary security credentials, see Temporary Security Credentials.

aws:UserAgent

Works with string operators.

Checks the requester's client application.

aws:userid

Works with string operators.

Checks the requester's user ID.

This condition key is available for only some services.

aws:username

Works with string operators.

Checks the requester's user name.

This condition key is available for only some services.