Identity-based policy examples for Amazon CloudTrail - Amazon CloudTrail
Policy best practicesExample: Allowing and denying actions for a specified trailExamples: Creating and applying policies for actions on specific trailsExamples: Denying access to create or delete event data stores based on tagsUsing the consoleAllow users to view their own permissionsGranting custom permissions for CloudTrail users
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Identity-based policy examples for Amazon CloudTrail

By default, users and roles don't have permission to create or modify CloudTrail resources. They also can't perform tasks by using the Amazon Web Services Management Console, Amazon Command Line Interface (Amazon CLI), or Amazon API. To grant users permission to perform actions on the resources that they need, an IAM administrator can create IAM policies. The administrator can then add the IAM policies to roles, and users can assume the roles.

To learn how to create an IAM identity-based policy by using these example JSON policy documents, see Creating IAM policies in the IAM User Guide.

For details about actions and resource types defined by CloudTrail, including the format of the ARNs for each of the resource types, see Actions, Resources, and Condition Keys for Amazon CloudTrail in the Service Authorization Reference.

Policy best practices

Identity-based policies determine whether someone can create, access, or delete CloudTrail resources in your account. These actions can incur costs for your Amazon Web Services account. When you create or edit identity-based policies, follow these guidelines and recommendations:

  • Get started with Amazon managed policies and move toward least-privilege permissions – To get started granting permissions to your users and workloads, use the Amazon managed policies that grant permissions for many common use cases. They are available in your Amazon Web Services account. We recommend that you reduce permissions further by defining Amazon customer managed policies that are specific to your use cases. For more information, see Amazon managed policies or Amazon managed policies for job functions in the IAM User Guide.

  • Apply least-privilege permissions – When you set permissions with IAM policies, grant only the permissions required to perform a task. You do this by defining the actions that can be taken on specific resources under specific conditions, also known as least-privilege permissions. For more information about using IAM to apply permissions, see Policies and permissions in IAM in the IAM User Guide.

  • Use conditions in IAM policies to further restrict access – You can add a condition to your policies to limit access to actions and resources. For example, you can write a policy condition to specify that all requests must be sent using SSL. You can also use conditions to grant access to service actions if they are used through a specific Amazon Web Service, such as Amazon CloudFormation. For more information, see IAM JSON policy elements: Condition in the IAM User Guide.

  • Use IAM Access Analyzer to validate your IAM policies to ensure secure and functional permissions – IAM Access Analyzer validates new and existing policies so that the policies adhere to the IAM policy language (JSON) and IAM best practices. IAM Access Analyzer provides more than 100 policy checks and actionable recommendations to help you author secure and functional policies. For more information, see IAM Access Analyzer policy validation in the IAM User Guide.

  • Require multi-factor authentication (MFA) – If you have a scenario that requires IAM users or a root user in your Amazon Web Services account, turn on MFA for additional security. To require MFA when API operations are called, add MFA conditions to your policies. For more information, see Configuring MFA-protected API access in the IAM User Guide.

For more information about best practices in IAM, see Security best practices in IAM in the IAM User Guide.

CloudTrail doesn't have service-specific context keys that you can use in the Condition element of policy statements.

Example: Allowing and denying actions for a specified trail

The following example demonstrates a policy that allows users with the policy to view the status and configuration of a trail and start and stop logging for a trail named My-First-Trail. This trail was created in the US East (Ohio) Region (its home Region) in the Amazon Web Services account with the ID 123456789012.

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Allow",
          "Action": [
              "cloudtrail:StartLogging",
              "cloudtrail:StopLogging",
              "cloudtrail:GetTrail",
              "cloudtrail:GetTrailStatus",
              "cloudtrail:GetEventSelectors"
          ],
          "Resource": [
              "arn:aws:cloudtrail:us-east-2:123456789012:trail/My-First-Trail"
          ]
      }
  ]
}

The following example demonstrates a policy that explicitly denies CloudTrail actions for any trail not named My-First-Trail.

{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Effect": "Deny",
          "Action": [
              "cloudtrail:*"
          ],
          "NotResource": [
              "arn:aws:cloudtrail:us-east-2:123456789012:trail/My-First-Trail"
          ]
      }
  ]
}

Examples: Creating and applying policies for actions on specific trails

You can use permissions and policies to control a user's ability to perform specific actions on CloudTrail trails.

For example, you don't want users of your company’s developer group to start or stop logging on a specific trail. However, you might want to grant them permission to perform the DescribeTrails and GetTrailStatus actions on the trail. You want the users of the developer group to perform the StartLogging or StopLogging actions on trails that they manage.

You can create two policy statements and attach them to the developer group you create in IAM. For more information about groups in IAM, see IAM Groups in the IAM User Guide.

In the first policy, you deny the StartLogging and StopLogging actions for the trail ARN that you specify. In the following example, the trail ARN is arn:aws:cloudtrail:us-east-2:123456789012:trail/Example-Trail.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1446057698000",
            "Effect": "Deny",
            "Action": [
                "cloudtrail:StartLogging",
                "cloudtrail:StopLogging"
            ],
            "Resource": [
                "arn:aws:cloudtrail:us-east-2:123456789012:trail/Example-Trail"
            ]
        }
    ]
}

In the second policy, the DescribeTrails and GetTrailStatus actions are allowed on all CloudTrail resources:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1446072643000",
            "Effect": "Allow",
            "Action": [
                "cloudtrail:DescribeTrails",
                "cloudtrail:GetTrail",
                "cloudtrail:GetTrailStatus"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

If a user of the developer group tries to start or stop logging on the trail that you specified in the first policy, that user gets an access denied exception. Users of the developer group can start and stop logging on trails that they create and manage.

The following examples show that the configured developer group in an Amazon CLI profile named devgroup. First, a user of devgroup runs the describe-trails command. 

$ aws --profile devgroup cloudtrail describe-trails

The command complete successfully with the following output:

{
    "trailList": [
        {
            "IncludeGlobalServiceEvents": true, 
            "Name": "Default", 
            "TrailARN": "arn:aws:cloudtrail:us-east-2:123456789012:trail/Example-Trail", 
            "IsMultiRegionTrail": false, 
            "S3BucketName": "myS3bucket ", 
            "HomeRegion": "us-east-2"
        }
    ]
}

The user then runs the get-trail-status command on the trail that you specified in the first policy.

$ aws --profile devgroup cloudtrail get-trail-status --name Example-Trail

The command complete successfully with the following output:

{
    "LatestDeliveryTime": 1449517556.256, 
    "LatestDeliveryAttemptTime": "2015-12-07T19:45:56Z", 
    "LatestNotificationAttemptSucceeded": "", 
    "LatestDeliveryAttemptSucceeded": "2015-12-07T19:45:56Z", 
    "IsLogging": true, 
    "TimeLoggingStarted": "2015-12-07T19:36:27Z", 
    "StartLoggingTime": 1449516987.685, 
    "StopLoggingTime": 1449516977.332, 
    "LatestNotificationAttemptTime": "", 
    "TimeLoggingStopped": "2015-12-07T19:36:17Z"
}

Next, a user in the devgroup group runs the stop-logging command on the same trail. 

$ aws --profile devgroup cloudtrail stop-logging --name Example-Trail

The command returns an access denied exception, such as the following:

A client error (AccessDeniedException) occurred when calling the StopLogging operation: Unknown

The user runs the start-logging command on the same trail. 

$ aws --profile devgroup cloudtrail start-logging --name Example-Trail

Again the command returns an access denied exception, such as the following:

A client error (AccessDeniedException) occurred when calling the StartLogging operation: Unknown

Examples: Denying access to create or delete event data stores based on tags

In the following policy example, permission to create an event data store with CreateEventDataStore is denied if at least one of the following conditions aren't met:

  • The event data store doesn't have a tag key of stage applied to itself

  • The value of the stage tag isn't alpha, beta, gamma, or prod.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "cloudtrail:CreateEventDataStore",
            "Resource": "*",
            "Condition": {
                "Null": {
                    "aws:RequestTag/stage": "true"
                }
            }
        },
        {
            "Effect": "Deny",
            "Action": "cloudtrail:CreateEventDataStore",
            "Resource": "*",
            "Condition": {
                "ForAnyValue:StringNotEquals": {
                    "aws:RequestTag/stage": [
                        "alpha",
                        "beta",
                        "gamma",
                        "prod"
                    ]
                }
            }
        }
    ]
}

In the following policy example, permission to delete an event data store with DeleteEventDataStore is denied is if the event data store has a stage tag with a value of prod. A policy like this one can help protect an event data store from accidental deletion.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "cloudtrail:DeleteEventDataStore",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/stage": "prod"
                }
            }
        }
    ]
}

Using the CloudTrail console

To access the Amazon CloudTrail console, you must have a minimum set of permissions. These permissions must allow you to list and view details about the CloudTrail resources in your Amazon Web Services account. If you create an identity-based policy that is more restrictive than the minimum required permissions, the console won't function as intended for entities (users or roles) with that policy.

You don't need to allow minimum console permissions for users that are making calls only to the Amazon CLI or the Amazon API. Instead, allow access to only the actions that match the API operation that they're trying to perform.

Granting permissions for CloudTrail administration

To allow IAM roles or users to administer a CloudTrail resource, such as a trail, event data store, or channel, you must grant explicit permissions to perform the actions associated with CloudTrail tasks. In most situations, you can use an Amazon managed policy that contains predefined permissions.

Note

The permissions you grant to users to perform CloudTrail administration tasks aren't the same as the permissions that CloudTrail requires to deliver log files to Amazon S3 buckets or send notifications to Amazon SNS topics. For more information about those permissions, see Amazon S3 bucket policy for CloudTrail.

If you configure integration with Amazon CloudWatch Logs, CloudTrail also requires a role that it can assume to deliver events to an Amazon CloudWatch Logs log group. You must create the role that CloudTrail uses. For more information, see Granting permission to view and configure Amazon CloudWatch Logs information on the CloudTrail console and Sending events to CloudWatch Logs.

The following Amazon managed policies are available for CloudTrail:

  • AWSCloudTrail_FullAccess – This policy provides full access to CloudTrail actions on CloudTrail resources, such as trails, event data stores, and channels. This policy provides the required permissions to create, update, and delete CloudTrail trails, event data stores, and channels.

    This policy also provides permissions to manage the Amazon S3 bucket, the log group for CloudWatch Logs, and an Amazon SNS topic for a trail. However, the AWSCloudTrail_FullAccess managed policy doesn't provide permissions to delete the Amazon S3 bucket, the log group for CloudWatch Logs, or an Amazon SNS topic. For information about managed policies for other Amazon Web Services, see the Amazon Managed Policy Reference Guide.

    Note

    The AWSCloudTrail_FullAccess policy isn't intended to be shared broadly across your Amazon Web Services account. Users with this role can turn off or reconfigure the most sensitive and important auditing functions in their Amazon Web Services accounts. For this reason, you must only apply this policy to account administrators. You must closely control and monitor use of this policy.

  • AWSCloudTrail_ReadOnlyAccess – This policy grants permissions to view the CloudTrail console, including recent events and event history. This policy also allows you to view existing trails, event data stores, and channels. Roles and users with this policy can download the event history, but they can't create or update trails, event data stores, or channels.

To provide access, add permissions to your users, groups, or roles:

Additional resources

To learn more about using IAM to give identities, such as users and roles, access to resources in your account, see Getting set up with IAM and Access management for Amazon resources in the IAM User Guide.

You don't need to allow minimum console permissions for users that are making calls only to the Amazon CLI or the Amazon API. Instead, allow access to only the actions that match the API operation that you're trying to perform.

Allow users to view their own permissions

This example shows how you might create a policy that allows IAM users to view the inline and managed policies that are attached to their user identity. This policy includes permissions to complete this action on the console or programmatically using the Amazon CLI or Amazon API.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ViewOwnUserInfo",
            "Effect": "Allow",
            "Action": [
                "iam:GetUserPolicy",
                "iam:ListGroupsForUser",
                "iam:ListAttachedUserPolicies",
                "iam:ListUserPolicies",
                "iam:GetUser"
            ],
            "Resource": ["arn:aws-cn:iam::*:user/${aws:username}"]
        },
        {
            "Sid": "NavigateInConsole",
            "Effect": "Allow",
            "Action": [
                "iam:GetGroupPolicy",
                "iam:GetPolicyVersion",
                "iam:GetPolicy",
                "iam:ListAttachedGroupPolicies",
                "iam:ListGroupPolicies",
                "iam:ListPolicyVersions",
                "iam:ListPolicies",
                "iam:ListUsers"
            ],
            "Resource": "*"
        }
    ]
}

Granting custom permissions for CloudTrail users

CloudTrail policies grant permissions to users who work with CloudTrail. If you need to grant different permissions to users, you can attach a CloudTrail policy to an IAM group or to a user. You can edit the policy to include or exclude specific permissions. You can also create your own custom policy. Policies are JSON documents that define the actions a user is allowed to perform and the resources that the user is allowed to perform those actions on. For specific examples, see Example: Allowing and denying actions for a specified trail and Examples: Creating and applying policies for actions on specific trails.

Read-only access

The following example shows a policy that grants read-only access to CloudTrail trails. This is equivalent to the managed policy AWSCloudTrail_ReadOnlyAccess. It grants users permission to see trail information, but not to create or update trails.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudtrail:Get*",
                "cloudtrail:Describe*",
                "cloudtrail:List*",
                "cloudtrail:LookupEvents"
            ],
            "Resource": "*"
        }
    ]
}

In the policy statements, the Effect element specifies whether the actions are allowed or denied. The Action element lists the specific actions that the user is allowed to perform. The Resource element lists the Amazon resources the user is allowed to perform those actions on. For policies that control access to CloudTrail actions, the Resource element is usually set to *, a wildcard that means "all resources."

The values in the Action element correspond to the APIs that the services support. The actions are preceded by cloudtrail: to indicate that they refer to CloudTrail actions. You can use the * wildcard character in the Action element , such as in the following examples:

  • "Action": ["cloudtrail:*Logging"]

    This allows all CloudTrail actions that end with "Logging" (StartLogging, StopLogging).

  • "Action": ["cloudtrail:*"]

    This allows all CloudTrail actions, but not actions for other Amazon services.

  • "Action": ["*"]

    This allows all Amazon actions. This permission is suitable for a user who acts as an Amazon administrator for your account.

The read-only policy doesn't grant user permission for the CreateTrail, UpdateTrail, StartLogging, and StopLogging actions. Users with this policy are not allowed to create trails, update trails, or turn logging on and off. For the list of CloudTrail actions, see the Amazon CloudTrail API Reference.

Full access

The following example shows a policy that grants full access to CloudTrail. This is equivalent to the managed policy AWSCloudTrail_FullAccess. It grants users the permission to perform all CloudTrail actions. It also lets users log data events in Amazon S3 and Amazon Lambda, manage files in Amazon S3 buckets, manage how CloudWatch Logs monitors CloudTrail log events, and manage Amazon SNS topics in the account that the user is associated with.

Important

The AWSCloudTrail_FullAccess policy or equivalent permissions are not intended to be shared broadly across your Amazon account. Users with this role or equivalent access have the ability to disable or reconfigure the most sensitive and important auditing functions in their Amazon accounts. For this reason, this policy should be applied only to account administrators, and use of this policy should be closely controlled and monitored.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sns:AddPermission",
                "sns:CreateTopic",
                "sns:SetTopicAttributes",
                "sns:GetTopicAttributes"
            ],
            "Resource": [
                "arn:aws:sns:*:*:aws-cloudtrail-logs*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "sns:ListTopics"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:CreateBucket",
                "s3:PutBucketPolicy"
            ],
            "Resource": [
                "arn:aws:s3:::aws-cloudtrail-logs*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListAllMyBuckets",
                "s3:GetBucketLocation",
                "s3:GetBucketPolicy"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "cloudtrail:*",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup"
            ],
            "Resource": [
                "arn:aws:logs:*:*:log-group:aws-cloudtrail-logs*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:ListRoles",
                "iam:GetRolePolicy",
                "iam:GetUser"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:PassRole"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "iam:PassedToService": "cloudtrail.amazonaws.com"
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "kms:CreateKey",
                "kms:CreateAlias",
                "kms:ListKeys",
                "kms:ListAliases"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "lambda:ListFunctions"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "dynamodb:ListGlobalTables",
                "dynamodb:ListTables"
            ],
            "Resource": "*"
        }
    ]
}

Granting permission to view Amazon Config information on the CloudTrail console

You can view event information on the CloudTrail console, including resources that are related to that event. For these resources, you can choose the Amazon Config icon to view the timeline for that resource in the Amazon Config console. Attach this policy to your users to grant them read-only Amazon Config access. The policy doesn't grant them permission to change settings in Amazon Config.

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": [
            "config:Get*",
            "config:Describe*",
            "config:List*"
        ],
        "Resource": "*"
    }]
}

For more information, see Viewing resources referenced with Amazon Config.

Granting permission to view and configure Amazon CloudWatch Logs information on the CloudTrail console

You can view and configure delivery of events to CloudWatch Logs in the CloudTrail console if you have sufficient permissions. These are permissions that may be beyond those granted for CloudTrail administrators. Attach this policy to administrators who will configure and manage CloudTrail integration with CloudWatch Logs. The policy doesn't grant them permissions in CloudTrail or in CloudWatch Logs directly, but instead grants the permissions required to create and configure the role CloudTrail will assume to successfully deliver events to your CloudWatch Logs group.

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": [
            "iam:CreateRole",
            "iam:PutRolePolicy",
            "iam:AttachRolePolicy",
            "iam:ListRoles",
            "iam:GetRolePolicy",
            "iam:GetUser"
        ],
        "Resource": "*"
    }]
}

For more information, see Monitoring CloudTrail Log Files with Amazon CloudWatch Logs.

Additional information

To learn more about using IAM to give identities, such as users and roles, access to resources in your account, see Getting started and Access management for Amazon resources in the IAM User Guide.