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 keys in the request context with key values that you specify in your policy. Request information is provided by different sources, including the principal making the request, the resource the request is made against, and the metadata about the request itself.

Global condition keys can be used across all AWS services. While these condition keys can be used in all policies, the key is not available in every request context. For example, the aws:SourceAccount condition key is only available when the call to your resource is made directly by an AWS service principal. To learn more about the circumstances under which a global key is included in the request context, see the Availability information for each key.

Some individual services create their own condition keys that are available in the request context for other services. Cross-service condition keys are a type of global condition key that include a prefix matching the name of the service, such as ec2: or lambda:, but are available across other services.

Service-specific condition keys are defined for use with an individual AWS service. For example, Amazon S3 lets you write a policy with the s3:VersionId condition key to limit access to a specific version of an Amazon S3 object. This condition key is unique to the service, meaning it only works with requests to the Amazon S3 service. For condition keys that are service-specific, see Actions, Resources, and Condition Keys for AWS Services and choose the service whose keys you want to view.

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

Sensitive condition keys

The following condition keys are considered sensitive. The use of wildcards in these condition keys does not have any valid use cases, even with a substring of the key value with a wildcard. This is because the wildcard might match the condition key to any value, which could pose a security risk.

Properties of the principal

Use the following condition keys to compare details about the principal making the request with the principal properties that you specify in the policy. For a list of principals that can make requests, see How to specify a principal.

aws:PrincipalArn

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.

You can specify the root user ARN as a value for condition key aws:PrincipalArn in AWS Organizations service control policies (SCPs). SCPs are a type of organization policy used to manage permissions in your organization and affect only member accounts in the organization. An SCP restricts permissions for IAM users and roles in member accounts, including the member account's root user. For more information about the effect of SCPs on permissions, see SCP effects on permissions in the AWS Organizations User Guide.

aws:PrincipalAccount

Use this key to compare the account to which the requesting principal belongs with the account identifier that you specify in the policy. For anonymous requests, the request context returns anonymous.

In the following example, access is denied except to principals with the account number 123456789012.

aws:PrincipalOrgPaths

Use this key to compare the AWS Organizations path for the principal who is making the request to the path in the policy. That principal can be an IAM user, IAM role, AWS STS federated user principal, or AWS account root user. In a policy, this condition key ensures that the requester is an account member within the specified organization root or organizational units (OUs) in AWS Organizations. An AWS Organizations path is a text representation of the structure of an AWS Organizations entity. For more information about using and understanding paths, see Understand the AWS Organizations entity path.

For example, the following condition returns true for principals in accounts that are attached directly to the ou-ab12-22222222 OU, but not in its child OUs.

"Condition" : { "ForAnyValue:StringEquals" : {
     "aws:PrincipalOrgPaths":["o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/ou-ab12-22222222/"]
}}

The following condition returns true for principals in an account that is attached directly to the OU or any of its child OUs. When you include a wildcard, you must use the StringLike condition operator.

"Condition" : { "ForAnyValue:StringLike" : {
     "aws:PrincipalOrgPaths":["o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/ou-ab12-22222222/*"]
}}

The following condition returns true for principals in an account that is attached directly to any of the child OUs, but not directly to the parent OU. The previous condition is for the OU or any children. The following condition is for only the children (and any children of those children).

"Condition" : { "ForAnyValue:StringLike" : {
     "aws:PrincipalOrgPaths":["o-a1b2c3d4e5/r-ab12/ou-ab12-11111111/ou-ab12-22222222/ou-*"]
}}

The following condition allows access for every principal in the o-a1b2c3d4e5 organization, regardless of their parent OU.

"Condition" : { "ForAnyValue:StringLike" : {
     "aws:PrincipalOrgPaths":["o-a1b2c3d4e5/*"]
}}

aws:PrincipalOrgPaths is a multivalued condition key. Multivalued keys can have multiple values in the request context. When you use multiple values with the ForAnyValue condition operator, the principal's path must match one of the paths listed in the policy. For more information about multivalued condition keys, see Set operators for multivalued context keys.

    "Condition": {
        "ForAnyValue:StringLike": {
            "aws:PrincipalOrgPaths": [
                "o-a1b2c3d4e5/r-ab12/ou-ab12-33333333/*",
                "o-a1b2c3d4e5/r-ab12/ou-ab12-22222222/*"
            ]
        }
    }

aws:PrincipalOrgID

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.

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 amzn-s3-demo-bucket bucket.

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

aws:PrincipalTag/tag-key

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.

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 Tags for AWS Identity and Access Management resources. You can use aws:PrincipalTag to control access for AWS principals.

This example shows how you might create an identity-based policy that allows users with the department=hr tag to manage IAM users, groups, or roles. To use this policy, replace the italicized placeholder text in the example policy with your own information. Then, follow the directions in create a policy or edit a policy.

aws:PrincipalIsAWSService

Use this key to check whether the call to your resource is being made directly by an AWS service principal. For example, AWS CloudTrail uses the service principal cloudtrail.amazonaws.com to write logs to your Amazon S3 bucket. The request context key is set to true when a service uses a service principal to perform a direct action on your resources. The context key is set to false if the service uses the credentials of an IAM principal to make a request on the principal's behalf. It is also set to false if the service uses a service role or service-linked role to make a call on the principal's behalf.

You can use this condition key to limit access to your trusted identities and expected network locations while safely granting access to AWS services.

In the following Amazon S3 bucket policy example, access to the bucket is restricted unless the request originates from vpc-111bbb22 or is from a service principal, such as CloudTrail.

In the following video, learn more about how you might use the aws:PrincipalIsAWSService condition key in a policy.

aws:PrincipalServiceName

Use this key to compare the service principal name in the policy with the service principal that is making requests to your resources. You can use this key to check whether this call is made by a specific service principal. When a service principal makes a direct request to your resource, the aws:PrincipalServiceName key contains the name of the service principal. For example, the AWS CloudTrail service principal name is cloudtrail.amazonaws.com.