# Tagging Security Lake resources
A *tag* is an optional label that you can define and assign to AWS resources, including certain types of Amazon Security Lake resources. Tags can help you identify, categorize, and manage resources in different ways, such as by purpose, owner, environment, or other criteria. For example, you can use tags to apply policies, allocate costs, distinguish between resources, or identify resources that support certain compliance requirements or workflows.
You can assign tags to the following types of Security Lake resources: subscribers, and the data lake configuration for your AWS account in individual AWS Regions.
**Topics**
+ [Tagging fundamentals](tags-basics.md)
+ [Using tags in IAM policies](tags-iam.md)
+ [Adding tags to resources](tags-add.md)
+ [Editing tags for resources](tags-update.md)
+ [Removing tags from resources](tags-remove.md)
# Tagging fundamentals
A resource can have as many as 50 tags. Each tag consists of a required *tag key* and an optional *tag value*, both of which you define. A *tag key* is a general label that acts as a category for a more specific tag value. A *tag value* acts as a descriptor for a tag key.
For example, if you add subscribers to analyze security data from different environments (one set of subscribers for cloud data and another set for on-premises data), you might assign an `Environment` tag key to those subscribers. The associated tag value might be `Cloud` for subscribers that analyze data from AWS services, and `On-Premises` for the others.
As you define and assign tags to Amazon Security Lake resources, keep the following in mind:
+ Each resource can have a maximum of 50 tags.
+ For each resource, each tag key must be unique and it can have only one tag value.
+ Tag keys and values are case sensitive. As a best practice, we recommend that you define a strategy for capitalizing tags and implement that strategy consistently across your resources.
+ A tag key can have a maximum of 128 UTF-8 characters. A tag value can have a maximum of 256 UTF-8 characters. The characters can be letters, numbers, spaces, or the following symbols: \$1 . : / = \$1 - @
+ The `aws:` prefix is reserved for use by AWS. You can’t use it in any tag keys or values that you define. In addition, you can't change or remove tag keys or values that use this prefix. Tags that use this prefix don’t count against the quota of 50 tags per resource.
+ Any tags that you assign are available only for your AWS account and only in the AWS Region in which you assign them.
+ If you assign tags to a resource by using Security Lake, the tags are applied only to the resource that's stored directly in Security Lake in the applicable AWS Region. They aren't applied to any associated, supporting resources that Security Lake creates, uses, or maintains for you in other AWS services. For example, if you assign tags to your data lake, the tags are applied only to your data lake configuration in Security Lake for the specified Region. They aren't applied to the Amazon Simple Storage Service (Amazon S3) bucket that stores your log and event data. To also assign tags to an associated resource, you can use AWS Resource Groups or the AWS service that stores the resource—for example, Amazon S3 for an S3 bucket. Assigning tags to associated resources can help you identify supporting resources for your data lake.
+ If you delete a resource, any tags that are assigned to the resource are also deleted.
For additional restrictions, tips, and best practices, see [Tagging your AWS resources](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html) in the *Tagging AWS Resources User Guide*.
**Important**
Do not store confidential or other types of sensitive data in tags. Tags are accessible from many AWS services, including AWS Billing and Cost Management. They aren't intended to be used for sensitive data.
To add and manage tags for Security Lake resources, you can use the Security Lake console or the Security Lake API.
# Using tags in IAM policies
After you start tagging resources, you can define tag-based, resource-level permissions in AWS Identity and Access Management (IAM) policies. By using tags in this way, you can implement granular control of which users and roles in your AWS account have permission to create and tag resources, and which users and roles have permission to add, edit, and remove tags more generally. To control access based on tags, you can use [tag-related condition keys](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonsecuritylake.html#amazonsecuritylake-policy-keys) in the [Condition element](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) of IAM policies.
For example, you can create a policy that allows a user to have full access to all Amazon Security Lake resources, if the `Owner` tag for the resource specifies their username:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ModifyResourceIfOwner",
"Effect": "Allow",
"Action": "securitylake:*",
"Resource": "*",
"Condition": {
"StringEqualsIgnoreCase": {"aws:ResourceTag/Owner": "${aws:username}"}
}
}
]
}
```
------
If you define tag-based, resource-level permissions, the permissions take effect immediately. This means that your resources are more secure as soon as they're created, and you can quickly start enforcing the use of tags for new resources. You can also use resource-level permissions to control which tag keys and values can be associated with new and existing resources. For more information, see [Controlling access to AWS resources using tags](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html) in the *IAM User Guide*.
# Adding tags to Amazon Security Lake resources
To add tags to an Amazon Security Lake resource, you can use the Security Lake console or the Security Lake API.
**Important**
Adding tags to a resource can affect access to the resource. Before you add a tag to a resource, review any AWS Identity and Access Management (IAM) policies that might use tags to control access to resources.
------
#### [ Console ]
When you enable Security Lake for an AWS Region or create a subscriber, the Security Lake console provides options for adding tags to the resource—the data lake configuration for the Region or the subscriber. Follow the instructions on the console to add tags to the resource when you create the resource.
To add one or more tags to an existing resource by using the Security Lake console, follow these steps.
**To add a tag to a resource**
1. Open the Security Lake console at [https://console.aws.amazon.com/securitylake/](https://console.aws.amazon.com/securitylake/).
1. Depending on the type of resource that you want to add a tag to, do one of the following:
+ For a data lake configuration, choose **Regions** in the navigation pane. Then, in the **Regions** table, select the Region.
+ For a subscriber, choose **Subscribers** in the navigation pane. Then, in the **My subscribers** table, select the subscriber.
If the subscriber doesn't appear in the table, use the AWS Region selector in the upper-right corner of the page to select the Region where you created the subscriber. The table lists existing subscribers only for the current Region.
1. Choose **Edit**.
1. Expand the **Tags** section. This section lists all the tags that are currently assigned to the resource.
1. In the **Tags** section, choose **Add new tag**.
1. In the **Key** box, enter the tag key for the tag to add to the resource. Then, in the **Value** box, optionally enter a tag value for the key.
A tag key can contain as many as 128 characters. A tag value can contain as many as 256 characters. The characters can be letters, numbers, spaces, or the following symbols: \$1 . : / = \$1 - @
1. To add another tag to the resource, choose **Add new tag**, and then repeat the preceding step. You can assign as many as 50 tags to a resource.
1. When you finish adding tags, choose **Save**.
------
#### [ API ]
To create a resource and add one or more tags to it programmatically, use the appropriate `Create` operation for the type of resource that you want to create:
+ **Data lake configuration** – Use the [CreateDataLake](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_CreateDataLake.html) operation or, if you're using the AWS Command Line Interface (AWS CLI), run the [create-data-lake](https://docs.aws.amazon.com/cli/latest/reference/securitylake/create-data-lake.html) command.
+ **Subscriber** – Use the [CreateSubscriber](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_CreateSubscriber.html) operation or, if you're using the AWS CLI, run the [create-subscriber](https://docs.aws.amazon.com/cli/latest/reference/securitylake/create-subscriber.html) command.
In your request, use the `tags` parameter to specify the tag key (`key`) and optional tag value (`value`) for each tag to add to the resource. The `tags` parameter specifies an array of objects. Each object specifies a tag key and its associated tag value.
To add one or more tags to an existing resource, use the [TagResource](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_TagResource.html) operation of the Security Lake API or, if you're using the AWS CLI, run the [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/securitylake/tag-resource.html) command. In your request, specify the Amazon Resource Name (ARN) of the resource that you want to add a tag to. Use the `tags` parameter to specify the tag key (`key`) and optional tag value (`value`) for each tag to add. As is the case for `Create` operations and commands, the `tags` parameter specifies an array of objects, one object for each tag key and its associated tag value.
For example, the following AWS CLI command adds an `Environment` tag key with a `Cloud` tag value to the specified subscriber. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability.
```
$ aws securitylake tag-resource \
--resource-arn arn:aws:securitylake:us-east-1:123456789012:subscriber/1234abcd-12ab-34cd-56ef-1234567890ab \
--tags key=Environment,value=Cloud
```
Where:
+ `resource-arn` specifies the ARN of the subscriber to add a tag to.
+ `Environment` is the tag key of the tag to add to the subscriber.
+ `Cloud` is the tag value for the specified tag key (`Environment`).
In the following example, the command adds several tags to the subscriber.
```
$ aws securitylake tag-resource \
--resource-arn arn:aws:securitylake:us-east-1:123456789012:subscriber/1234abcd-12ab-34cd-56ef-1234567890ab \
--tags key=Environment,value=Cloud key=CostCenter,value=12345 key=Owner,value=jane-doe
```
For each object in a `tags` array, both the `key` and `value` arguments are required. However, the value for the `value` argument can be an empty string. If you don’t want to associate a tag value with a tag key, don't specify a value for the `value` argument. For example, the following command adds an `Owner` tag key with no associated tag value:
```
$ aws securitylake tag-resource \
--resource-arn arn:aws:securitylake:us-east-1:123456789012:subscriber/1234abcd-12ab-34cd-56ef-1234567890ab \
--tags key=Owner,value=
```
If a tagging operation succeeds, Security Lake returns an empty HTTP 200 response. Otherwise, Security Lake returns an HTTP 4*xx* or 500 response that indicates why the operation failed.
------
# Editing tags for Amazon Security Lake resources
To edit the tags (tag keys or tag values) for an Amazon Security Lake resource, you can use the Security Lake console or the Security Lake API.
**Important**
Editing the tags for a resource can affect access to the resource. Before you edit a tag key or value for a resource, review any AWS Identity and Access Management (IAM) policies that might use the tag to control access to resources.
------
#### [ Console ]
Follow these steps to edit a resource's tags by using the Security Lake console.
**To edit the tags for a resource**
1. Open the Security Lake console at [https://console.aws.amazon.com/securitylake/](https://console.aws.amazon.com/securitylake/).
1. Depending on the type of resource whose tags you want to edit, do one of the following:
+ For a data lake configuration, choose **Regions** in the navigation pane. Then, in the **Regions** table, select the Region.
+ For a subscriber, choose **Subscribers** in the navigation pane. Then, in the **My subscribers** table, select the subscriber.
If the subscriber doesn't appear in the table, use the AWS Region selector in the upper-right corner of the page to select the Region where you created the subscriber. The table lists existing subscribers only for the current Region.
1. Choose **Edit**.
1. Expand the **Tags** section. The **Tags** section lists all the tags that are currently assigned to the resource.
1. Do any of the following:
+ To add a tag value to an existing tag key, enter the value in the **Value** box next to the tag key.
+ To change an existing tag key, choose **Remove** next to the tag. Then choose **Add new tag**. In the **Key** box that appears, enter the new tag key. Optionally enter an associated tag value in the **Value** box.
+ To change an existing tag value, choose **X** in the **Value** box that contains the value. Then enter the new tag value in the **Value** box.
+ To remove an existing tag value, choose **X** in the **Value** box that contains the value.
+ To remove an existing tag (both the tag key and tag value), choose **Remove** next to the tag.
A resource can have as many as 50 tags. A tag key can contain as many as 128 characters. A tag value can contain as many as 256 characters. The characters can be letters, numbers, spaces, or the following symbols: \$1 . : / = \$1 - @
1. When you finish editing the tags, choose **Save**.
------
#### [ API ]
When you edit a tag for a resource programmatically, you overwrite the existing tag with new values. Therefore, the best way to edit a tag depends on whether you want to edit a tag key, a tag value, or both. To edit a tag key, [remove the current tag](tags-remove.md) and [add a new tag](tags-add.md).
To edit or remove only the tag value that's associated with a tag key, overwrite the existing value by using the [TagResource](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_TagResource.html) operation of the Security Lake API. If you're using the AWS Command Line Interface (AWS CLI), run the [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/securitylake/tag-resource.html) command. In your request, specify the Amazon Resource Name (ARN) of the resource whose tag value you want to edit or remove.
To edit a tag value, use the `tags` parameter to specify the tag key whose tag value you want to change. Also specify the new tag value for the key. For example, the following AWS CLI command changes the tag value from `Cloud` to `On-Premises` for the `Environment` tag key that's assigned to the specified subscriber. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability.
```
$ aws securitylake tag-resource \
--resource-arn arn:aws:securitylake:us-east-1:123456789012:subscriber/1234abcd-12ab-34cd-56ef-1234567890ab \
--tags key=Environment,value=On-Premises
```
Where:
+ `resource-arn` specifies the ARN of the subscriber.
+ `Environment` is the tag key that's associated with the tag value to change.
+ `On-Premises` is the new tag value for the specified tag key (`Environment`).
To remove a tag value from a tag key, don’t specify a value for the `value` argument of the key in the `tags` parameter. For example:
```
$ aws securitylake tag-resource \
--resource-arn arn:aws:securitylake:us-east-1:123456789012:subscriber/1234abcd-12ab-34cd-56ef-1234567890ab \
--tags key=Owner,value=
```
If the operation succeeds, Security Lake returns an empty HTTP 200 response. Otherwise, Security Lake returns an HTTP 4*xx* or 500 response that indicates why the operation failed.
------
## Reviewing tags for Amazon Security Lake resources
You can review the tags (both tag keys and tag values) for an Amazon Security Lake resource by using the Security Lake console or the Security Lake API.
------
#### [ Console ]
Follow these steps to review a resource's tags by using the Security Lake console.
**To review the tags for a resource**
1. Open the Security Lake console at [https://console.aws.amazon.com/securitylake/](https://console.aws.amazon.com/securitylake/).
1. Depending on the type of resource whose tags you want to review, do one of the following:
+ For a data lake configuration, choose **Regions** in the navigation pane. In the **Regions** table, select the Region, and then choose **Edit**. Then expand the **Tags** section.
+ For a subscriber, choose **Subscribers** in the navigation pane. Then, in the **My subscribers** table, choose the subscriber's name.
If the subscriber doesn't appear in the table, use the AWS Region selector in the upper-right corner of the page to select the Region where you created the subscriber. The table lists existing subscribers only for the current Region.
The **Tags** section lists all the tags that are currently assigned to the resource.
------
#### [ API ]
To retrieve and review the tags for an existing resource programmatically, use the [ListTagsForResource](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_ListTagsForResource.html) operation of the Security Lake API. In your request, use the `resourceArn` parameter to specify the Amazon Resource Name (ARN) of the resource.
If you're using the AWS Command Line Interface (AWS CLI), run the [list-tags-for-resource](https://docs.aws.amazon.com/cli/latest/reference/securitylake/list-tags-for-resource.html) command and use the `resource-arn` parameter to specify the ARN of the resource. For example:
```
$ aws securitylake list-tags-for-resource --resource-arn arn:aws:securitylake:us-east-1:123456789012:subscriber/1234abcd-12ab-34cd-56ef-1234567890ab
```
In the preceding example, *arn:aws:securitylake:us-east-1:123456789012:subscriber/1234abcd-12ab-34cd-56ef-1234567890ab* is the ARN of an existing subscriber.
If the operation succeeds, Security Lake returns a `tags` array. Each object in the array specifies a tag (both the tag key and tag value) that's currently assigned to the resource. For example:
```
{
"tags": [
{
"key": "Environment",
"value": "Cloud"
},
{
"key": "CostCenter",
"value": "12345"
},
{
"key": "Owner",
"value": ""
}
]
}
```
Where `Environment`, `CostCenter`, and `Owner` are the tag keys that are assigned to the resource. `Cloud` is the tag value that's associated with the `Environment` tag key. `12345` is the tag value that's associated with the `CostCenter` tag key. The `Owner` tag key doesn't have an associated tag value.
------
# Removing tags from Amazon Security Lake resources
To remove tags from an Amazon Security Lake resource, you can use the Security Lake console or the Security Lake API.
**Important**
Removing tags from a resource can affect access to the resource. Before you remove a tag, review any AWS Identity and Access Management (IAM) policies that might use the tag to control access to resources.
------
#### [ Console ]
Follow these steps to remove one or more tags from a resource by using the Security Lake console.
**To remove a tag from a resource**
1. Open the Security Lake console at [https://console.aws.amazon.com/securitylake/](https://console.aws.amazon.com/securitylake/).
1. Depending on the type of resource that you want to remove a tag from, do one of the following:
+ For a data lake configuration, choose **Regions** in the navigation pane. Then, in the **Regions** table, select the Region.
+ For a subscriber, choose **Subscribers** in the navigation pane. Then, in the **My subscribers** table, select the subscriber.
If the subscriber doesn't appear in the table, use the AWS Region selector in the upper-right corner of the page to select the Region where you created the subscriber. The table lists existing subscribers only for the current Region.
1. Choose **Edit**.
1. Expand the **Tags** section. The **Tags** section lists all the tags that are currently assigned to the resource.
1. Do any of the following:
+ To remove only the tag value for a tag, choose **X** in the **Value** box that contains the value to remove.
+ To remove both the tag key and tag value (as a pair) for a tag, choose **Remove** next to the tag to remove.
1. To remove additional tags from the resource, repeat the preceding step for each additional tag to remove.
1. When you finish removing tags, choose **Save**.
------
#### [ API ]
To remove one or more tags from a resource programmatically, use the [UntagResource](https://docs.aws.amazon.com/security-lake/latest/APIReference/API_UntagResource.html) operation of the Security Lake API. In your request, use the `resourceArn` parameter to specify the Amazon Resource Name (ARN) of the resource to remove a tag from. Use the `tagKeys` parameter to specify the tag key of the tag to remove. To remove multiple tags, append the `tagKeys` parameter and argument for each tag to remove, separated by an ampersand (&)—for example, `tagKeys=key1&tagKeys=key2`. To remove only a specific tag value (not a tag key) from a resource, [edit the tag](tags-update.md) instead of removing the tag.
If you're using the AWS Command Line Interface (AWS CLI), run the [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/securitylake/untag-resource.html) command to remove one or more tags from a resource. For the `resource-arn` parameter, specify the ARN of the resource to remove a tag from. Use the `tag-keys` parameter to specify the tag key of the tag to remove. For example, the following command removes the `Environment` tag (both the tag key and tag value) from the specified subscriber:
```
$ aws securitylake untag-resource \
--resource-arn arn:aws:securitylake:us-east-1:123456789012:subscriber/1234abcd-12ab-34cd-56ef-1234567890ab \
--tag-keys Environment
```
Where `resource-arn` specifies the ARN of the subscriber to remove a tag from, and `Environment` is the tag key of the tag to remove.
To remove multiple tags from a resource, add each additional tag key as an argument for the `tag-keys` parameter. For example:
```
$ aws securitylake untag-resource \
--resource-arn arn:aws:securitylake:us-east-1:123456789012:subscriber/1234abcd-12ab-34cd-56ef-1234567890ab \
--tag-keys Environment Owner
```
If the operation succeeds, Security Lake returns an empty HTTP 200 response. Otherwise, Security Lake returns an HTTP 4*xx* or 500 response that indicates why the operation failed.
------