Using IAM Policy Conditions for Fine-Grained Access Control

When you grant permissions, you can use the IAM policy language to specify the conditions when a policy should take effect. In a policy statement, you can optionally specify conditions that control when it is in effect. Each condition contains one or more key-value pairs. Condition keys are not case-sensitive. For example, you might want a policy to be applied only after a specific date.

If you specify multiple conditions, or multiple keys in a single condition, they are evaluated using a logical AND operation. If you specify a single condition with multiple values for one key, they are evaluated using a logical OR operation. For permission to be granted, all conditions must be met.

You can also use placeholders when you specify conditions. For more information, see Policy Variables in the IAM User Guide. For more information about specifying conditions in an IAM policy language, see Condition in the IAM User Guide.

By default, IAM users and roles can't access the events in your account. To consume events, a user must be authorized for the PutRule API action. If you allow an IAM user or role for the events:PutRule action in their policy, then they will be able to create a rule that matches certain events. You must add a target to a rule, otherwise, a rule without a target does nothing except publish a CloudWatch metric when it matches an incoming event. Your IAM user or role must have permissions for the events:PutTargets action.

It is possible to limit access to the events by scoping the authorization to specific sources and types of events (using the events:source and events:detail-type condition keys). You can provide a condition in the policy statement of the IAM user or role that allows them to create a rule that only matches a specific set of sources and detail types. For a list showing all of condition key values and the CloudWatch Events actions and resources that they apply to, see Using IAM Policy Conditions for Fine-Grained Access Control.

Similarly, through setting conditions in your policy statements, you can decide which specific resources in your accounts can be added to a rule by an IAM user or role (using the events:TargetArn condition key). For example, if you turn on CloudTrail in your account and you have a CloudTrail stream, CloudTrail events are also available to the users in your account through CloudWatch Events. If you want your users to use CloudWatch Events and access all the events but the CloudTrail events, you can add a deny statement on the PutRule API action with a condition that any rule created by that user or role cannot match the CloudTrail event type.

For CloudTrail events, you can limit the access to a specific principal that the original API call was originated from (using the events:detail.userIdentity.principalId condition key). For example, you can allow a user to see all the CloudTrail events, except the ones that are made by a specific IAM role in your account that you use for auditing or forensics.

Condition Key	Key/Value Pair	Evaluation Types
`events:source`	`"events:source":"source "` Where `source` is the literal string for the source field of the event such as `"aws.ec2"` and `"aws.s3"`. To see more possible values for `source`, see the example events in CloudWatch Events Event Examples From Each Supported Service.	Source, Null
`events:detail-type`	`"events:detail-type":"detail-type "` Where `detail-type` is the literal string for the detail-type field of the event such as `"AWS API Call via CloudTrail"` and `"EC2 Instance State-change Notification"`. To see more possible values for `detail-type`, see the example events in CloudWatch Events Event Examples From Each Supported Service.	Detail Type, Null
`events: detail.userIdentity.principalId`	`"events: detail.userIdentity.principalId":"principal-id"` Where `principal-id` is the literal string for the detail.userIdentity.principalId field of the event with detail-type "AWS API Call via CloudTrail" such as `"AROAIDPPEZS35WEXAMPLE:AssumedRoleSessionName."`.	Principal Id, Null
`events:TargetArn`	`"events:TargetArn":"target-arn "` Where `target-arn` is the ARN of the target that can be put to a rule such as `"arn:aws:lambda:::function:*"`.	ARN, Null

For example policy statements for CloudWatch Events, see Overview of Managing Access Permissions to Your CloudWatch Events Resources.

Topics

Example 1: Limit Access to a Specific Source
Example 2: Define Multiple Sources That Can Be Used in an Event Pattern Individually
Example 3: Define a Source and a DetailType That Can Be Used in an Event Pattern
Example 4: Ensure That the Source Is Defined in the Event Pattern
Example 5: Define a List of Allowed Sources in an Event Pattern with Multiple Sources
Example 6: Ensure That AWS CloudTrail Events for API Calls from a Certain PrincipalId Are Consumed
Example 7: Limiting Access to Targets

Example 1: Limit Access to a Specific Source

The following example policies can be attached to an IAM user. Policy A allows the PutRule API action for all events, whereas Policy B allows PutRule only if the event pattern of the rule being created matches Amazon EC2 events.

Policy A:—allow any events


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowPutRuleForAllEvents",
            "Effect": "Allow",
            "Action": "events:PutRule",
            "Resource": "*"
        }
    ]
    }

Policy B:—allow events only from Amazon EC2


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowPutRuleForAllEC2Events",
            "Effect": "Allow",
            "Action": "events:PutRule",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "events:source": "aws.ec2"
                }
            }
        }
    ]
}

EventPattern is a mandatory argument to PutRule. Hence, if the user with Policy B calls PutRule with an event pattern like the following:


{
    "source": [ "aws.ec2" ]
}

The rule would be created because the policy allows for this specific source, that is, "aws.ec2". However, if the user with Policy B calls PutRulewith an event pattern like the following:


{
    "source": [ "aws.s3" ]
}

The rule creation would be denied because the policy does not allow for this specific source, that is, "aws.s3". Essentially, the user with Policy B is only allowed to create a rule that would match the events originating from Amazon EC2; hence, they are only allowed access to the events from Amazon EC2.

See the following table for a comparison of Policy A and Policy B:

Event Pattern	Allowed by Policy A	Allowed by Policy B
`{ "source": [ "aws.ec2" ] }`	Yes	Yes
`{ "source": [ "aws.ec2", "aws.s3" ] }`	Yes	No (Source aws.s3 is not allowed)
`{ "source": [ "aws.ec2" ], "detail-type": [ "EC2 Instance State-change Notification" ] }`	Yes	Yes
`{ "detail-type": [ "EC2 Instance State-change Notification" ] }`	Yes	No (Source must be specified)

Example 2: Define Multiple Sources That Can Be Used in an Event Pattern Individually

The following policy allows events from Amazon EC2 or CloudWatch Events. In other words, it allows an IAM user or role to create a rule where the source in the EventPattern is specified as either "aws.ec2" or "aws.ecs". Not defining the source results in a "deny".


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowPutRuleIfSourceIsEC2OrECS",
            "Effect": "Allow",
            "Action": "events:PutRule",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "events:source": [ "aws.ec2", "aws.ecs" ]
                }
            }
        }
    ]
}