AWS Identity and Access Management
User Guide

AWS Global Condition Context Keys

When a principal makes a request to AWS, AWS gathers the request information into a request context. You can use the Condition element of a JSON policy to compare the request context with values that you specify in your policy. To learn more about the circumstances under which a global key is included in the request context, see the Availability information for each global condition key. For information about how to use the Condition element in a JSON policy, see IAM JSON Policy Elements: Condition.

Note

If you use condition keys that are available only in some circumstances, you can use the IfExists versions of the condition operators. If the condition keys are missing from a request context, the policy can fail the evaluation. For example, use the following condition block with ...IfExists operators to match when a request comes from a specific IP range or from a specific VPC. If either or both keys are not included in the request context, the condition still returns true. The values are only checked if the specified key is included in the request context.

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

Global condition keys are condition keys with an aws: prefix. AWS services can provide service-specific keys that include the service prefix. For example, IAM condition keys include the iam: prefix. For more information, see Actions, Resources, and Condition Keys for AWS Services and choose the service whose keys you want to view.

aws:CurrentTime

Works with date operators.

Use this key to compare the date and time of the request with the date and time that you specify in the policy.

  • Availability – This key is always included in the request context.

aws:EpochTime

Works with date operators or numeric operators.

Use this key to compare the date and time of the request in epoch or Unix time with the value that you specify in the policy. This key also accepts the number of seconds since January 1, 1970.

  • Availability – This key is always included in the request context.

aws:MultiFactorAuthAge

Works with numeric operators.

Use this key to compare the number of seconds since the requesting principal was authorized using MFA with the number that you specify in the policy. For more information about MFA, see Using Multi-Factor Authentication (MFA) in AWS.

  • Availability – This key is included in the request context only if the principal was authenticated using MFA. If MFA was not used, this key is not present.

aws:MultiFactorAuthPresent

Works with Boolean operators.

Use this key to check whether multi-factor authentication (MFA) was used to validate the temporary security credentials that made the request.

  • Availability – This key is included in the request context only when the principal uses temporary credentials to make the request. The key is not present in AWS CLI, AWS API, or AWS SDK requests that are made using long-term credentials.

Temporary credentials are used to authenticate IAM roles, federated users, IAM users with temporary tokens from sts:GetSessionToken, and users of the AWS Management Console. IAM users in the AWS Management Console unknowingly use temporary credentials. Users sign into the console using their user name and password, which are long-term credentials. However, in the background, the console generates temporary credentials on behalf of the user. To learn which services support using temporary credentials, see AWS Services That Work with IAM.

The aws:MultiFactorAuthPresent key is not present when an API or CLI command is called with long-term credentials, such as user 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 whether a request is authenticated using MFA.

##### WARNING: NOT RECOMMENDED ##### "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 that are made using long-term credentials, or to requests that are authenticated using MFA. Use this example with caution because its logic is complicated and it does not test whether MFA-authentication was actually used.

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

Recommended Combination

We recommend that you use the BoolIfExists operator to check whether a request is authenticated using MFA.

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

This combination of Deny, BoolIfExists, and false denies requests that are not authenticated using MFA. Specifically, it denies requests from temporary credentials that do not include MFA. It also denies requests that are made using long-term credentials, such as AWS CLI or AWS API operations made using access keys. The *IfExists operator checks for the presence of the aws:MultiFactorAuthPresent key and whether or not it could be present, as indicated by its existence. Use this when you want to deny any request that is not authenticated using MFA. This is more secure, but can break any code or scripts that use access keys to access the AWS CLI or AWS API.

Alternative Combinations

You can also use the BoolIfExists operator to allow MFA-authenticated requests and AWS CLI or AWS API requests that are 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 Allow, BoolIfExists, and true allows requests that are authenticated using MFA, or requests that cannot be authenticated using MFA. This means that AWS CLI, AWS API, and AWS SDK operations are allowed when the requester uses their long-term access keys. This combination does not allow requests from temporary credentials that could, but do not include MFA.

When you create a policy using the IAM console visual editor and choose MFA required, this combination is applied. This setting requires MFA for console access, but allows programmatic access with no MFA.

Alternatively, you can use the Bool operator to allow programmatic and console requests only when authenticated using MFA.

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

This combination of the Allow, Bool, and true allows only MFA-authenticated requests. This applies only to temporary credentials that support using MFA. This statement does not allow access to requests that were made using long-term access keys, 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:

##### WARNING: USE WITH CAUTION ##### "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 that are made using temporary credentials, and denies access for long-term credentials. Use this example with caution because it does not test whether MFA-authentication was actually used.

aws:PrincipalAccount

Works with string operators.

Use this key to compare the account to which the requesting principal belongs with the account identifier that you specify in the policy.

  • Availability – This key is always included in the request context.

aws:PrincipalArn

Works with ARN operators.

Use this key to compare the Amazon Resource Name (ARN) of the principal that made the request with the ARN that you specify in the policy. For IAM roles, the request context returns the ARN of the role, not the ARN of the user that assumed the role. To learn which types of principals you can specify in this condition key, see Specifying a Principal.

  • Availability – This key is always included in the request context.

aws:PrincipalOrgID

Works with string operators.

Use this key to compare the identifier of the organization in AWS Organizations to which the requesting principal belongs with the identifier specified in the policy.

  • Availability – This key is included in the request context only if the principal is a member of an organization.

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. You can specify the organization ID in the condition element. When you add and remove accounts, policies that include the aws:PrincipalOrgID key 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.

aws:PrincipalTag

Works with string operators.

Use this key to compare the tag attached to the principal making the request with the tag that you specify in the policy. If the principal has more than one tag attached, the request context includes one aws:PrincipalTag key for each attached tag key.

  • Availability – This key is included in the request context only if the principal is an IAM user or IAM role with attached tags.

You can add custom attributes to a user or role in the form of a key-value pair. For more information about IAM tags, see Tagging IAM Users and Roles. You can use aws:PrincipalTag to control access for AWS principals.

This example shows how you might create a policy that allows users with the tagManager=true tag to manage IAM users, groups, or roles. To use this policy, replace the red italicized text in the example policy with your own information.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:*", "Resource": "*", "Condition": {"StringEquals": {"aws:PrincipalTag/tagManager": "true"}} } ] }

aws:PrincipalType

Works with string operators.

Use this key to compare the type of principal making the request with the principal type that you specify in the policy. For details about how the information appears in the request context for different principals, see Specifying a Principal.

  • Availability – This key is always included in the request context.

aws:Referer

Works with string operators.

Use this key to compare who referred the request in the client browser with the referer that you specify in the policy. The aws:referer request context value is provided by the caller in an HTTP header.

  • Availability – This key is included in the request context only if the request was invoked using a URL in the browser.

For example, you can call Amazon S3 API operations directly using a web browser. This means that you can view S3 objects, such as images and documents, directly through a web browser. The aws:referer condition allows you to restrict access to specific values in the HTTP or HTTPS request based on the value of the referrer header.

Warning

This key should be used carefully. It is dangerous to include a publicly known referer header value. 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, such as content stored in Amazon S3, from being referenced on unauthorized third-party sites.

aws:RequestedRegion

Works with string operators.

Use this key to compare the AWS Region that was called in the request with the region that you specify in the policy. You can use this global condition key to control which Regions can be requested. To view the AWS Regions for each service, see AWS Regions and Endpoints in the Amazon Web Services General Reference.

  • Availability – This key is always included in the request context.

Some global services, such as IAM, have a single endpoint. 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, then IAM calls 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:Describe*", "ec2:Export*", "ec2:Get*", "ec2:Search*" ], "Resource": "*" }, { "Sid": "InstanceWriteRegionRestricted", "Effect": "Allow", "Action": [ "ec2:Associate*", "ec2:Import*", "ec2:Modify*", "ec2:Monitor*", "ec2:Reset*", "ec2:Run*", "ec2:Start*", "ec2:Stop*", "ec2:Terminate*" ], "Resource": "*", "Condition": { "StringEquals": { "aws:RequestedRegion": [ "eu-west-1", "eu-west-2", "eu-west-3" ] } } } ] }

aws:RequestTag/tag-key

Works with string operators.

Use this key to compare the tag key-value pair that was passed in the request with the tag pair that you specify in the policy. For example, you could check whether the request includes the tag key "Dept" and that it has the value "Accounting". For more information, see Controlling Access During AWS Requests.

  • Availability – This key is included in the request context when tags are passed in the request. When multiple tags are passed in the request, there is one context key for each tag key-value pair.

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

Because you can include multiple tag key-value pairs in a request, the request content could be a multivalued request. In this case, you should consider using the ForAllValues or ForAnyValue set operators. For more information, see Using Multiple Keys and Values.

aws:ResourceTag/tag-key

Works with string operators.

Use this key to compare the tag key-value pair that you specify in the policy with the key-value pair that is attached to the resource. For example, you could require that access to a resource is allowed only if the resource has the attached tag key "Dept" with the value "Marketing". For more information, see Controlling Access to AWS Resources.

  • Availability – This key is included in the request context when the requested resource already has attached tags. There is one context key for each tag key-value pair.

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

aws:SecureTransport

Works with Boolean operators.

Use this key to check whether the request was sent using SSL. The request context returns true or false. In a policy, you can allow specific actions only if the request is sent using SSL.

  • Availability – This key is always included in the request context.

aws:SourceAccount

Works with string operators.

Use this key to compare the source of the request with the account ID that you specify in the policy. For example, assume that you have an Amazon S3 bucket in your account that is configured to deliver object creation events to an Amazon 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.

  • Availability – This key is included in the request context only if a resource triggers a service to call another service on behalf of the resource owner.

aws:SourceArn

Works with ARN operators.

Use this key to compare the source of the request with the Amazon Resource Name (ARN) that you specify in the policy. For example, when an Amazon S3 bucket update triggers an Amazon SNS topic post, the Amazon S3 service invokes the sns:Publish API operation. The bucket is considered the source of the SNS request and the value of the key is the bucket's ARN. This key does not work with the ARN of the principal making the request. Instead, use aws:PrincipalArn.

  • Availability – This key is included in the request context only if a resource triggers a service to call another service on behalf of the resource owner.

The source's ARN includes the account ID, so it is not necessary to use aws:SourceAccount with aws:SourceArn.

aws:SourceIp

Works with IP address operators.

Use this key to compare the requester's IP address with the IP address that you specify in the policy. To learn about the condition operators that you can use with this key, see IP Address Condition Operators.

  • Availability – This key is included in the request context, except when the requester uses a VPC endpoint to make the request.

The aws:SourceIp condition key can be used in a policy to allow principals to make requests only from within a specified IP range. However, this policy would deny access to an AWS service that makes calls on your behalf. For example, assume that AWS CloudFormation uses a service role to call Amazon EC2 to stop an instance. In this case, the request is denied because the target service (Amazon EC2) sees the IP address of the calling service (AWS CloudFormation). The request context does not include 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 such as aws:VpcSourceIp. For more information about using VPC enpdpoints, see VPC Endpoints - Controlling the Use of Endpoints in the Amazon VPC User Guide.

aws:SourceVpc

Works with string operators.

Use this key to check whether the request comes from the VPC that you specify in the policy. In a policy, you can use this key to allow access to only a specific VPC. For more information, see Restricting Access to a Specific VPC in the Amazon Simple Storage Service Developer Guide.

  • Availability – This key is included in the request context only if the requester uses a VPC endpoint to make the request.

aws:SourceVpce

Works with string operators.

Use this key to compare the VPC endpoint identifier of the request with the endpoint ID that you specify in the policy. In a policy, you can use this key to restrict 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.

  • Availability – This key is included in the request context only if the requester uses a VPC endpoint to make the request.

aws:TagKeys

Works with string operators.

Use this key to compare the tag keys in a request with the keys that you specify in the policy. As a best practice when you use policies to control access using tags, use the aws:TagKeys condition key to define what tag keys are allowed. For example policies and more information, see Controlling Access Based on Tag Keys.

  • Availability – This key is included in the request context only if the operation supports attaching tags to resources.

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"]).

Because you can include multiple tag key-value pairs in a request, the request content could be a multivalued request. In this case, you should consider using the ForAllValues or ForAnyValue set operators. For more information, see Using Multiple Keys and Values.

Some services support tagging with resource operations, such as creating, modifying, or deleting a resource. To allow tagging and operations as a single call, you must create a policy that includes both the tagging action and the resource-modifying action. You can then use the aws:TagKeys condition key to enforce using specific tag keys in the request. For example, to limit tags when someone creates an Amazon EC2 snapshot, you must include the ec2:CreateSnapshot creation action and the ec2:CreateTags tagging action in the policy. To view a policy for this scenario that uses aws:TagKeys, see Creating a Snapshot with Tags in the Amazon EC2 User Guide for Linux Instances.

aws:TokenIssueTime

Works with date operators.

Use this key to compare the date and time that temporary security credentials were issued with the date and time that you specify in the policy.

  • Availability – This key is included in the request context only when the principal uses temporary credentials to make the request. They key is not present in AWS CLI, AWS API, or AWS SDK requests that are made using access keys.

To learn which services support using temporary credentials, see AWS Services That Work with IAM.

aws:UserAgent

Works with string operators.

Use this key to compare the requester's client application with the application that you specify in the policy.

  • Availability – This key is always included in the request context.

Warning

This key should be used carefully. Since the aws:UserAgent value is provided by the caller in an HTTP header, unauthorized parties can use modified or custom browsers to provide any aws:UserAgent value that they choose. As a result, aws:UserAgent should not be used to prevent unauthorized parties from making direct AWS requests. You can use it to allow only specific client applications, and only after testing your policy.

aws:userid

Works with string operators.

Use this key to compare the requester's principal identifier with the ID that you specify in the policy. For IAM users, the request context value is the user ID. For IAM roles, this value format can vary. For details about how the information appears for different principals, see Specifying a Principal.

  • Availability – This key is included in the request context for all signed requests. Anonymous requests do not include this key.

aws:username

Works with string operators.

Use this key to compare the requester's user name with the user name that you specify in the policy. For details about how the information appears for different principals, see Specifying a Principal.

  • Availability – This key is always included in the request context for IAM users. Anonymous requests and requests that are made using the AWS account root user or IAM roles do not include this key.

aws:VpcSourceIp

Works with IP address operators.

Use this key to compare the IP address from which a request was made with the IP address that you specify in the policy. In a policy, the key matches only if the request originates from the specified IP address and it goes through a VPC endpoint.

  • Availability – This key is included in the request context only if the request is made using a VPC endpoint.

For more information, see Controlling Access to Services with VPC Endpoints in the Amazon VPC User Guide.