# Setting up a new cross-account subscription
Follow the steps in these sections to set up a new cross-account log subscription.
**Topics**
+ [
# Step 1: Create a destination
](CreateDestination.md)
+ [
# Step 2: (Only if using an organization) Create an IAM role
](CreateSubscriptionFilter-IAMrole.md)
+ [
# Step 3: Add/validate IAM permissions for the cross-account destination
](Subscription-Filter-CrossAccount-Permissions.md)
+ [
# Step 4: Create a subscription filter
](CreateSubscriptionFilter.md)
+ [
# Validate the flow of log events
](ValidateLogEventFlow.md)
+ [
# Modify destination membership at runtime
](ModifyDestinationMembership.md)
# Step 1: Create a destination
**Important**
All steps in this procedure are to be done in the log data recipient account.
For this example, the log data recipient account has an AWS account ID of 999999999999, while the log data sender AWS account ID is 111111111111.
This example creates a destination using a Amazon Kinesis Data Streams stream called RecipientStream, and a role that enables CloudWatch Logs to write data to it.
When the destination is created, CloudWatch Logs sends a test message to the destination on the recipient account’s behalf. When the subscription filter is active later, CloudWatch Logs sends log events to the destination on the source account’s behalf.
**To create a destination**
1. In the recipient account, create a destination stream in Amazon Kinesis Data Streams. At a command prompt, type:
```
aws kinesis create-stream --stream-name "RecipientStream" --shard-count 1
```
1. Wait until the stream becomes active. You can use the **aws kinesis describe-stream** command to check the **StreamDescription.StreamStatus** property. In addition, take note of the **StreamDescription.StreamARN** value because you will pass it to CloudWatch Logs later:
```
aws kinesis describe-stream --stream-name "RecipientStream"
{
"StreamDescription": {
"StreamStatus": "ACTIVE",
"StreamName": "RecipientStream",
"StreamARN": "arn:aws:kinesis:us-east-1:999999999999:stream/RecipientStream",
"Shards": [
{
"ShardId": "shardId-000000000000",
"HashKeyRange": {
"EndingHashKey": "34028236692093846346337460743176EXAMPLE",
"StartingHashKey": "0"
},
"SequenceNumberRange": {
"StartingSequenceNumber": "4955113521868881845667950383198145878459135270218EXAMPLE"
}
}
]
}
}
```
It might take a minute or two for your stream to show up in the active state.
1. Create the IAM role that grants CloudWatch Logs the permission to put data into your stream. First, you'll need to create a trust policy in a file **\$1/TrustPolicyForCWL.json**. Use a text editor to create this policy file, do not use the IAM console.
This policy includes a `aws:SourceArn` global condition context key that specifies the `sourceAccountId` to help prevent the confused deputy security problem. If you don't yet know the source account ID in the first call, we recommend that you put the destination ARN in the source ARN field. In the subsequent calls, you should set the source ARN to be the actual source ARN that you gathered from the first call. For more information, see [Confused deputy prevention](Subscriptions-confused-deputy.md).
```
{
"Statement": {
"Effect": "Allow",
"Principal": {
"Service": "logs.amazonaws.com"
},
"Condition": {
"StringLike": {
"aws:SourceArn": [
"arn:aws:logs:region:sourceAccountId:*",
"arn:aws:logs:region:recipientAccountId:*"
]
}
},
"Action": "sts:AssumeRole"
}
}
```
1. Use the **aws iam create-role** command to create the IAM role, specifying the trust policy file. Take note of the returned Role.Arn value because it will also be passed to CloudWatch Logs later:
```
aws iam create-role \
--role-name CWLtoKinesisRole \
--assume-role-policy-document file://~/TrustPolicyForCWL.json
{
"Role": {
"AssumeRolePolicyDocument": {
"Statement": {
"Action": "sts:AssumeRole",
"Effect": "Allow",
"Condition": {
"StringLike": {
"aws:SourceArn": [
"arn:aws:logs:region:sourceAccountId:*",
"arn:aws:logs:region:recipientAccountId:*"
]
}
},
"Principal": {
"Service": "logs.amazonaws.com"
}
}
},
"RoleId": "AAOIIAH450GAB4HC5F431",
"CreateDate": "2015-05-29T13:46:29.431Z",
"RoleName": "CWLtoKinesisRole",
"Path": "/",
"Arn": "arn:aws:iam::999999999999:role/CWLtoKinesisRole"
}
}
```
1. Create a permissions policy to define which actions CloudWatch Logs can perform on your account. First, use a text editor to create a permissions policy in a file **\$1/PermissionsForCWL.json**:
```
{
"Statement": [
{
"Effect": "Allow",
"Action": "kinesis:PutRecord",
"Resource": "arn:aws:kinesis:region:999999999999:stream/RecipientStream"
}
]
}
```
1. Associate the permissions policy with the role by using the **aws iam put-role-policy** command:
```
aws iam put-role-policy \
--role-name CWLtoKinesisRole \
--policy-name Permissions-Policy-For-CWL \
--policy-document file://~/PermissionsForCWL.json
```
1. After the stream is in the active state and you have created the IAM role, you can create the CloudWatch Logs destination.
1. This step doesn't associate an access policy with your destination and is only the first step out of two that completes a destination creation. Make a note of the **DestinationArn** that is returned in the payload:
```
aws logs put-destination \
--destination-name "testDestination" \
--target-arn "arn:aws:kinesis:region:999999999999:stream/RecipientStream" \
--role-arn "arn:aws:iam::999999999999:role/CWLtoKinesisRole"
{
"DestinationName" : "testDestination",
"RoleArn" : "arn:aws:iam::999999999999:role/CWLtoKinesisRole",
"DestinationArn" : "arn:aws:logs:us-east-1:999999999999:destination:testDestination",
"TargetArn" : "arn:aws:kinesis:us-east-1:999999999999:stream/RecipientStream"
}
```
1. After step 7a is complete, in the log data recipient account, associate an access policy with the destination. This policy must specify the **logs:PutSubscriptionFilter** action and grants permission to the sender account to access the destination.
The policy grants permission to the AWS account that sends logs. You can specify just this one account in the policy, or if the sender account is a member of an organization, the policy can specify the organization ID of the organization. This way, you can create just one policy to allow multiple accounts in one organization to send logs to this destination account.
Use a text editor to create a file named `~/AccessPolicy.json` with one of the following policy statements.
This first example policy allows all accounts in the organization that have an ID of `o-1234567890` to send logs to the recipient account.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": "*",
"Action": "logs:PutSubscriptionFilter",
"Resource": "arn:aws:logs:us-east-1:999999999999:destination:testDestination",
"Condition": {
"StringEquals": {
"aws:PrincipalOrgID": [
"o-1234567890"
]
}
}
}
]
}
```
------
This next example allows just the log data sender account (111111111111) to send logs to the log data recipient account.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"AWS": "111111111111"
},
"Action": "logs:PutSubscriptionFilter",
"Resource": "arn:aws:logs:us-east-1:999999999999:destination:testDestination"
}
]
}
```
------
1. Attach the policy you created in the previous step to the destination.
```
aws logs put-destination-policy \
--destination-name "testDestination" \
--access-policy file://~/AccessPolicy.json
```
This access policy enables users in the AWS Account with ID 111111111111 to call **PutSubscriptionFilter** against the destination with ARN arn:aws:logs:*region*:999999999999:destination:testDestination. Any other user's attempt to call PutSubscriptionFilter against this destination will be rejected.
To validate a user's privileges against an access policy, see [Using Policy Validator](https://docs.aws.amazon.com/IAM/latest/UserGuide/policies_policy-validator.html) in the *IAM User Guide*.
When you have finished, if you're using AWS Organizations for your cross-account permissions, follow the steps in [Step 2: (Only if using an organization) Create an IAM role](CreateSubscriptionFilter-IAMrole.md). If you're granting permissions directly to the other account instead of using Organizations, you can skip that step and proceed to [Step 4: Create a subscription filter](CreateSubscriptionFilter.md).
# Step 2: (Only if using an organization) Create an IAM role
In the previous section, if you created the destination by using an access policy that grants permissions to the organization that account `111111111111` is in, instead of granting permissions directly to account `111111111111`, then follow the steps in this section. Otherwise, you can skip to [Step 4: Create a subscription filter](CreateSubscriptionFilter.md).
The steps in this section create an IAM role, which CloudWatch can assume and validate whether the sender account has permission to create a subscription filter against the recipient destination.
Perform the steps in this section in the sender account. The role must exist in the sender account, and you specify the ARN of this role in the subscription filter. In this example, the sender account is `111111111111`.
**To create the IAM role necessary for cross-account log subscriptions using AWS Organizations**
1. Create the following trust policy in a file `/TrustPolicyForCWLSubscriptionFilter.json`. Use a text editor to create this policy file; do not use the IAM console.
```
{
"Statement": {
"Effect": "Allow",
"Principal": { "Service": "logs.amazonaws.com" },
"Action": "sts:AssumeRole"
}
}
```
1. Create the IAM role that uses this policy. Take note of the `Arn` value that is returned by the command, you will need it later in this procedure. In this example, we use `CWLtoSubscriptionFilterRole` for the name of the role we're creating.
```
aws iam create-role \
--role-name CWLtoSubscriptionFilterRole \
--assume-role-policy-document file://~/TrustPolicyForCWLSubscriptionFilter.json
```
1. Create a permissions policy to define the actions that CloudWatch Logs can perform on your account.
1. First, use a text editor to create the following permissions policy in a file named `~/PermissionsForCWLSubscriptionFilter.json`.
```
{
"Statement": [
{
"Effect": "Allow",
"Action": "logs:PutLogEvents",
"Resource": "arn:aws:logs:region:111111111111:log-group:LogGroupOnWhichSubscriptionFilterIsCreated:*"
}
]
}
```
1. Enter the following command to associate the permissions policy you just created with the role that you created in step 2.
```
aws iam put-role-policy
--role-name CWLtoSubscriptionFilterRole
--policy-name Permissions-Policy-For-CWL-Subscription-filter
--policy-document file://~/PermissionsForCWLSubscriptionFilter.json
```
When you have finished, you can proceed to [Step 4: Create a subscription filter](CreateSubscriptionFilter.md).
# Step 3: Add/validate IAM permissions for the cross-account destination
According to AWS cross-account policy evaluation logic, in order to access any cross-account resource (such as an Kinesis or Firehose stream used as a destination for a subscription filter) you must have an identity-based policy in the sending account which provides explicit access to the cross-account destination resource. For more information about policy evaluation logic, see [ Cross-account policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic-cross-account.html).
You can attach the identity-based policy to the IAM role or IAM user that you are using to create the subscription filter. This policy must be present in the sending account. If you are using the Administrator role to create the subscription filter, you can skip this step and move on to [Step 4: Create a subscription filter](CreateSubscriptionFilter.md).
**To add or validate the IAM permissions needed for cross-account**
1. Enter the following command to check which IAM role or IAM user is being used to run AWS logs commands.
```
aws sts get-caller-identity
```
The command returns output similar to the following:
```
{
"UserId": "User ID",
"Account": "sending account id",
"Arn": "arn:aws:sending account id:role/user:RoleName/UserName"
}
```
Make note of the value represented by *RoleName* or *UserName*.
1. Sign into the AWS Management Console in the sending account and search for the attached policies with the IAM role or IAM user returned in the output of the command you entered in step 1.
1. Verify that the policies attached to this role or user provide explicit permissions to call `logs:PutSubscriptionFilter` on the cross-account destination resource.
The following policy provides permissions to create a subscription filter on any destination resource only in a single AWS account, account `999999999999`:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowSubscriptionFiltersOnAccountResources",
"Effect": "Allow",
"Action": "logs:PutSubscriptionFilter",
"Resource": [
"arn:aws:logs:*:*:log-group:*",
"arn:aws:logs:*:123456789012:destination:*"
]
}
]
}
```
------
The following policy provides permissions to create a subscription filter only on a specific destination resource named `sampleDestination` in single AWS account, account `123456789012`:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowSubscriptionFiltersonAccountResource",
"Effect": "Allow",
"Action": "logs:PutSubscriptionFilter",
"Resource": [
"arn:aws:logs:*:*:log-group:*",
"arn:aws:logs:*:123456789012:destination:sampleDestination"
]
}
]
}
```
------
# Step 4: Create a subscription filter
After you create a destination, the log data recipient account can share the destination ARN (arn:aws:logs:us-east-1:999999999999:destination:testDestination) with other AWS accounts so that they can send log events to the same destination. These other sending accounts users then create a subscription filter on their respective log groups against this destination. The subscription filter immediately starts the flow of real-time log data from the chosen log group to the specified destination.
**Note**
If you are granting permissions for the subscription filter to an entire organization, you will need to use the ARN of the IAM role that you created in [Step 2: (Only if using an organization) Create an IAM role](CreateSubscriptionFilter-IAMrole.md).
In the following example, a subscription filter is created in a sending account. the filter is associated with a log group containing AWS CloudTrail events so that every logged activity made by "Root" AWS credentials is delivered to the destination you previously created. That destination encapsulates a stream called "RecipientStream".
The rest of the steps in the following sections assume that you have followed the directions in [Sending CloudTrail Events to CloudWatch Logs](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/send-cloudtrail-events-to-cloudwatch-logs.html) in the *AWS CloudTrail User Guide* and created a log group that contains your CloudTrail events. These steps assume that the name of this log group is `CloudTrail/logs`.
When you enter the following command, be sure you are signed in as the IAM user or using the IAM role that you added the policy for, in [Step 3: Add/validate IAM permissions for the cross-account destination](Subscription-Filter-CrossAccount-Permissions.md).
```
aws logs put-subscription-filter \
--log-group-name "CloudTrail/logs" \
--filter-name "RecipientStream" \
--filter-pattern "{$.userIdentity.type = Root}" \
--destination-arn "arn:aws:logs:region:999999999999:destination:testDestination"
```
The log group and the destination must be in the same AWS Region. However, the destination can point to an AWS resource such as a Amazon Kinesis Data Streams stream that is located in a different Region.
# Validate the flow of log events
After you create the subscription filter, CloudWatch Logs forwards all the incoming log events that match the filter pattern to the stream that is encapsulated within the destination stream called "**RecipientStream**". The destination owner can verify that this is happening by using the **aws kinesis get-shard-iterator** command to grab a Amazon Kinesis Data Streams shard, and using the **aws kinesis get-records** command to fetch some Amazon Kinesis Data Streams records:
```
aws kinesis get-shard-iterator \
--stream-name RecipientStream \
--shard-id shardId-000000000000 \
--shard-iterator-type TRIM_HORIZON
{
"ShardIterator":
"AAAAAAAAAAFGU/kLvNggvndHq2UIFOw5PZc6F01s3e3afsSscRM70JSbjIefg2ub07nk1y6CDxYR1UoGHJNP4m4NFUetzfL+wev+e2P4djJg4L9wmXKvQYoE+rMUiFq+p4Cn3IgvqOb5dRA0yybNdRcdzvnC35KQANoHzzahKdRGb9v4scv+3vaq+f+OIK8zM5My8ID+g6rMo7UKWeI4+IWiKEXAMPLE"
}
aws kinesis get-records \
--limit 10 \
--shard-iterator
"AAAAAAAAAAFGU/kLvNggvndHq2UIFOw5PZc6F01s3e3afsSscRM70JSbjIefg2ub07nk1y6CDxYR1UoGHJNP4m4NFUetzfL+wev+e2P4djJg4L9wmXKvQYoE+rMUiFq+p4Cn3IgvqOb5dRA0yybNdRcdzvnC35KQANoHzzahKdRGb9v4scv+3vaq+f+OIK8zM5My8ID+g6rMo7UKWeI4+IWiKEXAMPLE"
```
**Note**
You might need to rerun the get-records command a few times before Amazon Kinesis Data Streams starts to return data.
You should see a response with an array of Amazon Kinesis Data Streams records. The data attribute in the Amazon Kinesis Data Streams record is compressed in gzip format and then base64 encoded. You can examine the raw data from the command line using the following Unix command:
```
echo -n "" | base64 -d | zcat
```
The base64 decoded and decompressed data is formatted as JSON with the following structure:
```
{
"owner": "111111111111",
"logGroup": "CloudTrail/logs",
"logStream": "111111111111_CloudTrail/logs_us-east-1",
"subscriptionFilters": [
"RecipientStream"
],
"messageType": "DATA_MESSAGE",
"logEvents": [
{
"id": "3195310660696698337880902507980421114328961542429EXAMPLE",
"timestamp": 1432826855000,
"message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}"
},
{
"id": "3195310660696698337880902507980421114328961542429EXAMPLE",
"timestamp": 1432826855000,
"message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}"
},
{
"id": "3195310660696698337880902507980421114328961542429EXAMPLE",
"timestamp": 1432826855000,
"message": "{\"eventVersion\":\"1.03\",\"userIdentity\":{\"type\":\"Root\"}"
}
]
}
```
The key elements in this data structure are as follows:
**owner**
The AWS Account ID of the originating log data.
**logGroup**
The log group name of the originating log data.
**logStream**
The log stream name of the originating log data.
**subscriptionFilters**
The list of subscription filter names that matched with the originating log data.
**messageType**
Data messages use the "DATA\$1MESSAGE" type. Sometimes CloudWatch Logs may emit Amazon Kinesis Data Streams records with a "CONTROL\$1MESSAGE" type, mainly for checking if the destination is reachable.
**logEvents**
The actual log data, represented as an array of log event records. The ID property is a unique identifier for every log event.
# Modify destination membership at runtime
You might encounter situations where you have to add or remove membership of some users from a destination that you own. You can use the `put-destination-policy` command on your destination with a new access policy. In the following example, a previously added account **111111111111** is stopped from sending any more log data, and account **222222222222** is enabled.
1. Fetch the policy that is currently associated with the destination **testDestination** and make a note of the **AccessPolicy**:
```
aws logs describe-destinations \
--destination-name-prefix "testDestination"
{
"Destinations": [
{
"DestinationName": "testDestination",
"RoleArn": "arn:aws:iam::999999999999:role/CWLtoKinesisRole",
"DestinationArn": "arn:aws:logs:region:999999999999:destination:testDestination",
"TargetArn": "arn:aws:kinesis:region:999999999999:stream/RecipientStream",
"AccessPolicy": "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Sid\": \"\", \"Effect\": \"Allow\", \"Principal\": {\"AWS\": \"111111111111\"}, \"Action\": \"logs:PutSubscriptionFilter\", \"Resource\": \"arn:aws:logs:region:999999999999:destination:testDestination\"}] }"
}
]
}
```
1. Update the policy to reflect that account **111111111111** is stopped, and that account **222222222222** is enabled. Put this policy in the **\$1/NewAccessPolicy.json** file:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"AWS": "222222222222"
},
"Action": "logs:PutSubscriptionFilter",
"Resource": "arn:aws:logs:us-east-1:999999999999:destination:testDestination"
}
]
}
```
------
1. Call **PutDestinationPolicy** to associate the policy defined in the **NewAccessPolicy.json** file with the destination:
```
aws logs put-destination-policy \
--destination-name "testDestination" \
--access-policy file://~/NewAccessPolicy.json
```
This will eventually disable the log events from account ID **111111111111**. Log events from account ID **222222222222** start flowing to the destination as soon as the owner of account **222222222222** creates a subscription filter.