# Managing data access for Security Lake subscribers
Subscribers with data access to source data in Amazon Security Lake are notified of new objects for the source as the data is written to the S3 bucket. By default, subscribers are notified about new objects through an HTTPS endpoint that they provide. Alternatively, subscribers can be notified about new objects by polling an Amazon Simple Queue Service (Amazon SQS) queue.
Subscribers are notified of new Amazon S3 objects for a source as the objects are written to the Security Lake data lake. Subscribers can directly access the S3 objects and receive notifications of new objects through a subscription endpoint or by polling an Amazon Simple Queue Service (Amazon SQS) queue. This subscription type is identified as `S3` in the `accessTypes` parameter of the [CreateSubscriber](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_CreateSubscriber.html) API.
**Topics**
+ [Prerequisites](prereqs-creating-subscriber.md)
+ [Creating a subscriber with data access](create-subscriber-data-access.md)
+ [Updating a data subscriber](subscriber-update.md)
+ [Removing a data subscriber](remove-data-access-subscriber.md)
# Prerequisites to create a subscriber with data access in Security Lake
You must complete the following prerequisites before you can create a subscriber with data access in Security Lake.
## Verify permissions
To verify your permissions, use IAM to review the IAM policies that are attached to your IAM identity. Then, compare the information in those policies to the following list of (permissions) actions that you must have to notify subscribers when new data is written to the data lake.
You will need permission to perform the following actions:
+ `iam:CreateRole`
+ `iam:DeleteRolePolicy`
+ `iam:GetRole`
+ `iam:PutRolePolicy`
+ `lakeformation:GrantPermissions`
+ `lakeformation:ListPermissions`
+ `lakeformation:RegisterResource`
+ `lakeformation:RevokePermissions`
+ `ram:GetResourceShareAssociations`
+ `ram:GetResourceShares`
+ `ram:UpdateResourceShare`
In addition to the preceding list, you also need permission to perform the following actions:
+ `events:CreateApiDestination`
+ `events:CreateConnection`
+ `events:DescribeRule`
+ `events:ListApiDestinations`
+ `events:ListConnections`
+ `events:PutRule`
+ `events:PutTargets`
+ `s3:GetBucketNotification`
+ `s3:PutBucketNotification`
+ `sqs:CreateQueue`
+ `sqs:DeleteQueue`
+ `sqs:GetQueueAttributes`
+ `sqs:GetQueueUrl`
+ `sqs:SetQueueAttributes`
## Get the subscriber's external ID
To create a subscriber, apart from the subscriber's AWS account ID, you will also need to get their *external ID*. The external ID is a unique identifier that the subscriber provides to you. Security Lake adds the external ID to the subscriber IAM role that it creates. You use the external ID when you create a subscriber in the Security Lake console, through the API, or AWS CLI.
For more information about external IDs, see [How to use an external ID when granting access to your AWS resources to a third party](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) in the *IAM User Guide*.
**Important**
If you plan to use the Security Lake console to add a subscriber, you can skip the next step and proceed to [Creating a subscriber with data access in Security Lake](create-subscriber-data-access.md). The Security Lake console offers a streamlined process for getting started, and creates all necessary IAM roles or uses existing roles on your behalf.
If you plan to use Security Lake API or AWS CLI to add a subscriber, continue with the next step to create an IAM role to invoke EventBridge API destinations.
## Create IAM role to invoke EventBridge API destinations (API and AWS CLI-only step)
If you're using Security Lake through API or AWS CLI, create a role in AWS Identity and Access Management (IAM) that grants Amazon EventBridge permissions to invoke API destinations and send object notifications to the correct HTTPS endpoints.
After creating this IAM role, you'll need the Amazon Resource Name (ARN) of the role in order to create the subscriber. This IAM role isn't necessary if the subscriber polls data from an Amazon Simple Queue Service (Amazon SQS) queue or directly queries data from AWS Lake Formation. For more information about this type of data access method (access type), see [Managing query access for Security Lake subscribers](subscriber-query-access.md).
Attach the following policy to your IAM role:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowInvokeApiDestination",
"Effect": "Allow",
"Action": [
"events:InvokeApiDestination"
],
"Resource": [
"arn:aws:events:us-east-1:123456789012:api-destination/AmazonSecurityLake*/*"
]
}
]
}
```
------
Attach the following trust policy to your IAM role to permit EventBridge to assume the role:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowEventBridgeToAssume",
"Effect": "Allow",
"Principal": {
"Service": "events.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Security Lake automatically creates an IAM role that permits the subscriber to read data from the data lake (or poll events from an Amazon SQS queue if that's the preferred method of notification). This role is protected with an AWS managed policy called [`AmazonSecurityLakePermissionsBoundary`](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonSecurityLakePermissionsBoundary).
# Creating a subscriber with data access in Security Lake
Choose one of the following access methods to create a subscriber with access to data in the current AWS Region.
------
#### [ Console ]
1. Open the Security Lake console at [https://console.aws.amazon.com/securitylake/](https://console.aws.amazon.com/securitylake/).
1. By using the AWS Region selector in the upper-right corner of the page, select the Region where you want to create the subscriber.
1. In the navigation pane, choose **Subscribers**.
1. On the **Subscribers** page, choose **Create subscriber**.
1. For **Subscriber details**, enter **Subscriber name** and an optional **Description**.
The **Region** is auto-populated as your currently selected AWS Region and can't be modified.
1. For **Log and event sources**, choose which sources the subscriber is authorized to consume.
1. For **Data access method**, choose **S3** to set up data access for the subscriber.
1. For **Subscriber credentials**, provide the subscriber's AWS account ID and [external ID](https://docs.aws.amazon.com//security-lake/latest/userguide/prereqs-creating-subscriber.html#subscriber-external-id).
1. (Optional) For **Notification details**, if you want Security Lake to create an Amazon SQS queue that the subscriber can poll for object notifications, select **SQS queue**. If you want Security Lake to send notifications through EventBridge to an HTTPS endpoint, select **Subscription endpoint**.
If you select **Subscription endpoint**, also do the following:
1. Enter the **Subscription endpoint**. Examples of valid endpoint formats include **http://example.com**. Optionally, you can also provide an **HTTPS key name** and **HTTPS key value**.
1. For **Service Access**, create a new IAM role or use an existing IAM role that gives EventBridge permission to invoke API destinations and send object notifications to the correct endpoints.
For information about creating a new IAM role, see [Create IAM role to invoke EventBridge API destinations](https://docs.aws.amazon.com//security-lake/latest/userguide/prereqs-creating-subscriber.html#iam-role-subscriber).
1. (Optional) For **Tags**, enter as many as 50 tags to assign to the subscriber.
A *tag* is a label that you can define and assign to certain types of AWS resources. Each tag consists of a required tag key and an optional tag value. Tags can help you identify, categorize, and manage resources in different ways. To learn more, see [Tagging Security Lake resources](tagging-resources.md).
1. Choose **Create**.
------
#### [ API ]
To create a subscriber with data access programmatically, use the [CreateSubscriber](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_CreateSubscriber.html) operation of the Security Lake API. If you're using the AWS Command Line Interface (AWS CLI), run the [create-subscriber](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/create-subscriber.html) command.
In your request, use these parameters to specify the following settings for the subscriber:
+ For `sources`, specify each source that you want the subscriber to access.
+ For `subscriberIdentity`, specify the AWS account ID and external ID that the subscriber will use to access source data.
+ For `subscriber-name`, specify the name of the subscriber.
+ For `accessTypes`, specify `S3`.
**Example 1**
The following example creates a subscriber with access to data in the current AWS Region for the specified subscriber identity for an AWS source.
```
$ aws securitylake create-subscriber \
--subscriber-identity {"accountID": 1293456789123,"externalId": 123456789012} \
--sources [{"awsLogSource": {"sourceName": VPC_FLOW, "sourceVersion": 2.0}}] \
--subscriber-name subscriber name \
--access-types S3
```
**Example 2**
The following example creates a subscriber with access to data in the current AWS Region for the specified subscriber identity for a custom source.
```
$ aws securitylake create-subscriber \
--subscriber-identity {"accountID": 1293456789123,"externalId": 123456789012} \
--sources [{"customLogSource": {"sourceName": custom-source-name, "sourceVersion": 2.0}}] \
--subscriber-name subscriber name
--access-types S3
```
The preceding examples are formatted for Linux, macOS, or Unix, and they use the backslash (\$1) line-continuation character to improve readability.
(Optional) After you create a subscriber, use the [CreateSubscriberNotification](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_CreateSubscriberNotification.html) operation to specify how to notify the subscriber when new data is written to the data lake for the sources that you want the subscriber to access. If you're using the AWS Command Line Interface (AWS CLI), run the [create-subscriber-notification](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/create-subscriber-notification.html) command.
+ To override the default notification method (HTTPS endpoint) and create an Amazon SQS queue, specify values for the `sqsNotificationConfiguration` parameters.
+ If you prefer notification with an HTTPS endpoint, specify values for the `httpsNotificationConfiguration` parameters.
+ For the `targetRoleArn` field, specify the ARN of the IAM role that you created to invoke EventBridge API destinations.
```
$ aws securitylake create-subscriber-notification \
--subscriber-id "12345ab8-1a34-1c34-1bd4-12345ab9012" \
--configuration httpsNotificationConfiguration={"targetRoleArn"="arn:aws:iam::XXX:role/service-role/RoleName", "endpoint"="https://account-management.$3.$2.securitylake.aws.dev/v1/datalake"}
```
To get the `subscriberID`, use the [ListSubscribers](https://docs.aws.amazon.com//security-lake/latest/APIReference/API_ListSubscribers.html) operation of the Security Lake API. If you're using the AWS Command Line Interface (AWS CLI), run the [list-subscriber](https://docs.aws.amazon.com/cli/latest/reference/securitylake/list-subscribers.html) command.
```
$ aws securitylake list-subscribers
```
------
To subsequently change the notification method (Amazon SQS queue or HTTPS endpoint) for the subscriber, use the [UpdateSubscriberNotification](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_UpdateSubscriberNotification.html) operation or, if you're using the AWS CLI, run the [update-subscriber-notification](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/update-subscriber-notification.html) command. You can also change the notification method by using the Security Lake console: select the subscriber on the **Subscribers** page, and then choose **Edit**.
## Sample object notification message
The following example shows the event notification in JSON structure format for the `CreateSubscriberNotification` operation.
```
{
"source": "aws.s3",
"time": "2021-11-12T00:00:00Z",
"account": "123456789012",
"region": "ca-central-1",
"resources": [
"arn:aws:s3:::amzn-s3-demo-bucket"
],
"detail": {
"bucket": {
"name": "amzn-s3-demo-bucket"
},
"object": {
"key": "example-key",
"size": 5,
"etag": "b57f9512698f4b09e608f4f2a65852e5"
},
"request-id": "N4N7GDK58NMKJ12R",
"requester": "securitylake.amazonaws.com"
}
}
```
# Updating a data subscriber in Security Lake
You can update a subscriber by changing the sources from which the subscriber consumes. You can also assign or edit the tags for a subscriber. A *tag* is a label that you can define and assign to certain types of AWS resources, including subscribers. To learn more, see [Tagging Security Lake resources](tagging-resources.md).
Choose one of the access methods, and follow these steps to define new sources for an existing subscription.
------
#### [ Console ]
1. Open the Security Lake console at [https://console.aws.amazon.com/securitylake/](https://console.aws.amazon.com/securitylake/).
1. In the navigation pane, choose **Subscribers**.
1. Select the subscriber.
1. Choose **Edit**, and then do any of the following:
+ To update the sources for the subscriber, enter the new settings in the **Log and event sources** section.
+ To assign or edit tags for the subscriber, change the tags as necessary in the **Tags** section.
1. When you finish, choose **Save**.
------
#### [ API ]
To update data access sources for a subscriber programmatically, use the [UpdateSubscriber](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_UpdateSubscriber.html) operation of the Security Lake API. If you're using the AWS Command Line Interface (AWS CLI), run the [update-subscriber](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/update-subscriber.html) command. In your request, use the `sources` parameters to specify each source that you want the subscriber to access.
```
$ aws securitylake update-subscriber --subscriber-id subscriber ID
```
For a list of subscribers associated with a specific AWS account or organization, use the [ListSubscribers](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_ListSubscribers.html) operation. If you're using the AWS Command Line Interface (AWS CLI), run the [list-subscribers](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/list-subscribers.html) command.
```
$ aws securitylake list-subscribers
```
To review the current settings for a particular subscriber, use the [GetSubscriber](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_GetSubscriber.html) operation. run the [get-subscriber](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/get-subscriber.html) command. Security Lake then returns the subscriber's name and description, external ID, and additional information. If you're using the AWS Command Line Interface (AWS CLI), run the [get-subscriber](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/get-subscriber.html) command.
To update the notification method for a subscriber, use the [UpdateSubscriberNotification](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_UpdateSubscriberNotification.html) operation. If you're using the AWS Command Line Interface (AWS CLI), run the [update-subscriber-notification](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/update-subscriber-notification.html) command. For example, you can specify a new HTTPS endpoint for the subscriber or switch from an HTTPS endpoint to an Amazon SQS queue.
------
# Removing a data subscriber from Security Lake
If you no longer want a subscriber to consume data from Security Lake, you can remove the subscriber by following these steps.
------
#### [ Console ]
1. Open the Security Lake console at [https://console.aws.amazon.com/securitylake/](https://console.aws.amazon.com/securitylake/).
1. In the navigation pane, choose **Subscribers**.
1. Select the subscriber that you want to remove.
1. Choose **Delete** and confirm the action. This will delete the subscriber and all the associated notification settings.
------
#### [ API ]
Based on your scenario, do one of the following:
+ To delete the subscriber and all associated notification settings, use the [DeleteSubscriber](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_DeleteSubscriber.html) operation of the Security Lake API. If you're using the AWS Command Line Interface (AWS CLI), run the [delete-subscriber](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/delete-subscriber.html) command.
+ To retain the subscriber but stop future notifications to the subscriber, use the [DeleteSubscriberNotification](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_DeleteSubscriberNotification.html) operation of the Security Lake API. If you're using the AWS Command Line Interface (AWS CLI), run the run the [delete-subscriber-notification](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/securitylake/delete-subscriber-notification.html) command.
------