# Management policies in AWS Organizations
Management policies enable you to centrally configure and manage AWS services and their features. How those policies affect the OUs and accounts that inherit them depends on the type of management policy you apply in AWS Organizations. Review the topics in this section to understand relevant terms and concepts about management policies.
**Topics**
+ [Prerequisites and permissions](orgs_manage_policies_prereqs.md)
+ [Understanding policy inheritance](orgs_manage_policies_inheritance_mgmt.md)
+ [Viewing effective policies](orgs_manage_policies_effective.md)
+ [Invalid policy alerts](invalid-policy-alerts.md)
+ [Declarative policies](orgs_manage_policies_declarative.md)
+ [Backup policies](orgs_manage_policies_backup.md)
+ [Tag policies](orgs_manage_policies_tag-policies.md)
+ [Chat applications policies](orgs_manage_policies_chatbot.md)
+ [AI services opt-out policies](orgs_manage_policies_ai-opt-out.md)
+ [Security Hub policies](orgs_manage_policies_security_hub.md)
+ [Amazon Bedrock policies](orgs_manage_policies_bedrock.md)
+ [Amazon Inspector policies](orgs_manage_policies_inspector.md)
+ [Upgrade rollout policies](orgs_manage_policies_upgrade_rollout.md)
+ [Amazon S3 policies](orgs_manage_policies_s3.md)
+ [AWS Shield Network Security Director policies](orgs_manage_policies_network_security_director.md)
# Prerequisites and permissions for management policies for AWS Organizations
This page describes the prerequisites and required permissions for management policies for AWS Organizations.
**Topics**
+ [Prerequisites for management policies](#manage-policies-prereqs-overview)
+ [Permissions for management policies](#manage-policies-permissions)
## Prerequisites for management policies
Using management policies for an organization requires the following:
+ Your organization must have [all features enabled](orgs_manage_org_support-all-features.md).
+ You must be signed in to your organization's management account or be a delegated administrator.
+ Your AWS Identity and Access Management (IAM) user or role must have the permissions that are listed in the following section.
## Permissions for management policies
The following example IAM policy provides permissions to use all aspects of management policies in an organization.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "OrganizationPolicies",
"Effect": "Allow",
"Action": [
"organizations:AttachPolicy",
"organizations:CreatePolicy",
"organizations:DeletePolicy",
"organizations:DescribeAccount",
"organizations:DescribeCreateAccountStatus",
"organizations:DescribeEffectivePolicy",
"organizations:DescribeOrganization",
"organizations:DescribeOrganizationalUnit",
"organizations:DescribePolicy",
"organizations:DetachPolicy",
"organizations:DisableAWSServiceAccess",
"organizations:DisablePolicyType",
"organizations:EnableAWSServiceAccess",
"organizations:EnablePolicyType",
"organizations:ListAccounts",
"organizations:ListAccountsForParent",
"organizations:ListAWSServiceAccessForOrganization",
"organizations:ListCreateAccountStatus",
"organizations:ListOrganizationalUnitsForParent",
"organizations:ListParents",
"organizations:ListPolicies",
"organizations:ListPoliciesForTarget",
"organizations:ListRoots",
"organizations:ListTargetsForPolicy",
"organizations:UpdatePolicy"
],
"Resource": "*"
}
]
}
```
------
For more information about IAM policies and permissions, see the [IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/).
# Understanding management policy inheritance
**Important**
The information in this section does ***not*** apply to authorization policies: service control policies (SCPs) and resource control policies (RCPs). For more information about how SCPs and RCPs work in an AWS Organizations hierarchy, see [SCP evaluation](orgs_manage_policies_scps_evaluation.md) and [RCP evaluation](orgs_manage_policies_rcps_evaluation.md).
You can attach management policies to organization entities (organization root, organizational unit (OU), or account) in your organization:
+ When you attach a management policy to the organization root, all OUs and accounts in the organization inherit that policy.
+ When you attach a management policy to a specific OU, accounts that are directly under that OU or any child OU inherit the policy.
+ When you attach a management policy to a specific account, it affects only that account.
Because you can attach management policies to multiple levels in the organization, accounts can inherit multiple policies.
This following topics explain how parent policies and child policies are processed into the effective policy for an account.
**Topics**
+ [Terminology](inheritance-terminology.md)
+ [Management policy types](syntax-inheritance.md)
+ [Inheritance operators](policy-operators.md)
+ [Inheritance examples](inheritance-examples.md)
# Inheritance terminology
This topic uses the following terms when discussing management policy inheritance.
**Policy inheritance**
The interaction of policies at differing levels of an organization, moving from the top-level root of the organization, down through the organizational unit (OU) hierarchy to individual accounts.
You can attach policies to the organization root, OUs, individual accounts, and to any combination of these organization entities. Policy inheritance refers to management policies that are attached to the organization root or to an OU. All accounts that are members of the organization root or OU where a management policy is attached *inherit* that policy.
For example, when management policies are attached to the organization root, all accounts in the organization inherit that policy. That's because all accounts in an organization are always under the organization root. When you attach a policy to a specific OU, accounts that are directly under that OU or any child OU inherit that policy. Because you can attach policies to multiple levels in the organization, accounts might inherit multiple policy documents for a single policy type.
**Parent policies**
Policies that are attached higher in the organizational tree than policies that are attached to entities lower in the tree.
For example, if you attach management policy A to the organization root, it's just a policy. If you also attach policy B to an OU under that root, policy A is the parent policy of Policy B. Policy B is the child policy of Policy A. Policy A and policy B merge to create the effective tag policy for accounts in the OU.
**Child policies**
Policies that are attached at a lower level in the organization tree than the parent policy.
**Effective policies**
The final, single policy document that specifies the rules that apply to an account. The effective policy is the aggregation of any policies the account inherits, plus any policy that is directly attached to the account. For more information, see [Viewing effective management policies](orgs_manage_policies_effective.md).
**Inheritance operators**
Operators that control how inherited policies merge into a single effective policy. These operators are considered an advanced feature. Experienced policy authors can use them to limit what changes a child policy can make and how settings in policies merge. For more information, see [Inheritance operators](policy-operators.md).
# Policy syntax and inheritance for management policy types
Exactly how policies affect the OUs and accounts that inherit them depends on the type of management policy you choose. Management policy types include:
+ [Declarative policies](orgs_manage_policies_declarative.md)
+ [Backup policies](orgs_manage_policies_backup.md)
+ [Tag policies](orgs_manage_policies_tag-policies.md)
+ [Chat applications policies](orgs_manage_policies_chatbot.md)
+ [AI services opt-out policies](orgs_manage_policies_ai-opt-out.md)
+ [Security Hub policies](orgs_manage_policies_security_hub.md)
+ [Bedrock policies](orgs_manage_policies_bedrock.md)
+ [Inspector policies](orgs_manage_policies_inspector.md)
+ [Upgrade rollout policies](orgs_manage_policies_upgrade_rollout.md)
+ [S3 policies](orgs_manage_policies_s3.md)
+ [AWS Shield Network Security Director policies](orgs_manage_policies_network_security_director.md)
The syntax for management policy types includes *[Inheritance operators](policy-operators.md)*, which enable you to specify with fine granularity what elements from the parent policies are applied and what elements can be overridden or modified when inherited by child OUs and accounts.
The *effective policy* is the set of rules that are inherited from the organization root and OUs along with those directly attached to the account. The effective policy specifies the final set of rules that apply to the account. You can view the effective policy for an account that includes the effect of all of the inheritance operators in the policies applied. For more information, see [Viewing effective management policies](orgs_manage_policies_effective.md).
# Inheritance operators
Inheritance operators control how inherited policies and account policies merge into the account's effective policy. These operators include value-setting operators and child control operators.
When you use the visual editor in the AWS Organizations console, you can use only the `@@assign` operator. Other operators are considered an advanced feature. To use the other operators, you must manually author the JSON policy. Experienced policy authors can use inheritance operators to control what values are applied to the effective policy and limit what changes child policies can make.
For information about how policy inheritance works in an organization, see [Inheritance examples](inheritance-examples.md).
## Value-setting operators
You can use the following value-setting operators to control how your policy interacts with its parent policies:
+ `@@assign` – **Overwrites** any inherited policy settings with the specified settings. If the specified setting isn't inherited, this operator adds it to the effective policy. This operator can apply to any policy setting of any type.
+ For single-valued settings, this operator replaces the inherited value with the specified value.
+ For multi-valued settings (JSON arrays), this operator removes any inherited values and replaces them with the values specified by this policy.
+ `@@append` – **Adds** the specified settings (without removing any) to the inherited ones. If the specified setting isn't inherited, this operator adds it to the effective policy. You can use this operator with only multi-valued settings.
+ This operator adds the specified values to any values in the inherited array.
+ `@@remove` – **Removes** the specified inherited settings from the effective policy, if they exist. You can use this operator with only multi-valued settings.
+ This operator removes only the specified values from the array of values inherited from the parent policies. Other values can continue to exist in the array and can be inherited by child policies.
## Child control operators
Using child control operators is optional. You can use the `@@operators_allowed_for_child_policies` operator to control which value-setting operators child policies can use. You can allow all operators, some specific operators, or no operators. By default, all operators (`@@all`) are allowed.
+ `"@@operators_allowed_for_child_policies"`:`["@@all"]` – Child OUs and accounts can use any operator in policies. By default, all operators are allowed in child policies.
+ `"@@operators_allowed_for_child_policies"`:`["@@assign", "@@append", "@@remove"]` – Child OUs and accounts can use only the specified operators in child policies. You can specify one or more value-setting operators in this child control operator.
+ `"@@operators_allowed_for_child_policies"`:`["@@none"]` – Child OUs and accounts can't use operators in policies. You can use this operator to effectively lock in the values that are defined in a parent policy so that child policies can't add, append, or remove those values.
**Note**
If an inherited child control operator limits the use of an operator, you can't reverse that rule in a child policy. If you include child control operators in a parent policy, they limit the value-setting operators in all child policies.
# Inheritance examples
These examples show how policy inheritance works by showing how parent and child tag policies are merged into an effective tag policy for an account.
The examples assume that you have the organization structure shown in the following diagram.
![\[An organization with one root, two OUs, and several accounts.\]](http://docs.aws.amazon.com/organizations/latest/userguide/images/org-structure-inheritance.png)
**Topics**
+ [Example 1: Allow child policies to overwrite *only* tag values](#example-assign-operator)
+ [Example 2: Append new values to inherited tags](#example-append-operator)
+ [Example 3: Remove values from inherited tags](#example-remove-operator)
+ [Example 4: Restrict changes to child policies](#example-restrict-child)
+ [Example 5: Conflicts with child control operators](#multiple-same-node-operators)
+ [Example 6: Conflicts with appending values at same hierarchy level](#multiple-same-node-values)
## Example 1: Allow child policies to overwrite *only* tag values
The following tag policy defines the `CostCenter` tag key and two acceptable values, `Development` and `Support`. If you attach it to the organization root, the tag policy is in effect for all accounts in the organization.
**Policy A – Organization root tag policy**
```
{
"tags": {
"costcenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"tag_value": {
"@@assign": [
"Development",
"Support"
]
}
}
}
}
```
Assume that you want users in OU1 to use a different tag value for a key, and you want to enforce the tag policy for specific resource types. Because policy A doesn't specify which child control operators are allowed, all operators are allowed. You can use the `@@assign` operator and create a tag policy like the following to attach to OU1.
**Policy B – OU1 tag policy**
```
{
"tags": {
"costcenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"tag_value": {
"@@assign": [
"Sandbox"
]
},
"enforced_for": {
"@@assign": [
"redshift:*",
"dynamodb:table"
]
}
}
}
}
```
Specifying the `@@assign` operator for the tag does the following when policy A and policy B merge to form the *effective tag policy* for an account:
+ Policy B overwrites the two tag values that were specified in the parent policy, policy A. The result is that `Sandbox` is the only compliant value for the `CostCenter` tag key.
+ The addition of `enforced_for` specifies that the `CostCenter` tag *must* be the specified tag value on all Amazon Redshift resources and Amazon DynamoDB tables.
As shown in the diagram, OU1 includes two accounts: 111111111111 and 222222222222.
**Resultant effective tag policy for accounts 111111111111 and 222222222222**
**Note**
You can't directly use the contents of a displayed effective policy as the contents of a new policy. The syntax doesn't include the operators needed to control merging with other child and parent policies. The display of an effective policy is intended only for understanding the results of the merger.
```
{
"tags": {
"costcenter": {
"tag_key": "CostCenter",
"tag_value": [
"Sandbox"
],
"enforced_for": [
"redshift:*",
"dynamodb:table"
]
}
}
}
```
## Example 2: Append new values to inherited tags
There may be cases where you want all accounts in your organization to specify a tag key with a short list of acceptable values. For accounts in one OU, you may want to allow an additional value that only those accounts can specify when creating resources. This example specifies how to do that by using the `@@append` operator. The `@@append` operator is an advanced feature.
Like example 1, this example starts with policy A for the organization root tag policy.
**Policy A – Organization root tag policy**
```
{
"tags": {
"costcenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"tag_value": {
"@@assign": [
"Development",
"Support"
]
}
}
}
}
```
For this example, attach policy C to OU2. The difference in this example is that using the `@@append` operator in policy C *adds to*, rather than overwrites, the list of acceptable values and the `enforced_for` rule.
**Policy C – OU2 tag policy for appending values**
```
{
"tags": {
"costcenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"tag_value": {
"@@append": [
"Marketing"
]
},
"enforced_for": {
"@@append": [
"redshift:*",
"dynamodb:table"
]
}
}
}
}
```
Attaching policy C to OU2 has the following effects when policy A and policy C merge to form the effective tag policy for an account:
+ Because policy C includes the `@@append` operator, it allows for *adding to*, not overwriting, the list of acceptable tag values that are specified in Policy A.
+ As in policy B, the addition of `enforced_for` specifies that the `CostCenter` tag must be used as the specified tag value on all Amazon Redshift resources and Amazon DynamoDB tables. Overwriting (`@@assign`) and adding (`@@append`) have the same effect if the parent policy doesn't include a child control operator that restricts what a child policy can specify.
As shown in the diagram, OU2 includes one account: 999999999999. Policy A and policy C merge to create the effective tag policy for account 999999999999.
**Effective tag policy for account 999999999999**
**Note**
You can't directly use the contents of a displayed effective policy as the contents of a new policy. The syntax doesn't include the operators needed to control merging with other child and parent policies. The display of an effective policy is intended only for understanding the results of the merger.
```
{
"tags": {
"costcenter": {
"tag_key": "CostCenter",
"tag_value": [
"Development",
"Support",
"Marketing"
],
"enforced_for": [
"redshift:*",
"dynamodb:table"
]
}
}
}
```
## Example 3: Remove values from inherited tags
There may be cases where the tag policy that is attached to the organization defines more tag values than you want an account to use. This example explains how to revise a tag policy using the `@@remove` operator. The `@@remove` is an advanced feature.
Like the other examples, this example starts with policy A for the organization root tag policy.
**Policy A – Organization root tag policy**
```
{
"tags": {
"costcenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"tag_value": {
"@@assign": [
"Development",
"Support"
]
}
}
}
}
```
For this example, attach policy D to account 999999999999.
**Policy D – Account 999999999999 tag policy for removing values**
```
{
"tags": {
"costcenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"tag_value": {
"@@remove": [
"Development",
"Marketing"
],
"enforced_for": {
"@@remove": [
"redshift:*",
"dynamodb:table"
]
}
}
}
}
}
```
Attaching policy D to account 999999999999 has the following effects when policy A, policy C, and policy D merge to form the effective tag policy:
+ Assuming you performed all of the previous examples, policies B, C, and C are child policies of A. Policy B is only attached to OU1, so it has no effect on account 9999999999999.
+ For account 9999999999999, the only acceptable value for the `CostCenter` tag key is `Support`.
+ Compliance is not enforced for the `CostCenter` tag key.
**New effective tag policy for account 999999999999**
**Note**
You can't directly use the contents of a displayed effective policy as the contents of a new policy. The syntax doesn't include the operators needed to control merging with other child and parent policies. The display of an effective policy is intended only for understanding the results of the merger.
```
{
"tags": {
"costcenter": {
"tag_key": "CostCenter",
"tag_value": [
"Support"
]
}
}
}
```
If you later add more accounts to OU2, their effective tag policies would be different than for account 999999999999. That's because the more restrictive policy D is only attached at the account level, and not to the OU.
## Example 4: Restrict changes to child policies
There may be cases where you want to restrict changes in child policies. This example explains how to do that using child control operators.
This example starts with a new organization root tag policy and assumes that tag policies aren't yet attached to organization entities.
**Policy E – Organization root tag policy for restricting changes in child policies **
```
{
"tags": {
"project": {
"tag_key": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "Project"
},
"tag_value": {
"@@operators_allowed_for_child_policies": ["@@append"],
"@@assign": [
"Maintenance",
"Escalations"
]
}
}
}
}
```
When you attach policy E to the organization root, the policy prevents child policies from changing the `Project` tag key. However, child policies can overwrite or append tag values.
Assume you then attach the following policy F to an OU.
**Policy F – OU tag policy**
```
{
"tags": {
"project": {
"tag_key": {
"@@assign": "PROJECT"
},
"tag_value": {
"@@append": [
"Escalations - research"
]
}
}
}
}
```
Merging policy E and policy F have the following effects on the OU's accounts:
+ Policy F is a child policy to Policy E.
+ Policy F attempts to change the case treatment, but it can't. That's because policy E includes the `"@@operators_allowed_for_child_policies": ["@@none"]` operator for the tag key.
+ However, policy F can append tag values for the key. That's because policy E includes `"@@operators_allowed_for_child_policies": ["@@append"]` for the tag value.
**Effective policy for accounts in the OU**
**Note**
You can't directly use the contents of a displayed effective policy as the contents of a new policy. The syntax doesn't include the operators needed to control merging with other child and parent policies. The display of an effective policy is intended only for understanding the results of the merger.
```
{
"tags": {
"project": {
"tag_key": "Project",
"tag_value": [
"Maintenance",
"Escalations",
"Escalations - research"
]
}
}
}
```
## Example 5: Conflicts with child control operators
Child control operators can exist in tag policies that are attached at the same level in the organization hierarchy. When that happens, the intersection of the allowed operators is used when the policies merge to form the effective policy for accounts.
Assume policy G and policy H are attached to the organization root.
**Policy G – Organization root tag policy 1**
```
{
"tags": {
"project": {
"tag_value": {
"@@operators_allowed_for_child_policies": ["@@append"],
"@@assign": [
"Maintenance"
]
}
}
}
}
```
**Policy H – Organization root tag policy 2**
```
{
"tags": {
"project": {
"tag_value": {
"@@operators_allowed_for_child_policies": ["@@append", "@@remove"]
}
}
}
}
```
In this example, one policy at the organization root defines that the values for the tag key can only be appended to. The other policy attached to the organization root allows child policies to both append and remove values. The intersection of these two permissions is used for child policies. The result is that child policies can append values, but not remove values. Therefore, the child policy can append a value to the list of tag values but can't remove the `Maintenance` value.
## Example 6: Conflicts with appending values at same hierarchy level
You can attach multiple tag policies to each organization entity. When you do this, the tag policies that are attached to the same organization entity might include conflicting information. Policies are evaluated based on the order in which they were attached to the organization entity. To change which policy is evaluated first, you can detach a policy and then reattach it.
Assume policy J is attached to the organization root first, and then policy K is attached to the organization root.
**Policy J – First tag policy attached to the organization root**
```
{
"tags": {
"project": {
"tag_key": {
"@@assign": "PROJECT"
},
"tag_value": {
"@@append": ["Maintenance"]
}
}
}
}
```
**Policy K – Second tag policy attached to the organization root**
```
{
"tags": {
"project": {
"tag_key": {
"@@assign": "project"
}
}
}
}
```
In this example, the tag key `PROJECT` is used in the effective tag policy because the policy that defined it was attached to the organization root first.
**Policy JK – Effective tag policy for account**
The effective policy for the account is as follows.
**Note**
You can't directly use the contents of a displayed effective policy as the contents of a new policy. The syntax doesn't include the operators needed to control merging with other child and parent policies. The display of an effective policy is intended only for understanding the results of the merger.
```
{
"tags": {
"project": {
"tag_key": "PROJECT",
"tag_value": [
"Maintenance"
]
}
}
}
```
# Viewing effective management policies
Determine the effective management policy for an account in your organization.
## What is an effective management policy?
The *effective policy* specifies the final rules that apply to an AWS account for a management policy type. It is the aggregation for a management policy that the account inherits, plus any policies for that management policy type that are directly attached to the account. When you attach a management policy to the organization's root, it applies to all accounts in your organization. When you attach a management policy to an organiztional unit (OU), it applies to all accounts and OUs that belong to the OU. When you attach a management policy directly to an account, it applies only to that one AWS account.
For information about how policies are combined into the final effective policy, see [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md).
**Backup policy example**
The backup policy attached to the organization root might specify that all accounts in the organization back up all Amazon DynamoDB tables with a default backup frequency of once per week. A separate backup policy attached directly to one member account with critical information in a table can override the frequency with a value of once per day. The combination of these backup policies comprises the effective backup policy. This effective backup policy is determined for each account in the organization individually. In this example, the result is that all accounts in the organization back up their DynamoDB tables once per week, with the exception of one account that backs up its tables daily.
**Tag policy example**
The tag policy attached to the organization root might define a `CostCenter` tag with four compliant values. A separate tag policy attached to the account may restrict the `CostCenter` key to only two of the four compliant values. The combination of these tag policies comprises the effective tag policy. The result is that only two of the four compliant tag values defined in the organization root tag policy are compliant for the account.
**Chat applications policy example**
Amazon Q Developer in chat applications will reevaluate any previously created Amazon Q Developer in chat applications configurations against the effective chat applications policies and deny any previously allowed actions if they are consistent with the permitted settings and guardrails in the effective policy. The effective policy for a member account defines the permitted settings and guardrails. For example, if a chat applications policy with deny access for public Slack channels is applied to a member account, then the existing Amazon Q Developer in chat applications configurations for public Slack channels in the member account will be disabled. Amazon Q Developer in chat applications will not deliver notifications and channel members will not be able to run any tasks in the blocked channel. The Amazon Q Developer in chat applications console will mark the affected channels as disabled with an appropriate error messaging next to it.
**AI services opt-out example**
The AI services opt-out policy attached to the organization root might specify that all accounts in the organization opt out of content use by all AWS machine learning services. A separate AI services opt-out policy attached directly to one member account specifies that it opts in to content use for only Amazon Rekognition. The combination of these AI services opt-out policies comprises the effective AI services opt-out policy. The result is that all accounts in the organization are opted out of all AWS services, with the exception of one account that opts in to Amazon Rekognition.
## How to view the effective management policy
You can view the effective policy of a management policy type for an account from the AWS Management Console, AWS API, or AWS Command Line Interface.
**Minimum permissions**
To view the effective policy of a management policy type for an account, you must have permission to run the following actions:
`organizations:DescribeEffectivePolicy`
`organizations:DescribeOrganization` – required only when using the Organizations console
------
#### [ AWS Management Console ]
**To view the effective policy of a management policy type for an account**
1. Sign in to the [AWS Organizations console](https://console.aws.amazon.com/organizations/v2). You must sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization’s management account.
1. On the **[AWS accounts](https://console.aws.amazon.com/organizations/v2/home/accounts)** page, choose the name of the account for which you want to view the effective policy. You might have to expand OUs (choose the ![\[Gray cloud icon representing cloud computing or storage services.\]](http://docs.aws.amazon.com/organizations/latest/userguide/images/console-expand.png)) to find the account that you want.
1. On the **Policies** tab, choose the management policy type for which you want to view the effective policy.
1. Choose **View the effective policy for this AWS account**.
The console displays the effective policy applied to the specified account.
**Note**
You can't copy and paste an effective policy and use it as the JSON for another policy without significant changes. Policy documents must include the [inheritance operators](policy-operators.md) that specify how each setting is merged into the final effective policy.
------
#### [ AWS CLI & AWS SDKs ]
**To view the effective policy of a management policy type for an account**
You can use one of the following to view the effective policy:
+ AWS CLI: [describe-effective-policy](https://docs.aws.amazon.com/cli/latest/reference/organizations/describe-effective-policy.html)
The following example shows the effective AI services opt-out policy for an account.
```
$ aws organizations describe-effective-policy \
--policy-type AISERVICES_OPT_OUT_POLICY \
--target-id 123456789012
{
"EffectivePolicy": {
"PolicyContent": "{\"services\":{\"comprehend\":{\"opt_out_policy\":\"optOut\"}, ....TRUNCATED FOR BREVITY.... "opt_out_policy\":\"optIn\"}}}",
"LastUpdatedTimestamp": "2020-12-09T12:58:53.548000-08:00",
"TargetId": "123456789012",
"PolicyType": "AISERVICES_OPT_OUT_POLICY"
}
}
```
+ AWS SDKs: [DescribeEffectivePolicy](https://docs.aws.amazon.com/organizations/latest/APIReference/API_DescribeEffectivePolicy.html)
------
For information about situations in which an effective policy could become invalid, see [Viewing invalid policy alerts](https://docs.aws.amazon.com//organizations/latest/userguide/invalid-policy-alerts.html).
# About invalid effective policy alerts
*Invalid policy alerts* let you know about invalid effective policies and provide mechanisms (APIs) to identify accounts with invalid policies. AWS Organizations notifies you asynchronously when one of your accounts has an invalid effective policy. The notification appears as a banner in the AWS Organizations console page, and it is recorded as an AWS CloudTrail event.
## Detect invalid effective management policies in your organization
There are several ways in which you can view invalid effective management policies in your organization: from the AWS Management Console, AWS API, AWS Command Line Interface (CLI), or as an AWS CloudTrail event.
**Minimum permissions**
To find the information related to invalid effective policies of a management policy type in your organization, you must have permission to run the following actions:
`organizations:ListAccountsWithInvalidEffectivePolicy`
`organizations:ListEffectivePolicyValidationErrors`
`organizations:ListRoots` - required only when using the Organizations console
------
#### [ AWS Management Console ]
**To view invalid effective management policies from the console**
1. Sign in to the [AWS Organizations console](https://console.aws.amazon.com/organizations/v2). You must sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization’s management account.
1. On the **[AWS accounts](https://console.aws.amazon.com/organizations/v2/home/accounts)** page page, if your organization has invalid effective policies, a warning banner is displayed at the top of the page.
1. In the banner, click on **View detected issues** to view the list of all accounts in your organization that have invalid effective policies.
1. For each account in the list, select **View issues** to get more information on errors for each account shown under the **Effective policy issues** sections on this page.
------
#### [ AWS CLI & AWS SDKs ]
**To view the effective policy of a management policy type for an account**
The following commands help you view accounts with invalid effective policies
+ AWS CLI: [list-accounts-with-invalid-effective-policy](https://docs.aws.amazon.com/cli/latest/reference/organizations/list-accounts-with-invalid-effective-policy.html)
+ AWS SDKs: [ListAccountsWithInvalidEffectivePolicy](https://docs.aws.amazon.com/organizations/latest/APIReference/API_ListAccountsWithInvalidEffectivePolicy.html)
**The following commands help you view effective policy errors on an account**
+ AWS CLI: [list-effective-policy-validation-errors](https://docs.aws.amazon.com/cli/latest/reference/organizations/list-effective-policy-validation-errors.html)
+ AWS SDKs: [ListEffectivePolicyValidationErrors](https://docs.aws.amazon.com/organizations/latest/APIReference/API_ListEffectivePolicyValidationErrors.html)
------
**AWS CloudTrail**
You can use AWS CloudTrail events to monitor when accounts in your organizations have invalid effective management policies and when the policies are fixed. For more information, see *Effective policy examples* in [Understanding AWS Organizations log file entries](https://docs.aws.amazon.com//organizations/latest/userguide/orgs_cloudtrail-integration.html#understanding-service-name-entries).
If you receive an invalid effective policy notification, you can navigate through the AWS Organizations console or call these APIs from your management or delegated administrator account to find more details about the status of specific accounts and policies:
+ `ListAccountsWithInvalidEffectivePolicy` – Returns a list of accounts in the organization that have invalid effective policies of a specified type.
+ `ListEffectivePolicyValidationErrors` – Returns a list of validation errors for a specified account and management policy type. The validation errors contain details, including the error code, error description, and contributing policies that made the effective policy invalid.
## When an effective management policy might be considered invalid
Effective policies on an account can become invalid if they violate the constraints defined for the particular policy type. For example, a policy might be missing a required parameter in the final effective policy or exceed certain quotas defined for the policy type.
**Backup policy example**
Suppose that you create a backup policy with nine backup rules and attach it to the root of your organization. Later, you create another backup policy for the same backup plan – with two more rules – and attach it to any account in the organization. In that situation, there's an invalid effective policy on the account. It is invalid because the aggregation of the two policies defines 11 rules for the backup plan. The limit is 10 backup rules in a plan.
**Warning**
If any account in the organization has an invalid effective policy, that account will not receive effective policy updates for the particular policy type. It continues with the last applied valid effective policy for the account, unless all the errors are fixed.
**Examples of possible errors for effective policies**
+ `ELEMENTS_TOO_MANY` – Occurs when a particular attribute in an effective policy exceeds the allowed limit, such as when more than 10 rules are given for a backup plan.
+ `ELEMENTS_TOO_FEW` – Occurs when a particular attribute in an effective policy does not meet the minimum limit, such as when no region is defined for a backup plan.
+ `KEY_REQUIRED` – Occurs when a required configuration is missing in the effective policy, such as when a backup plan is missing a backup rule.
AWS Organizations validates effective policies before applying them to the accounts in your organization. This auditing process is especially beneficial if you have a large organization structure, and if your organization's policies are managed by more than one team.
# Declarative policies
Declarative policies allow you to centrally declare and enforce your desired configuration for a given AWS service at scale across an organization. Once attached, the configuration is always maintained when the service adds new features or APIs. Use declarative policies to prevent noncompliant actions. For example, you can block public internet access to Amazon VPC resources across your organization.
The key benefits of using declarative policies are:
+ **Ease of use**: You can enforce the baseline configuration for an AWS service with a few selections in the AWS Organizations and AWS Control Tower consoles or with a few commands using the AWS CLI & AWS SDKs.
+ **Set once and forget**: The baseline configuration for an AWS service is always maintained, even when the service introduces new features or APIs. The baseline configuration is also maintained when new accounts are added to an organization or when new principals and resources are created.
+ **Transparency**: The account status report allows you to review the current status of all attributes supported by declarative policies for the accounts in scope. You can also create customizable error messages, which can help administrators redirect end users to internal wiki pages or provide a descriptive message that can help end users understand why an action failed.
For a full list of supported AWS services and attributes, see [Supported AWS services and attributes](#orgs_manage_policies_declarative-supported-controls).
**Topics**
+ [How declarative policies work](#orgs_manage_policies_declarative-how-work)
+ [Custom error messages](#orgs_manage_policies_declarative-custom-message)
+ [Account status report](#orgs_manage_policies_declarative-account-status-report)
+ [Supported services](#orgs_manage_policies_declarative-supported-controls)
+ [Getting started](orgs_manage_policies-declarative_getting-started.md)
+ [Best practices](orgs_manage_policies_declarative_best-practices.md)
+ [Generating the account status report](orgs_manage_policies_declarative_status-report.md)
+ [Declarative policy syntax and examples](orgs_manage_policies_declarative_syntax.md)
## How declarative policies work
Declarative policies are enforced in the service's control plane, which is an important distinction from [authorization policies such as service control policies (SCPs) and resource control policies (RCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_authorization_policies.html). While authorization policies regulate access to APIs, declarative policies are applied directly at the service level to enforce durable intent. This ensures that the baseline configuration is always enforced, even when new features or APIs are introduced by the service.
The following table helps illustrate this distinction and provides some use cases.
****
| | Service control policies | Resource control policies | Declarative policies |
| --- | --- | --- | --- |
| Why? | To centrally define and enforce consistent access controls on principals (such as IAM users and IAM roles) at scale. | To centrally define and enforce consistent access controls on resources at scale | To centrally define and enforce the baseline configuration for AWS services at scale. |
| How? | By controlling the maximum available access permissions of principals at an API level. | By controlling the maximum available access permissions for resources at an API level. | By enforcing the desired configuration of an AWS service without using API actions. |
| Governs service-linked roles? | No | No | Yes |
| Feedback mechanism | Non-customizable access denied SCP error. | Non-customizable access denied RCP error. | Customizable error message. For more information, see [Custom error messages for declarative policies](#orgs_manage_policies_declarative-custom-message). |
| Example policy | [Deny member accounts from leaving the organization](https://github.com/aws-samples/service-control-policy-examples/blob/main/Privileged-access-controls/Deny-member-accounts-from-leaving-your-AWS-organization.json) | [Restrict access to only HTTPS connections to your resources](https://github.com/aws-samples/resource-control-policy-examples/blob/main/Restrict-resource-access-patterns/Restrict-access-to-only-HTTPS-connections-to-your-resources.json) | [Allowed Images Settings](orgs_manage_policies_declarative_syntax.md#declarative-policy-ec2-ami-allowed-images) |
After you have [created](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_policies_create.html#create-declarative-policy-procedure) and [attached](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_policies_attach.html) a declarative policy, it is applied and enforced across your organization. Declarative policies can be applied to an entire organization, organizational units (OUs), or accounts. Accounts joining an organization will automatically inherit the declarative policy in the organization. For more information, see [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md).
The *effective policy* is the set of rules that are inherited from the organization root and OUs along with those directly attached to the account. The effective policy specifies the final set of rules that apply to the account. For more information, see [Viewing effective management policies](orgs_manage_policies_effective.md).
If a declarative policy is [detached](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_policies_detach.html), the attribute state will roll back to its previous state before the declarative policy was attached.
## Custom error messages for declarative policies
Declarative policies allow you to create custom error messages. For example, if an API operation fails due to a declarative policy, you can set the error message or provide a custom URL, such as a link to an internal wiki or a link to a message that describes the failure. If you do not specify a custom error message, AWS Organizations provides the following default error message: `Example: This action is denied due to an organizational policy in effect`.
You can also audit the process of creating declarative policies, updating declarative policies, and deleting declarative policies with AWS CloudTrail. CloudTrail can flag API operation failures due to declarative policies. For more information, see [Logging and monitoring](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_security_incident-response.html).
**Important**
Do not include *personally identifiable information (PII)* or other sensitive information in a custom error message. PII includes general information that can be used to identify or locate an individual. It covers records such as financial, medical, educational, or employment. PII examples include addresses, bank account numbers, and phone numbers.
## Account status report for declarative policies
The *account status report* allows you to review the current status of all attributes supported by declarative policies for the accounts in scope. You can choose the accounts and organizational units (OUs) to include in the report scope, or choose an entire organization by selecting the root.
This report helps you assess readiness by providing a Region breakdown and if the current state of an attribute is *uniform across accounts* (through the `numberOfMatchedAccounts`) or *inconsistent* (through the `numberOfUnmatchedAccounts`). You can also see the *most frequent value*, which is the configuration value that is most frequently observed for the attribute.
In Figure 1, there is a generated account status report, which shows uniformity across accounts for the following attributes: VPC Block Public Access and Image Block Public Access. This means that, for each attribute, all the accounts in scope have the same configuration for that attribute.
The generated account status report shows inconsistent accounts for the following attributes: Allowed Images Settings, Instance Metadata defaults, Serial Console Access, and Snapshot Block Public Access. In this example, each attribute with an inconsistent account is due to there being one account with a different configuration value.
If there is a most frequent value, that is displayed in its respective column. For more detailed information of what each attribute controls, see [Declarative policy syntax and example policies](orgs_manage_policies_declarative_syntax.md).
You can also expand an attribute to see a Region breakdown. In this example, Image Block Public Access is expanded and in each Region, you can see that there is also uniformity across accounts.
The choice to attach a declarative policy for enforcing a baseline configuration depends on your specific use case. Use the account status report to help you assess your readiness before attaching a declarative policy.
For more information, see [Generating the account status report](orgs_manage_policies_declarative_status-report.md).
![\[Example account status report with uniformity across accounts for VPC Block Public Access and Image Block Public Access\]](http://docs.aws.amazon.com/organizations/latest/userguide/images/declarative-status-report.png)
*Figure 1: Example account status report with uniformity across accounts for VPC Block Public Access and Image Block Public Access.*
## Supported AWS services and attributes
### Supported attributes for declarative policies for EC2
The following table displays the attributes supported for Amazon EC2 related services.
**Declarative policies for EC2**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html)
# Getting started with declarative policies
Follow these steps to get started using declarative policies.
1. [Learn about the permissions you must have to perform declarative policy tasks](orgs_manage_policies_prereqs.md).
1. [Enable declarative policies for your organization](enable-policy-type.md).
**Note**
**Enabling trust access is required**
You must enable trusted access for the service where the declarative policy will enforce a baseline configuration. This creates a read-only service-linked role that is used to generate the account status report of what the existing configuration is for accounts across your organization.
**Using the console**
If you use the Organizations console, this step is a part of the process for enabling declarative policies.
**Using the AWS CLI**
If you use the AWS CLI, there are two separate APIs:
[EnablePolicyType](https://docs.aws.amazon.com/organizations/latest/APIReference/API_EnablePolicyType.html), which you use to enable declarative policies.
[EnableAWSServiceAccess](https://docs.aws.amazon.com/organizations/latest/APIReference/API_EnableAWSServiceAccess.html), which you use to enable trusted access.
For more information on how to enable trusted access for a specific service with the AWS CLI see, [AWS services that you can use with AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_integrate_services_list.html).
1. [Run the account status report](orgs_manage_policies_declarative_status-report.md).
1. [Create a declarative policy](orgs_policies_create.md).
1. [Attach the declarative policy to your organization's root, OU, or account](orgs_policies_attach.md).
1. [View the combined effective declarative policy that applies to an account](orgs_manage_policies_effective.md).
For all of these steps, you sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account.
**Other information**
+ [Learn declarative policy syntax and see example policies](orgs_manage_policies_declarative_syntax.md)
# Best practices for using declarative policies
AWS recommends the following best practices for using declarative policies.
## Leverage readiness assessments
Use the declarative policy *account status report* to assess the current status of all attributes supported by declarative policies for the accounts in scope. You can choose the accounts and organizational units (OUs) to include in the report scope, or choose an entire organization by selecting the root.
This report helps you assess readiness by providing a Region breakdown and if the current state of an attribute is *uniform across accounts* (through the `numberOfMatchedAccounts`) or *inconsistent* (through the `numberOfUnmatchedAccounts`). You can also see the *most frequent value*, which is the configuration value that is most frequently observed for the attribute.
The choice to attach a declarative policy for enforcing a baseline configuration depends on your specific use case.
For more information and an illustrative example, see [Account status report for declarative policies](orgs_manage_policies_declarative.md#orgs_manage_policies_declarative-account-status-report).
## Start small and then scale
To simplify debugging, start with a test policy. Validate the behavior and impact of each change before making the next change. This approach reduces the number of variables you have to account for when an error or unexpected result occurs.
For example, you can start with a test policy attached to a single account in a noncritical test environment. After you have confirmed that it works to your specifications, you can then incrementally move the policy up the organization structure to more accounts and more organizational units (OUs).
## Establish review processes
Implement processes to monitor for new declarative attributes, evaluate policy exceptions, and make adjustments to maintain alignment with your organizational security and operational requirements.
## Validate changes using `DescribeEffectivePolicy`
After you make a change to a declarative policy, check the effective policies for representative accounts below the level where you made the change. You can [view the effective policy by using the AWS Management Console](orgs_manage_policies_effective.md), or by using the [DescribeEffectivePolicy](https://docs.aws.amazon.com/organizations/latest/APIReference/API_DescribeEffectivePolicy.html) API operation or one of its AWS CLI or AWS SDK variants. Ensure that the change you made had the intended impact on the effective policy.
## Communicate and train
Ensure your organizations understand the purpose and impact of your declarative policies. Provide clear guidance on the expected behaviors and how to handle failures due to policy enforcement.
# Generating the account status report for declarative policies
The *account status report* allows you to review the current status of all attributes supported by declarative policies for the accounts in scope. You can choose the accounts and organizational units (OUs) to include in the report scope, or choose an entire organization by selecting the root.
This report helps you assess readiness by providing a Region breakdown and if the current state of an attribute is *uniform across accounts* (through the `numberOfMatchedAccounts`) or *inconsistent* (through the `numberOfUnmatchedAccounts`). You can also see the *most frequent value*, which is the configuration value that is most frequently observed for the attribute.
The choice to attach a declarative policy for enforcing a baseline configuration depends on your specific use case.
For more information and an illustrative example, see [Account status report for declarative policies](orgs_manage_policies_declarative.md#orgs_manage_policies_declarative-account-status-report).
## Prerequisites
Before you can generate an account status report, you must perform the following steps
1. The `StartDeclarativePoliciesReport` API can only be called by the management account or delegated administrators for an organization.
1. To run reports from a delegated administrator account, the account must be registered as a delegated administrator for the EC2 service.
1. You must have an S3 bucket before generating the report (create a new one or use an existing one), it must be in the same Region in which the request is made, and it must have an appropriate S3 bucket policy. For a sample S3 policy, see *Sample Amazon S3 policy* under [Examples ](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StartDeclarativePoliciesReport.html#API_StartDeclarativePoliciesReport_Examples) in the *Amazon EC2 API Reference*
1. You must enable trusted access for the service where the declarative policy will enforce a baseline configuration. This creates a read-only service-linked role that is used to generate the account status report of what the existing configuration is for accounts across your organization.
**Using the console**
For the Organizations console, this step is a part of the process for enabling declarative policies.
**Using the AWS CLI**
For the AWS CLI, use the [EnableAWSServiceAccess](https://docs.aws.amazon.com/organizations/latest/APIReference/API_EnableAWSServiceAccess.html) API.
For more information on how to enable trusted access for a specific service with the AWS CLI see, [AWS services that you can use with AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_integrate_services_list.html).
1. Only one report per organization can be generated at a time. Attempting to generate a report while another is in progress will result in an error.
## Access the compliance status report
**Minimum permissions**
To generate a compliance status report, you need permission to run the following actions:
`ec2:StartDeclarativePoliciesReport`
`ec2:DescribeDeclarativePoliciesReports`
`ec2:GetDeclarativePoliciesReportSummary`
`ec2:CancelDeclarativePoliciesReport`
`organizations:DescribeAccount`
`organizations:DescribeOrganization`
`organizations:DescribeOrganizationalUnit`
`organizations:ListAccounts`
`organizations:ListDelegatedAdministrators`
`organizations:ListAWSServiceAccessForOrganization`
`s3:PutObject`
**Note**
If your Amazon S3 bucket uses SSE-KMS encryption, you must also include the `kms:GenerateDataKey` permission in the policy.
------
#### [ AWS Management Console ]
Use the following procedure to generate an account status report.
**To generate an account status report**
1. Sign in to the [AWS Organizations console](https://console.aws.amazon.com/organizations/v2). You must sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization’s management account.
1. On the **Policies** page, choose **Declarative policies for EC2**.
1. On the **Declarative policies for EC2** page, choose **View account status report** from the **Actions** dropdown menu.
1. On the **View account status report** page, choose **Generate status report**.
1. In the **Organizational structure** widget, specify which organizational units (OUs) you want to include in the report.
1. Choose **Submit**.
------
#### [ AWS CLI & AWS SDKs ]
**To generate an account status report**
Use the following operations to generate a compliance status report, check on its status, and view the report:
+ `ec2:start-declarative-policies-report`: Generates an account status report. The report is generated asynchronously, and can take several hours to complete. For more information, see [StartDeclarativePoliciesReport](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_StartDeclarativePoliciesReport.html) in the *Amazon EC2 API Reference*.
+ `ec2:describe-declarative-policies-report`: Describes the metadata of an account status report, including the state of the report. For more information, see [DescribeDeclarativePoliciesReports](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeDeclarativePoliciesReports.html) in the *Amazon EC2 API Reference*.
+ `ec2:get-declarative-policies-report-summary`: Retrieves a summary of the account status report. For more information, see [GetDeclarativePoliciesReportSummary](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_GetDeclarativePoliciesReportSummary.html) in the *Amazon EC2 API Reference*.
+ `ec2:cancel-declarative-policies-report`: Cancels the generation of an account status report. For more information, see [CancelDeclarativePoliciesReport](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CancelDeclarativePoliciesReport.html) in the *Amazon EC2 API Reference*.
Before generating a report, grant the EC2 declarative policies principal access to the Amazon S3 bucket where the report will be stored. To do this, attach the following policy to the bucket. Replace `amzn-s3-demo-bucket` with your actual Amazon S3 bucket name, and `identity_ARN` with the IAM identity used to call the `StartDeclarativePoliciesReport` API.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "DeclarativePoliciesReportDelivery",
"Effect": "Allow",
"Principal": {
"AWS": "identity_ARN"
},
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*",
"Condition": {
"StringEquals": {
"aws:CalledViaLast": "organizations.amazonaws.com"
}
}
}
]
}
```
------
------
# Declarative policy syntax and examples
This page describes declarative policy syntax and provides examples.
## Considerations
+ When you configure a service attribute using a declarative policy, it might impact multiple APIs. Any noncompliant actions will fail.
+ Account administrators will not be able to modify the value of the service attribute at the individual account level.
## Syntax for declarative policies
A declarative policy is a plaintext file that is structured according to the rules of [JSON](http://json.org). The syntax for declarative policies follows the syntax for all management policy types. For a complete discussion of that syntax, see [Policy syntax and inheritance for management policy types](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_inheritance_mgmt.html). This topic focuses on applying that general syntax to the specific requirements of the declarative policy type.
The following example shows basic declarative policy syntax:
```
{
"ec2_attributes": {
"exception_message": {
"@@assign": "Your custom error message.https://myURL"
}
}
}
```
+ The `ec2_attributes` field key name. Declarative policies always start with a fixed key name for the given AWS service. It's the top line in the example policy above. Currently declarative policies only supported Amazon EC2 related services.
+ Under `ec2_attributes`, you can use `exception_message` to set a custom error message. For more information, see [Custom error messages for declarative policies](orgs_manage_policies_declarative.md#orgs_manage_policies_declarative-custom-message).
+ Under `ec2_attributes`, you can insert one or more of the supported declarative policies. For those schemas, see [Supported declarative policies](#declarative-policy-examples).
## Supported declarative policies
The following are the AWS services and attributes that declarative policies support. In some of the following examples, the JSON whitespace formatting might be compressed to save space.
+ VPC Block Public Access
+ Serial Console Access
+ Image Block Public Access
+ Allowed Images Settings
+ Instance Metadata
+ Snapshot Block Public Access
------
#### [ VPC Block Public Access ]
**Policy effect**
Controls if resources in Amazon VPCs and subnets can reach the internet through internet gateways (IGWs). For more information, see [Configuration for internet access](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-igw-internet-access.html) in the *Amazon Virtual Private Cloud User Guide*.
**Policy contents**
```
{
"ec2_attributes": {
"vpc_block_public_access": {
"internet_gateway_block": {
"mode": {
"@@assign": "block_ingress"
},
"exclusions_allowed": {
"@@assign": "enabled"
}
}
}
}
}
```
The following are the available fields for this attribute:
+ `"internet_gateway"`:
+ `"mode"`:
+ `"off"`: VPC BPA is not enabled.
+ `"block_ingress"`: All internet traffic to the VPCs (except for VPCs or subnets which are excluded) is blocked. Only traffic to and from NAT gateways and egress-only internet gateways is allowed because these gateways only allow outbound connections to be established.
+ `"block_bidirectional"`: All traffic to and from internet gateways and egress-only internet gateways (except for excluded VPCs and subnets) is blocked.
+ `"exclusions_allowed"`: An exclusion is a mode that can be applied to a single VPC or subnet that exempts it from the account’s VPC BPA mode and will allow bidirectional or egress-only access.
+ `"enabled"`: Exclusions can be created by the account.
+ `"disabled"`: Exclusions cannot be created by the account.
**Note**
You can use the attribute to configure if exclusions are allowed, but you cannot create exclusions with this attribute itself. To create exclusions, you must create them in the account that owns the VPC. For more information about creating VPC BPA exclusions, see [Create and delete exclusions](https://docs.aws.amazon.com//vpc/latest/userguide/security-vpc-bpa.html#security-vpc-bpa-exclusions) in the *Amazon VPC User Guide*.
**Considerations**
If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:
+ `ModifyVpcBlockPublicAccessOptions`
+ `CreateVpcBlockPublicAccessExclusion`
+ `ModifyVpcBlockPublicAccessExclusion`
------
#### [ Serial Console Access ]
**Policy effect**
Controls if the EC2 serial console is accessible. For more information about the EC2 serial console, see [EC2 Serial Console](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-serial-console.html) in the *Amazon Elastic Compute Cloud User Guide*.
**Policy contents**
```
{
"ec2_attributes": {
"serial_console_access": {
"status": {
"@@assign": "enabled"
}
}
}
}
```
The following are the available fields for this attribute:
+ `"status"`:
+ `"enabled"`: EC2 serial console access is allowed.
+ `"disabled"`: EC2 serial console access is blocked.
**Considerations**
If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:
+ `EnableSerialConsoleAccess`
+ `DisableSerialConsoleAccess`
------
#### [ Image Block Public Access ]
**Policy effect**
Controls if Amazon Machine Images (AMIs) are publicly sharable. For more information about AMIs, see [Amazon Machine Images (AMIs)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) in the *Amazon Elastic Compute Cloud User Guide*.
**Policy contents**
```
{
"ec2_attributes": {
"image_block_public_access": {
"state": {
"@@assign": "block_new_sharing"
}
}
}
}
```
The following are the available fields for this attribute:
+ `"state"`:
+ `"unblocked"`: No restrictions on the public sharing of AMIs.
+ `"block_new_sharing"`: Blocks new public sharing of AMIs. AMIs that were already publicly shared remain publicly available.
**Considerations**
If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:
+ `EnableImageBlockPublicAccess`
+ `DisableImageBlockPublicAccess`
------
#### [ Allowed Images Settings ]
**Policy effect**
Controls the discovery and use of Amazon Machine Images (AMI) in Amazon EC2 with Allowed AMIs. For more information about AMIs, see [Control the discovery and use of AMIs in Amazon EC2 with Allowed AMIs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-allowed-amis.html) in the *Amazon Elastic Compute Cloud User Guide*.
**Policy contents**
The following are the available fields for this attribute:
```
{
"ec2_attributes": {
"allowed_images_settings": {
"state": {
"@@assign": "enabled"
},
"image_criteria": {
"criteria_1": {
"allowed_image_providers": {
"@@append": [
"amazon"
]
}
}
}
}
}
}
```
+ `"state"`:
+ `"enabled"`: The attribute is active and enforced.
+ `"disabled"`: The attribute is inactive and not enforced.
+ `"audit_mode"`: The attribute is in audit mode. This means it will identify noncompliant images but not block their use.
+ `"image_criteria"`: A list of criteria. Support up to 10 criteria with the name from criteria\$11 to criteria\$110
+ `"allowed_image_providers"`: A comma-separated list of 12 digit account IDs or owner alias of amazon, aws\$1marketplace, aws\$1backup\$1vault.
+ `"image_names"`: The names of the allowed images. Names can include wildcards (? and \$1). Length: 1–128 characters. With ?, the minimum is 3 characters.
+ `"marketplace_product_codes"`: The AWS Marketplace product codes for allowed images. Length: 1-25 characters Valid characters: Letters (A–Z, a–z) and numbers (0–9)
+ `"creation_date_condition"`: The maximum age for allowed images.
+ `"maximum_days_since_created"`: The maximum number of days that have elapsed since the image was created. Valid Range: Minimum value of 0. Maximum value of 2147483647.
+ `"deprecation_time_condition"`: The maximum period since deprecation for allowed images.
+ `"maximum_days_since_deprecated"`: The maximum number of days that have elapsed since the image was deprecated. Valid Range: Minimum value of 0. Maximum value of 2147483647.
**Considerations**
If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:
+ `EnableAllowedImagesSettings`
+ `ReplaceImageCriteriaInAllowedImagesSettings`
+ `DisableAllowedImagesSettings`
------
#### [ Instance Metadata ]
**Policy effect**
Controls IMDS defaults and IMDSv2 enforcement for all new EC2 instance launches. For more information about IMDS defaults and IMDSv2 enforcement, see [Use instance metadata to manage your EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) in the *Amazon EC2 User Guide*.
**Policy contents**
The following are the available fields for this attribute:
```
{
"ec2_attributes": {
"instance_metadata_defaults": {
"http_tokens": {
"@@assign": "required"
},
"http_put_response_hop_limit": {
"@@assign": "4"
},
"http_endpoint": {
"@@assign": "enabled"
},
"instance_metadata_tags": {
"@@assign": "enabled"
},
"http_tokens_enforced": {
"@@assign": "enabled"
}
}
}
}
```
+ `"http_tokens"`:
+ `"no_preference"`: Other defaults apply. For example, AMI defaults if applicable.
+ `"required"`: IMDSv2 must be used. IMDSv1 is not allowed.
+ `"optional"`: Both IMDSv1 and IMDSv2 are allowed.
**Note**
**Metadata version**
Before setting `http_tokens` to `required` (IMDSv2 must be used), make sure that none of your instances are making IMDSv1 calls. For more information, see [Step 1: Identify instances with IMDSv2=optional and audit IMDSv1 usage](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-metadata-transition-to-version-2.html#path-step-1) in the *Amazon EC2 User Guide*.
+ `"http_put_response_hop_limit"`:
+ `"Integer"`: Integer value from -1 to 64, representing the maximum number of hops the metadata token can travel. To indicate no preference, specify -1.
**Note**
**Hop limit**
If `http_tokens` is set to `required`, it is recommended to set `http_put_response_hop_limit` to a minimum of 2. For more information, see [Instance metadata access considerations](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html#imds-considerations) in the *Amazon Elastic Compute Cloud User Guide*.
+ `"http_endpoint"`:
+ `"no_preference"`: Other defaults apply. For example, AMI defaults if applicable.
+ `"enabled"`: The instance metadata service endpoint is accessible.
+ `"disabled"`: The instance metadata service endpoint is not accessible.
+ `"instance_metadata_tags"`:
+ `"no_preference"`: Other defaults apply. For example, AMI defaults if applicable.
+ `"enabled"`: Instance tags can be accessed from instance metadata.
+ `"disabled"`: Instance tags cannot be accessed from instance metadata.
+ `"http_tokens_enforced":`
+ `"no_preference"`: Other defaults apply. For example, AMI defaults if applicable.
+ `"enabled"`: IMDSv2 must be used. Attempts to launch an IMDSv1 instance or to enable IMDSv1 on existing instances will fail.
+ `"disabled"`: Both IMDSv1 and IMDSv2 are allowed.
**Warning**
**IMDSv2 enforcement**
Enabling IMDSv2 enforcement while allowing IMDSv1 and IMDSv2 (token optional) will cause launch failures, unless IMDSv1 is explicitly disabled, either through launch parameters or AMI defaults. For more information, see [Launching an IMDSv1-enabled instance fails](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/troubleshooting-launch.html#launching-an-imdsv1-enabled-instance-fails) in the *Amazon EC2 User Guide*.
------
#### [ Snapshot Block Public Access ]
**Policy effect**
Controls if Amazon EBS snapshots are publicly accessible. For more information about EBS snapshots, see [Amazon EBS snapshots](https://docs.aws.amazon.com/ebs/latest/userguide/ebs-snapshots.html) in the *Amazon Elastic Block Store User Guide*.
**Policy contents**
```
{
"ec2_attributes": {
"snapshot_block_public_access": {
"state": {
"@@assign": "block_new_sharing"
}
}
}
}
```
The following are the available fields for this attribute:
+ `"state"`:
+ `"block_all_sharing"`: Blocks all public sharing of snapshots. Snapshots that were already publicly shared are treated as private and are no longer publicly available.
+ `"block_new_sharing"`: Blocks new public sharing of snapshots. Snapshots that were already publicly shared remain publicly available.
+ `"unblocked"`: No restrictions on the public sharing of snapshots.
**Considerations**
If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:
+ `EnableSnapshotBlockPublicAccess`
+ `DisableSnapshotBlockPublicAccess`
------
# Backup policies
Backup policies allow you to centrally manage and apply backup plans to the AWS resources across an organization's accounts.
[AWS Backup](https://docs.aws.amazon.com/aws-backup/latest/devguide/) enables you to create [backup plans](https://docs.aws.amazon.com/aws-backup/latest/devguide/about-backup-plans.html) that define how to back up your AWS resources. The rules in the plan include a variety of settings, such as the backup frequency, the time window during which the backup occurs, the AWS Region containing the resources to back up and the vault in which to store the backup. You can then apply a backup plan to groups of AWS resources identified by using tags. You must also identify an AWS Identity and Access Management (IAM) role that grants AWS Backup permission to perform the backup operation on your behalf.
Backup policies in AWS Organizations combine all of those pieces into [JSON](https://json.org) text documents. You can attach a backup policy to any of the elements in your organization's structure, such as the root, organizational units (OUs), and individual accounts. Organizations applies inheritance rules to combine the policies in the organization's root, any parent OUs, or attached to the account. This results in an [effective backup policy](orgs_manage_policies_effective.md) for each account. This effective policy instructs AWS Backup how to automatically back up your AWS resources.
## How backup policies work
Backup policies give you granular control over backing up your resources at whatever level your organization requires. For example, you can specify in a policy attached to the organization's root that all Amazon DynamoDB tables must be backed up. That policy can include a default backup frequency. You can then attach a backup policy to OUs that override the backup frequency according to the requirements of each OU. For example, the `Developers` OU might specify a backup frequency of once per week, while the `Production` OU specifies once per day.
You can create partial backup policies that individually include only part of the required information to successfully back up your resources. You can attach these policies to different parts of the organization tree, such as the root or a parent OU, with the intention of those partial policies being inherited by lower-level OUs and accounts. When Organizations combines all of the policies for an account by using inheritance rules, the resulting effective policy must have all the required elements. Otherwise, AWS Backup considers the policy not valid and does not back up the affected resources.
**Important**
AWS Backup can only perform a successful backup when it is invoked by a *complete* effective policy that has all of the required elements.
Although a partial policy strategy as described earlier can work, if an effective policy for an account is incomplete, it results in errors or resources that are not successfully backed up. As an alternate strategy, consider requiring that all backup policies be complete and valid by themselves. Use default values supplied by policies attached higher in the hierarchy, and override them where needed in child policies by including [inheritance child control operators](policy-operators.md).
The effective backup plan for each AWS account in the organization appears in the AWS Backup console as an immutable plan for that account. You can view it, but not change it. You can, however, add or remove backup plan tags using [TagResource ](https://docs.aws.amazon.com/aws-backup/latest/devguide/API_TagResource.html) and [UntagResource ](https://docs.aws.amazon.com/aws-backup/latest/devguide/API_UntagResource.html) APIs.
When AWS Backup begins a backup based on a policy-created backup plan, you can see the status of the backup job in the AWS Backup console. A user in a member account can see the status and any errors for the backup jobs in that member account. If you also enable trusted service access with AWS Backup, a user in the organization's management account can see the status and errors for all backup jobs in the organization. For more information, see [Enabling cross-account management](https://docs.aws.amazon.com/aws-backup/latest/devguide/manage-cross-account.html#enable-cross-account) in the *AWS Backup Developer Guide*.
# Getting started with backup policies
Follow these steps to get started using backup policies.
1. [Learn about the permissions you must have to perform backup policy tasks](orgs_manage_policies_prereqs.md).
1. [Learn about some best practices we recommend when using backup policies](orgs_manage_policies_backup_best-practices.md).
1. [Enable backup policies for your organization](enable-policy-type.md).
1. [Create a backup policy](orgs_policies_create.md#create-backup-policy-procedure).
1. [Attach the backup policy to your organization's root, OU, or account](orgs_policies_attach.md).
1. [View the combined effective backup policy that applies to an account](orgs_manage_policies_effective.md).
For all of these steps, you sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account.
**Other information**
+ [Learn backup policy syntax and see example policies](orgs_manage_policies_backup_syntax.md)
# Best practices for using backup policies
AWS recommends the following best practices for using backup policies.
## Decide on a backup policy strategy
You can create backup policies in incomplete pieces that are inherited and merged to make a complete policy for each member account. If you do this, you risk ending up with an effective policy that is not complete if you make a change at one level without carefully considering the change's impact on all accounts below that level. To prevent this, we recommend that you instead ensure that the backup policies you implement at all levels are complete by themselves. Treat the parent policies as default policies that can be overridden by settings specified in child policies. That way, even if a child policy doesn't exist, the inherited policy is complete and uses the default values. You can control which settings can be added to, changed, or removed by child policies by using the [child control inheritance operators](policy-operators.md#child-control-operators).
## Validate changes to your backup policies checking using `GetEffectivePolicy`
After you make a change to a backup policy, check the effective policies for representative accounts below the level where you made the change. You can [view the effective policy by using the AWS Management Console](orgs_manage_policies_effective.md), or by using the [GetEffectivePolicy](https://docs.aws.amazon.com/organizations/latest/APIReference/API_GetEffectivePolicy.html) API operation or one of its AWS CLI or AWS SDK variants. Ensure that the change you made had the intended impact on the effective policy.
## Start simply and make small changes
To simplify debugging, start with simple policies and make changes one item at a time. Validate the behavior and impact of each change before making the next change. This approach reduces the number of variables you have to account for when an error or unexpected result does happen.
## Store copies of your backups in other AWS Regions and accounts in your organization
To improve your disaster recovery position, you can store copies of your backups.
+ **A different region** – If you store copies of the backup in additional AWS Regions, you help protect the backup against accidental corruption or deletion in the original Region. Use the `copy_actions` section of the policy to specify a vault in one or more Regions of the same account in which the backup plan runs. To do this, identify the account by using the `$account` variable when you specify the ARN of the backup vault in which to store the copy of the backup. The `$account `variable is automatically replaced at run time with the account ID in which the backup policy is running.
+ **A different account** – If you store copies of the backup in additional AWS accounts, you add a security barrier that helps protect against a malicious actor who compromises one of your accounts. Use the `copy_actions` section of the policy to specify a vault in one or more accounts in your organization, separate from the account in which the backup plan runs . To do this, identify the account by using its actual account ID number when you specify the ARN of the backup vault in which to store the copy of the backup.
## Limit the number of plans per policy
Policies that contain multiple plans are more complicated to troubleshoot because of the larger number of outputs that must all be validated. Instead, have each policy contain one and only one backup plan to simplify debugging and troubleshooting. You can then add additional policies with other plans to meet other requirements. This approach helps keep any issues with a plan isolated to one policy, and it prevents those issues from complicating the troubleshooting of issues with other policies and their plans.
## Use stack sets to create the required backup vaults and IAM roles
Use AWS CloudFormation stack sets integration with Organizations to automatically create the required backup vaults and AWS Identity and Access Management (IAM) roles in each of the member accounts in your organization. You can create a stack set that includes the resources you want automatically available in every AWS account in your organization. This approach enables you to run your backup plans with assurance that the dependencies are already met. For more information, see [Create a Stack Set with Self-Managed Permissions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-getting-started-create.html#create-stack-set-service-managed-permissions) in the *AWS CloudFormation User Guide*.
## Check your results by reviewing the first backup created in each account
When you make a change to a policy, check the next backup created after that change to ensure the change had the desired impact. This step goes beyond looking at the effective policy and ensures that AWS Backup interprets your policies and implements the backup plans the way you intended.
# Using AWS CloudTrail events to monitor backup policies in your organization
You can use AWS CloudTrail events to monitor when backup policies are created, updated, or deleted from any accounts in your organization, or when there is an invalid organizational backup plan. For more information, see [Logging cross-account management events ](https://docs.aws.amazon.com/aws-backup/latest/devguide/logging-using-cloudtrail.html#logging-cam-events) in the *AWS Backup Developer Guide*.
# Backup policy syntax and examples
This page describes backup policy syntax and provides examples.
## Syntax for backup policies
A backup policy is a plaintext file that is structured according to the rules of [JSON](http://json.org). The syntax for backup policies follows the syntax for all management policy types. For more information, see [Policy syntax and inheritance for management policy types](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_inheritance_mgmt.html). This topic focuses on applying that general syntax to the specific requirements of the backup policy type.
For more information about AWS Backup plans, see [CreateBackupPlan](https://docs.aws.amazon.com/aws-backup/latest/devguide/API_CreateBackupPlan.html) in the *AWS Backup Developer Guide*.
## Considerations
**Policy syntax**
Duplicate key names will be rejected in JSON.
Policies must specify the AWS Regions and resources to be backed up.
Policies must specify the IAM role that AWS Backup assumes.
Using `@@assign` operator at the same level can overwrite existing settings. For more information, see [A child policy overrides settings in a parent policy](#backup-policy-example-5).
Inheritance operators control how inherited policies and account policies merge into the account's effective policy. These operators include value-setting operators and child control operators.
For more information, see [Inheritance operators](policy-operators.md) and [Backup policy examples](#backup-policy-examples).
**IAM roles**
The IAM role must exist when creating a backup plan for the first time.
The IAM role must have permission to access resources identified by tag query.
The IAM role must have permission to perform the backup.
**Backup vaults**
Vaults must exist in each specified AWS Regions before a backup plan can run.
Vaults must exist for each AWS account that receives the effective policy. For more information, see [Backup vault creation and deletion](https://docs.aws.amazon.com/aws-backup/latest/devguide/create-a-vault.html) in the *AWS Backup Developer Guide*.
We recommend that you use AWS CloudFormation stack sets and its integration with Organizations to automatically create and configure backup vaults and IAM roles for each member account in the organization. For more information, see [Create a stack set with self-managed permissions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-getting-started-create.html#create-stack-set-service-managed-permissions) in the *AWS CloudFormation User Guide*.
**Quotas**
For a list of quotas see, [AWS Backup quotas](https://docs.aws.amazon.com/aws-backup/latest/devguide/aws-backup-limits.html#aws-backup-policies-quotas-table) in the *AWS Backup Developer Guide*.
## Backup syntax: Overview
Backup policy syntax includes the following components:
```
{
"plans": {
"PlanName": {
"rules": { ... },
"regions": { ... },
"selections": { ... },
"advanced_backup_settings": { ... },
"backup_plan_tags": { ... },
"scan_settings": { ... }
}
}
}
```
**Backup policy elements**
| Element | Description | Required |
| --- | --- | --- |
| [rules](#backup-policy-rules) | List of backup rules. Each rule defines when backups start and the execution window for the resources specified in the regions and selections elements. | Yes |
| [regions](#backup-plan-regions) | List of AWS Regions where a backup policy can protect resources. | Yes |
| [selections](#backup-plan-selections) | One or more resource types within the specified regions that the backup rules protect. | Yes |
| [advanced\$1backup\$1settings](#advanced-backup-settings) | Configuration options for specific backup scenarios. Currently, the only advanced backup setting that is supported is enabling Microsoft Volume Shadow Copy Service (VSS) backups for Windows or SQL Server running on an Amazon EC2 instance. | No |
| [backup\$1plan\$1tags](#backup-plan-tags) | Tags you want to associate with a backup plan. Each tag is a label consisting of a user-defined key and value. Tags can help you manage, identify, organize, search for, and filter your backup plans. | No |
| [scan\$1settings](#scan-settings) | Configuration options for scan settings. Currently the only scan settings that is support is enable Amazon GuardDuty Malware Protection for AWS Backup. | No |
## Backup syntax: rules
The `rules` policy key specifies the scheduled backup tasks that AWS Backup performs on the selected resources.
**Backup rule elements**
| Element | Description | Required |
| --- | --- | --- |
| schedule\$1expression | Cron expression in UTC that specifies when AWS Backup initiates a backup job. For information about cron expression, see [Using cron and rate expressions to schedule rules](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html) in the *Amazon EventBridge User Guide*. | Yes |
| target\$1backup\$1vault\$1name | Backup vault where backups are stored. Backup vaults are identified by names that are unique to the account used to create them and the AWS Region where they are created. | Yes |
| target\$1logically\$1air\$1gapped\$1backup\$1vault\$1arn | Logically air-gapped vault ARN where backups are stored. If provided, supported fully managed resources back up directly to logically air-gapped vault, while other supported resources create a temporary (billable) snapshot in backup vault, then copy it to logically air-gapped vault. Unsupported resources only back up to the specified backup vault. The ARN must use the special placeholders `$region` and `$account`. For example, for a vault named `AirGappedVault` the correct value is `arn:aws:backup:$region:$account:backup-vault:AirGappedVault`. | No |
| start\$1backup\$1window\$1minutes | Number of minutes to wait before canceling a backup job will be canceled if it doesn't start successfully. If this value is included, it must be at least 60 minutes to avoid errors. | No |
| complete\$1backup\$1window\$1minutes | Nnumber of minutes after a backup job is successfully started before it must be completed or it will be canceled by AWS Backup. | No |
| enable\$1continuous\$1backup | Specifies whether AWS Backup creates continuous backups. `True` causes AWS Backup to create continuous backups capable of point-in-time restore (PITR). `False` (or not specified) causes AWS Backup to create snapshot backups. For more information about continuous backups, see [Point-in-time recovery](https://docs.aws.amazon.com/aws-backup/latest/devguide/point-in-time-recovery.html) in the *AWS Backup Developer Guide*. **Note:** PITR-enabled backups have 35-day maximum retention. | No |
| lifecycle | Specifies when AWS Backup transitions a backup to cold storage and when it expires. Resource types that can transition to cold storage are listed in the Feature availability by resource table [Feature availability by resources](https://docs.aws.amazon.com/aws-backup/latest/devguide/backup-feature-availability.html#features-by-resource) in the *AWS Backup Developer Guide*. Each lifecycle contains the following elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_backup_syntax.html) **Note**: Backups transitioned to cold storage must be stored in cold storage for a minimum of 90 days. This means that the `delete_after_days` must be 90 days greater than `move_to_cold_storage_after_days`. | No |
| copy\$1actions | Specifies whether AWS Backup copies a backup to one or more additional locations. Each copy action contains the following elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_backup_syntax.html) **Note**: Backups transitioned to cold storage must be stored in cold storage for a minimum of 90 days. This means that the `delete_after_days` must be 90 days greater than `move_to_cold_storage_after_days`. | No |
| recovery\$1point\$1tags | Tags that you want to assigned to resources that are restored from backup. Each tag contains the following elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_backup_syntax.html) | No |
| index\$1actions | Specifies whether AWS Backup creates a backup index of your Amazon EBS snapshots and/or Amazon S3 backups. Backup indexes are created in order to search the metadata of your backups. For more information about backup index creation and backup search, see [Backup search](https://docs.aws.amazon.com//aws-backup/latest/devguide/backup-search.html#backup-search-overview). **Note:** Additional [IAM role permissions](https://docs.aws.amazon.com//aws-backup/latest/devguide/backup-search.html#backup-search-access) are required for Amazon EBS snapshot backup index creation. Each index action contains the following element: `resource_types` where resource types supported for indexing are Amazon EBS and Amazon S3. This parameter specifies which resource type will be opted into indexing. | No |
| scan\$1actions | Specifies whether a scanning action is enabled for a given rule. You must specify a `ScanMode`. You must use `scan_settings` in the backup policy elements in conjunction with `scan_actions` in order for scanning jobs to start successfully. Please also ensure you have the right [IAM role permissions](https://docs.aws.amazon.com//aws-backup/latest/devguide/malware-protection.html#malware-access). [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_backup_syntax.html) | No |
## Backup syntax: regions
The `regions` policy key specifies which AWS Regions that AWS Backup looks in to find the resources that match the conditions in the `selections` key.
**Backup regions elements**
| Element | Description | Required |
| --- | --- | --- |
| regions | Specifies the AWS Region codes. For example: `["us-east-1", "eu-north-1"]`. | Yes |
## Backup syntax: selections
The `selections` policy key specifies the resources that are backed up by the rules in a backup policy.
There are two mutually exclusive elements: `tags` and `resources`. An effective policy **must** `have` either tags or `resources` in the selection to be valid.
If you want a selection with both tag conditions and resource conditions, use the `resources` keys.
**Backup selection elements: Tags**
| Element | Description | Required |
| --- | --- | --- |
| iam\$1role\$1arn | IAM role that AWS Backup assumes to query, discover, and backup resources across the specified Regions. The role must have sufficient permissions to query resources based on tag conditions and perform backup operations on the matched resources. | Yes |
| tag\$1key | Tag key name to search for. | Yes |
| tag\$1value | Value that must be associated with the matching tag\$1key. AWS Backup includes the resource only if both tag\$1key and tag\$1value match (case sensitive). | Yes |
| conditions | Tag keys and values you want to include or exclude Use string\$1equals or string\$1not\$1equals to include or exclude tags of an exact match. Use string\$1like and string\$1not\$1like to include or exclude tags that contains or do not contain specific characters **Note:** Limited to 30 conditions for each selection. | No |
**Backup selection elements: Resources**
| Element | Description | Required |
| --- | --- | --- |
| iam\$1role\$1arn | IAM role that AWS Backup assumes to query, discover, and backup resources across the specified Regions. The role must have sufficient permissions to query resources based on tag conditions and perform backup operations on the matched resources. **Note:** In AWS GovCloud (US) Regions, you must add the name of the partition to the ARN. For example, "`arn:aws:ec2:*:*:volume/*`" must be "`arn:aws-us-gov:ec2:*:*:volume/*`". | Yes |
| resource\$1types | Resource types to include in a backup plan. | Yes |
| not\$1resource\$1types | Resource types to exclude from a backup plan. | No |
| conditions | Tag keys and values you want to include or exclude Use string\$1equals or string\$1not\$1equals to include or exclude tags of an exact match. Use string\$1like and string\$1not\$1like to include or exclude tags that contains or do not contain specific characters **Note:** Limited to 30 conditions for each selection. | No |
**Supported resource types**
Organizations supports the following resource types for the `resource_types` and `not_resource_types` elements:
+ AWS Backup gateway virtual machines: `"arn:aws:backup-gateway:*:*:vm/*"`
+ AWS CloudFormation stacks: `"arn:aws:cloudformation:*:*:stack/*"`
+ Aurora DSQL clusters: `"arn:aws:dsql:*:*:cluster/*"`
+ Amazon DynamoDB tables: `"arn:aws:dynamodb:*:*:table/*"`
+ Amazon EC2 instances: `"arn:aws:ec2:*:*:instance/*"`
+ Amazon EBS volumes: `"arn:aws:ec2:*:*:volume/*"`
+ Amazon EFS file systems: `"arn:aws:elasticfilesystem:*:*:file-system/*"`
+ Amazon Aurora/Amazon DocumentDB/Amazon Neptune clusters: `"arn:aws:rds:*:*:cluster:*"`
+ Amazon RDS databases: `"arn:aws:rds:*:*:db:*"`
+ Amazon Redshift clusters: `"arn:aws:redshift:*:*:cluster:*"`
+ Amazon Redshift Serverless namespaces: `"arn:aws:redshift-serverless:*:*:namespace/*"`
+ Amazon S3: `"arn:aws:s3:::*"`
+ AWS Systems Manager for SAP HANA databases: `"arn:aws:ssm-sap:*:*:HANA/*"`
+ AWS Storage Gateway gateways: `"arn:aws:storagegateway:*:*:gateway/*"`
+ Amazon Timestream databases: `"arn:aws:timestream:*:*:database/*"`
+ Amazon FSx file systems: `"arn:aws:fsx:*:*:file-system/*"`
+ Amazon FSx volumes: `"arn:aws:fsx:*:*:volume/*"`
+ Amazon Elastic Kubernetes Service volumes: `"arn:aws:eks:*:*:cluster/*"`
**Code examples**
For more information, see [Specifying resources with the tags block](#backup-policy-example-6) and [Specifying resources with the resources block](#backup-policy-example-7).
## Backup syntax: advanced backup settings
The `advanced_backup_settings` key specifies the configuration options for specific backup scenarios. Each setting contains the following elements:
**Advanced backup settings elements**
| Element | Description | Required |
| --- | --- | --- |
| advanced\$1backup\$1settings | Specifies settings for specific backup scenarios. This key contains one or more settings. Each setting is a JSON object string with the following elements: Currently the only advanced backup setting that is supported is enabling Microsoft Volume Shadow Copy Service (VSS) backups for Windows or SQL Server running on an Amazon EC2 instance. Each advanced backup setting the following elements: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_backup_syntax.html) | No |
**Example:**
```
"advanced_backup_settings": {
"ec2": {
"windows_vss": {
"@@assign": "enabled"
}
}
},
```
## Backup syntax: backup plan tags
The `backup_plan_tags` policy key specifies the tags that are attached to a backup plan itself. This does not impact the tags specified for `rules` or `selections`.
**Backup plan tag elements**
| Element | Description | Required |
| --- | --- | --- |
| backup\$1plan\$1tags | Each tag is a label consisting of a user-defined key and value: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_backup_syntax.html) | No |
## Backup syntax: scan settings
The `scan_settings` policy key specifies the configuration for malware scanning using Amazon GuardDuty Malware Protection for AWS Backup. You must use `scan_settings` in conjunction with `scan_actions` in your backup rules for scanning jobs to start successfully.
**Scan settings elements**
| Element | Description | Required |
| --- | --- | --- |
| scan\$1settings | Configuration options for scan settings. Currently the only scan settings that is supported is enabling Amazon GuardDuty Malware Protection for AWS Backup. You must specify the `ResourceTypes` and `ScannerRoleArn`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_backup_syntax.html) | No |
**Example:**
The following shows how to configure `scan_actions` in a backup rule and `scan_settings` at the plan level to enable Amazon GuardDuty Malware Protection scanning.
`scan_actions` in a rule:
```
"scan_actions": {
"GUARDDUTY": {
"scan_mode": {
"@@assign": "INCREMENTAL_SCAN"
}
}
}
```
`scan_settings` at the plan level:
```
"scan_settings": {
"GUARDDUTY": {
"resource_types": {
"@@assign": ["EBS"]
},
"scanner_role_arn": {
"@@assign": "arn:aws:iam::$account:role/MyGuardDutyScannerRole"
}
}
}
```
## Backup policy examples
The example backup policies that follow are for information purposes only. In some of the following examples, the JSON whitespace formatting might be compressed to save space.
+ [Example 1: Policy assigned to a parent node](#backup-policy-example-1)
+ [Example 2: A parent policy is merged with a child policy](#backup-policy-example-2)
+ [Example 3: A parent policy prevents any changes by a child policy](#backup-policy-example-3)
+ [Example 4: A parent policy prevents changes to one backup plan by a child policy](#backup-policy-example-4)
+ [Example 5: A child policy overrides settings in a parent policy](#backup-policy-example-5)
+ [Example 6: Specifying resources with the tags block](#backup-policy-example-6)
+ [Example 7: Specifying resources with the resources block](#backup-policy-example-7)
+ [Example 8: Backup plan with Amazon GuardDuty Malware Protection scanning](#backup-policy-example-8)
### Example 1: Policy assigned to a parent node
The following example shows a backup policy that is assigned to one of the parent nodes of an account.
**Parent policy** – This policy can be attached to the organization's root, or to any OU that is a parent of all of the intended accounts.
```
{
"plans": {
"PII_Backup_Plan": {
"regions": {
"@@assign": [
"ap-northeast-2",
"us-east-1",
"eu-north-1"
]
},
"rules": {
"Hourly": {
"schedule_expression": {
"@@assign": "cron(0 5/1 ? * * *)"
},
"start_backup_window_minutes": {
"@@assign": "480"
},
"complete_backup_window_minutes": {
"@@assign": "10080"
},
"lifecycle": {
"move_to_cold_storage_after_days": {
"@@assign": "180"
},
"delete_after_days": {
"@@assign": "270"
},
"opt_in_to_archive_for_supported_resources": {
"@@assign": "false"
}
},
"target_backup_vault_name": {
"@@assign": "FortKnox"
},
"target_logically_air_gapped_backup_vault_arn": {
"@@assign": "arn:aws:backup:$region:$account:backup-vault:AirGappedVault"
},
"index_actions": {
"resource_types": {
"@@assign": [
"EBS",
"S3"
]
}
},
"copy_actions": {
"arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault": {
"target_backup_vault_arn": {
"@@assign": "arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault"
},
"lifecycle": {
"move_to_cold_storage_after_days": {
"@@assign": "30"
},
"delete_after_days": {
"@@assign": "120"
},
"opt_in_to_archive_for_supported_resources": {
"@@assign": "false"
}
}
},
"arn:aws:backup:us-west-1:111111111111:backup-vault:tertiary_vault": {
"target_backup_vault_arn": {
"@@assign": "arn:aws:backup:us-west-1:111111111111:backup-vault:tertiary_vault"
},
"lifecycle": {
"move_to_cold_storage_after_days": {
"@@assign": "30"
},
"delete_after_days": {
"@@assign": "120"
},
"opt_in_to_archive_for_supported_resources": {
"@@assign": "false"
}
}
}
}
}
},
"selections": {
"tags": {
"datatype": {
"iam_role_arn": {
"@@assign": "arn:aws:iam::$account:role/MyIamRole"
},
"tag_key": {
"@@assign": "dataType"
},
"tag_value": {
"@@assign": [
"PII",
"RED"
]
}
}
}
},
"advanced_backup_settings": {
"ec2": {
"windows_vss": {
"@@assign": "enabled"
}
}
}
}
}
}
```
If no other policies are inherited or attached to the accounts, the effective policy rendered in each applicable AWS account looks like the following example. The CRON expression causes the backup to run once an hour on the hour. The account ID 123456789012 will be the actual account ID for each account.
```
{
"plans": {
"PII_Backup_Plan": {
"regions": [
"us-east-1",
"ap-northeast-3",
"eu-north-1"
],
"rules": {
"hourly": {
"schedule_expression": "cron(0 0/1 ? * * *)",
"start_backup_window_minutes": "60",
"target_backup_vault_name": "FortKnox",
"target_logically_air_gapped_backup_vault_arn": "arn:aws:backup:$region:$account:backup-vault:AirGappedVault",
"index_actions": {
"resource_types": {
"@@assign": [
"EBS",
"S3"
]
}
},
"lifecycle": {
"delete_after_days": "2",
"move_to_cold_storage_after_days": "180",
"opt_in_to_archive_for_supported_resources": "false"
},
"copy_actions": {
"arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault": {
"target_backup_vault_arn": {
"@@assign": "arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault"
},
"lifecycle": {
"delete_after_days": "28",
"move_to_cold_storage_after_days": "180",
"opt_in_to_archive_for_supported_resources": "false"
}
},
"arn:aws:backup:us-west-1:111111111111:backup-vault:tertiary_vault": {
"target_backup_vault_arn": {
"@@assign": "arn:aws:backup:us-west-1:111111111111:backup-vault:tertiary_vault"
},
"lifecycle": {
"delete_after_days": "28",
"move_to_cold_storage_after_days": "180",
"opt_in_to_archive_for_supported_resources": "false"
}
}
}
}
},
"selections": {
"tags": {
"datatype": {
"iam_role_arn": "arn:aws:iam::123456789012:role/MyIamRole",
"tag_key": "dataType",
"tag_value": [
"PII",
"RED"
]
}
}
},
"advanced_backup_settings": {
"ec2": {
"windows_vss": "enabled"
}
}
}
}
}
```
### Example 2: A parent policy is merged with a child policy
In the following example, an inherited parent policy and a child policy either inherited or directly attached to an AWS account merge to form the effective policy.
**Parent policy** – This policy can be attached to the organization's root or to any parent OU.
```
{
"plans": {
"PII_Backup_Plan": {
"regions": { "@@append":[ "us-east-1", "ap-northeast-3", "eu-north-1" ] },
"rules": {
"Hourly": {
"schedule_expression": { "@@assign": "cron(0 0/1 ? * * *)" },
"start_backup_window_minutes": { "@@assign": "60" },
"target_backup_vault_name": { "@@assign": "FortKnox" },
"index_actions": {
"resource_types": {
"@@assign": [
"EBS",
"S3"
]
}
},
"lifecycle": {
"move_to_cold_storage_after_days": { "@@assign": "28" },
"delete_after_days": { "@@assign": "180" },
"opt_in_to_archive_for_supported_resources": { "@@assign": "false" }
},
"copy_actions": {
"arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault" : {
"target_backup_vault_arn" : {
"@@assign" : "arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault"
},
"lifecycle": {
"move_to_cold_storage_after_days": { "@@assign": "28" },
"delete_after_days": { "@@assign": "180" },
"opt_in_to_archive_for_supported_resources": { "@@assign": "false" }
}
}
}
}
},
"selections": {
"tags": {
"datatype": {
"iam_role_arn": { "@@assign": "arn:aws:iam::$account:role/MyIamRole" },
"tag_key": { "@@assign": "dataType" },
"tag_value": { "@@assign": [ "PII", "RED" ] }
}
}
}
}
}
}
```
**Child policy** – This policy can be attached directly to the account or to an OU any level below the one the parent policy is attached to.
```
{
"plans": {
"Monthly_Backup_Plan": {
"regions": {
"@@append":[ "us-east-1", "eu-central-1" ] },
"rules": {
"Monthly": {
"schedule_expression": { "@@assign": "cron(0 5 1 * ? *)" },
"start_backup_window_minutes": { "@@assign": "480" },
"target_backup_vault_name": { "@@assign": "Default" },
"lifecycle": {
"move_to_cold_storage_after_days": { "@@assign": "30" },
"delete_after_days": { "@@assign": "365" },
"opt_in_to_archive_for_supported_resources": { "@@assign": "false" }
},
"copy_actions": {
"arn:aws:backup:us-east-1:$account:backup-vault:Default" : {
"target_backup_vault_arn" : {
"@@assign" : "arn:aws:backup:us-east-1:$account:backup-vault:Default"
},
"lifecycle": {
"move_to_cold_storage_after_days": { "@@assign": "30" },
"delete_after_days": { "@@assign": "365" },
"opt_in_to_archive_for_supported_resources": { "@@assign": "false" }
}
}
}
}
},
"selections": {
"tags": {
"MonthlyDatatype": {
"iam_role_arn": { "@@assign": "arn:aws:iam::$account:role/MyMonthlyBackupIamRole" },
"tag_key": { "@@assign": "BackupType" },
"tag_value": { "@@assign": [ "MONTHLY", "RED" ] }
}
}
}
}
}
}
```
**Resulting effective policy** – The effective policy applied to the accounts contains two plans, each with its own set of rules and set of resources to apply the rules to.
```
{
"plans": {
"PII_Backup_Plan": {
"regions": [ "us-east-1", "ap-northeast-3", "eu-north-1" ],
"rules": {
"hourly": {
"schedule_expression": "cron(0 0/1 ? * * *)",
"start_backup_window_minutes": "60",
"target_backup_vault_name": "FortKnox",
"index_actions": {
"resource_types": {
"@@assign": [
"EBS",
"S3"
]
}
},
"lifecycle": {
"delete_after_days": "2",
"move_to_cold_storage_after_days": "180",
"opt_in_to_archive_for_supported_resources": { "@@assign": "false" }
},
"copy_actions": {
"arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault" : {
"target_backup_vault_arn" : {
"@@assign" : "arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault"
},
"lifecycle": {
"move_to_cold_storage_after_days": "28",
"delete_after_days": "180",
"opt_in_to_archive_for_supported_resources": { "@@assign": "false" }
}
}
}
}
},
"selections": {
"tags": {
"datatype": {
"iam_role_arn": "arn:aws:iam::$account:role/MyIamRole",
"tag_key": "dataType",
"tag_value": [ "PII", "RED" ]
}
}
}
},
"Monthly_Backup_Plan": {
"regions": [ "us-east-1", "eu-central-1" ],
"rules": {
"monthly": {
"schedule_expression": "cron(0 5 1 * ? *)",
"start_backup_window_minutes": "480",
"target_backup_vault_name": "Default",
"lifecycle": {
"delete_after_days": "365",
"move_to_cold_storage_after_days": "30",
"opt_in_to_archive_for_supported_resources": { "@@assign": "false" }
},
"copy_actions": {
"arn:aws:backup:us-east-1:$account:backup-vault:Default" : {
"target_backup_vault_arn": {
"@@assign" : "arn:aws:backup:us-east-1:$account:backup-vault:Default"
},
"lifecycle": {
"move_to_cold_storage_after_days": "30",
"delete_after_days": "365",
"opt_in_to_archive_for_supported_resources": { "@@assign": "false" }
}
}
}
}
},
"selections": {
"tags": {
"monthlydatatype": {
"iam_role_arn": "arn:aws:iam::&ExampleAWSAccountNo3;:role/MyMonthlyBackupIamRole",
"tag_key": "BackupType",
"tag_value": [ "MONTHLY", "RED" ]
}
}
}
}
}
}
```
### Example 3: A parent policy prevents any changes by a child policy
In the following example, an inherited parent policy uses the [child control operators](policy-operators.md#child-control-operators) to enforce all settings and prevents them from being changed or overridden by a child policy.
**Parent policy** – This policy can be attached to the organization's root or to any parent OU. The presence of `"@@operators_allowed_for_child_policies": ["@@none"]` at every node of the policy means that a child policy can't make changes of any kind to the plan. Nor can a child policy add additional plans to the effective policy. This policy becomes the effective policy for every OU and account under the OU to which it is attached.
```
{
"plans": {
"@@operators_allowed_for_child_policies": ["@@none"],
"PII_Backup_Plan": {
"@@operators_allowed_for_child_policies": ["@@none"],
"regions": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@append": [
"us-east-1",
"ap-northeast-3",
"eu-north-1"
]
},
"rules": {
"@@operators_allowed_for_child_policies": ["@@none"],
"Hourly": {
"@@operators_allowed_for_child_policies": ["@@none"],
"schedule_expression": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "cron(0 0/1 ? * * *)"
},
"start_backup_window_minutes": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "60"
},
"target_backup_vault_name": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "FortKnox"
},
"index_actions": {
"@@operators_allowed_for_child_policies": ["@@none"],
"resource_types": {
"@@assign": [
"EBS",
"S3"
]
}
},
"lifecycle": {
"@@operators_allowed_for_child_policies": ["@@none"],
"move_to_cold_storage_after_days": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "28"
},
"delete_after_days": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "180"
},
"opt_in_to_archive_for_supported_resources": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "false"
}
},
"copy_actions": {
"@@operators_allowed_for_child_policies": ["@@none"],
"arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault": {
"@@operators_allowed_for_child_policies": ["@@none"],
"target_backup_vault_arn": {
"@@assign": "arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault",
"@@operators_allowed_for_child_policies": ["@@none"]
},
"lifecycle": {
"@@operators_allowed_for_child_policies": ["@@none"],
"delete_after_days": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "28"
},
"move_to_cold_storage_after_days": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "180"
},
"opt_in_to_archive_for_supported_resources": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "false"
}
}
}
}
}
},
"selections": {
"@@operators_allowed_for_child_policies": ["@@none"],
"tags": {
"@@operators_allowed_for_child_policies": ["@@none"],
"datatype": {
"@@operators_allowed_for_child_policies": ["@@none"],
"iam_role_arn": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "arn:aws:iam::$account:role/MyIamRole"
},
"tag_key": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "dataType"
},
"tag_value": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": [
"PII",
"RED"
]
}
}
}
},
"advanced_backup_settings": {
"@@operators_allowed_for_child_policies": ["@@none"],
"ec2": {
"@@operators_allowed_for_child_policies": ["@@none"],
"windows_vss": {
"@@assign": "enabled",
"@@operators_allowed_for_child_policies": ["@@none"]
}
}
}
}
}
}
```
**Resulting effective policy** – If any child backup policies exist, they are ignored and the parent policy becomes the effective policy.
```
{
"plans": {
"PII_Backup_Plan": {
"regions": [
"us-east-1",
"ap-northeast-3",
"eu-north-1"
],
"rules": {
"hourly": {
"schedule_expression": "cron(0 0/1 ? * * *)",
"start_backup_window_minutes": "60",
"target_backup_vault_name": "FortKnox",
"index_actions": {
"resource_types": {
"@@assign": [
"EBS",
"S3"
]
}
},
"lifecycle": {
"delete_after_days": "2",
"move_to_cold_storage_after_days": "180",
"opt_in_to_archive_for_supported_resources": "false"
},
"copy_actions": {
"target_backup_vault_arn": "arn:aws:backup:us-east-1:123456789012:backup-vault:secondary_vault",
"lifecycle": {
"move_to_cold_storage_after_days": "28",
"delete_after_days": "180",
"opt_in_to_archive_for_supported_resources": "false"
}
}
}
},
"selections": {
"tags": {
"datatype": {
"iam_role_arn": "arn:aws:iam::123456789012:role/MyIamRole",
"tag_key": "dataType",
"tag_value": [
"PII",
"RED"
]
}
}
},
"advanced_backup_settings": {
"ec2": {"windows_vss": "enabled"}
}
}
}
}
```
### Example 4: A parent policy prevents changes to one backup plan by a child policy
In the following example, an inherited parent policy uses the [child control operators](policy-operators.md#child-control-operators) to enforce the settings for a single plan and prevents them from being changed or overridden by a child policy. The child policy can still add additional plans.
**Parent policy** – This policy can be attached to the organization's root or to any parent OU. This example is similar to the previous example with all child inheritance operators blocked, except at the `plans` top level. The `@@append` setting at that level enables child policies to add other plans to the collection in the effective policy. Any changes to the inherited plan are still blocked.
The sections in the plan are truncated for clarity.
```
{
"plans": {
"@@operators_allowed_for_child_policies": ["@@append"],
"PII_Backup_Plan": {
"@@operators_allowed_for_child_policies": ["@@none"],
"regions": { ... },
"rules": { ... },
"selections": { ... }
}
}
}
```
**Child policy** – This policy can be attached directly to the account or to an OU any level below the one the parent policy is attached to. This child policy defines a new plan.
The sections in the plan are truncated for clarity.
```
{
"plans": {
"MonthlyBackupPlan": {
"regions": { ... },
"rules": { ... },
"selections": { … }
}
}
}
```
**Resulting effective policy** – The effective policy includes both plans.
```
{
"plans": {
"PII_Backup_Plan": {
"regions": { ... },
"rules": { ... },
"selections": { ... }
},
"MonthlyBackupPlan": {
"regions": { ... },
"rules": { ... },
"selections": { … }
}
}
}
```
### Example 5: A child policy overrides settings in a parent policy
In the following example, a child policy uses [value-setting operators](policy-operators.md#value-setting-operators) to override some of the settings inherited from a parent policy.
**Parent policy** – This policy can be attached to the organization's root or to any parent OU. Any of the settings can be overridden by a child policy because the default behavior, in the absence of a [child-control operator](policy-operators.md#child-control-operators) that prevents it, is to allow the child policy to `@@assign`, `@@append`, or `@@remove`. The parent policy contains all of the required elements for a valid backup plan, so it backs up your resources successfully if it is inherited as is.
```
{
"plans": {
"PII_Backup_Plan": {
"regions": {
"@@append": [
"us-east-1",
"ap-northeast-3",
"eu-north-1"
]
},
"rules": {
"Hourly": {
"schedule_expression": {"@@assign": "cron(0 0/1 ? * * *)"},
"start_backup_window_minutes": {"@@assign": "60"},
"target_backup_vault_name": {"@@assign": "FortKnox"},
"index_actions": {
"resource_types": {
"@@assign": [
"EBS",
"S3"
]
}
},
"lifecycle": {
"delete_after_days": {"@@assign": "2"},
"move_to_cold_storage_after_days": {"@@assign": "180"},
"opt_in_to_archive_for_supported_resources": {"@@assign": false}
},
"copy_actions": {
"arn:aws:backup:us-east-1:$account:backup-vault:t2": {
"target_backup_vault_arn": {"@@assign": "arn:aws:backup:us-east-1:$account:backup-vault:t2"},
"lifecycle": {
"move_to_cold_storage_after_days": {"@@assign": "28"},
"delete_after_days": {"@@assign": "180"},
"opt_in_to_archive_for_supported_resources": {"@@assign": false}
}
}
}
}
},
"selections": {
"tags": {
"datatype": {
"iam_role_arn": {"@@assign": "arn:aws:iam::$account:role/MyIamRole"},
"tag_key": {"@@assign": "dataType"},
"tag_value": {
"@@assign": [
"PII",
"RED"
]
}
}
}
}
}
}
}
```
**Child policy** – The child policy includes only the settings that need to be different from the inherited parent policy. There must be an inherited parent policy that provides the other required settings when merged into an effective policy. Otherwise, the effective backup policy contains a backup plan that is not valid and doesn't back up your resources as expected.
```
{
"plans": {
"PII_Backup_Plan": {
"regions": {
"@@assign": [
"us-west-2",
"eu-central-1"
]
},
"rules": {
"Hourly": {
"schedule_expression": {"@@assign": "cron(0 0/2 ? * * *)"},
"start_backup_window_minutes": {"@@assign": "80"},
"target_backup_vault_name": {"@@assign": "Default"},
"lifecycle": {
"move_to_cold_storage_after_days": {"@@assign": "30"},
"delete_after_days": {"@@assign": "365"},
"opt_in_to_archive_for_supported_resources": {"@@assign": false}
}
}
}
}
}
}
```
**Resulting effective policy** – The effective policy includes settings from both policies, with the settings provided by the child policy overriding the settings inherited from the parent. In this example, the following changes occur:
+ The list of Regions is replaced with a completely different list. If you wanted to add a Region to the inherited list, use `@@append` instead of `@@assign` in the child policy.
+ AWS Backup performs every other hour instead of hourly.
+ AWS Backup allows 80 minutes for the backup to start instead of 60 minutes.
+ AWS Backup uses the `Default` vault instead of `FortKnox`.
+ The lifecycle is extended for both the transfer to cold storage and the eventual deletion of the backup.
```
{
"plans": {
"PII_Backup_Plan": {
"regions": [
"us-west-2",
"eu-central-1"
],
"rules": {
"hourly": {
"schedule_expression": "cron(0 0/2 ? * * *)",
"start_backup_window_minutes": "80",
"target_backup_vault_name": "Default",
"index_actions": {
"resource_types": {
"@@assign": [
"EBS",
"S3"
]
}
},
"lifecycle": {
"delete_after_days": "365",
"move_to_cold_storage_after_days": "30",
"opt_in_to_archive_for_supported_resources": "false"
},
"copy_actions": {
"arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault": {
"target_backup_vault_arn": {"@@assign": "arn:aws:backup:us-east-1:$account:backup-vault:secondary_vault"},
"lifecycle": {
"move_to_cold_storage_after_days": "28",
"delete_after_days": "180",
"opt_in_to_archive_for_supported_resources": "false"
}
}
}
}
},
"selections": {
"tags": {
"datatype": {
"iam_role_arn": "arn:aws:iam::$account:role/MyIamRole",
"tag_key": "dataType",
"tag_value": [
"PII",
"RED"
]
}
}
}
}
}
}
```
### Example 6: Specifying resources with the `tags` block
The following example includes all resources with the `tag_key` = `“env”` and `tag_value` = `"prod"` or `"gamma"`. This example excludes resources with the `tag_key` = `"backup"` and the `tag_value` = `"false"`.
```
...
"selections":{
"tags":{
"selection_name":{
"iam_role_arn": {"@@assign": "arn:aws:iam::$account:role/IAMRole"},
"tag_key":{"@@assign": "env"},
"tag_value":{"@@assign": ["prod", "gamma"]},
"conditions":{
"string_not_equals":{
"condition_name1":{
"condition_key": { "@@assign": "aws:ResourceTag/backup" },
"condition_value": { "@@assign": "false" }
}
}
}
}
}
},
...
```
### Example 7: Specifying resources with the `resources` block
The following are examples of using the `resources` block to specify resources.
------
#### [ Example: Select all resources in my account ]
The Boolean logic is similar to what you might use in IAM policies. The `"resource_types"` block uses a Boolean `AND` to combine the resource types.
```
...
"resources":{
"resource_selection_name":{
"iam_role_arn":{"@@assign": "arn:aws:iam::$account:role/IAMRole"},
"resource_types":{
"@@assign": [
"*"
]
}
}
},
...
```
------
#### [ Example: Select all resources in my account, but exclude Amazon EBS volumes ]
The Boolean logic is similar to what you might use in IAM policies. The `"resource_types"` and `"not_resource_types"` blocks use a Boolean `AND` to combine the resource types.
```
...
"resources":{
"resource_selection_name":{
"iam_role_arn":{"@@assign": "arn:aws:iam::$account:role/IAMRole"},
"resource_types":{
"@@assign": [
"*"
]
},
"not_resource_types":{
"@@assign": [
"arn:aws:ec2:*:*:volume/*"
]
}
}
},
...
```
------
#### [ Example: Select all resources tagged with "backup" : "true", but exclude Amazon EBS volumes ]
The Boolean logic is similar to what you might use in IAM policies. The `"resource_types"` and `"not_resource_types"` blocks use a Boolean `AND` to combine the resource types. The `"conditions"` block uses a Boolean `AND`.
```
...
"resources":{
"resource_selection_name":{
"iam_role_arn":{"@@assign": "arn:aws:iam::$account:role/IAMRole"},
"resource_types":{
"@@assign": [
"*"
]
},
"not_resource_types":{
"@@assign": [
"arn:aws:ec2:*:*:volume/*"
]
},
"conditions":{
"string_equals":{
"condition_name1":{
"condition_key": { "@@assign":"aws:ResourceTag/backup"},
"condition_value": { "@@assign":"true" }
}
}
}
}
},
...
```
------
#### [ Example: Select all Amazon EBS volumes and Amazon RDS DB instances tagged with both "backup" : "true" and "stage" : "prod" ]
The Boolean logic is similar to what you might use in IAM policies. The `"resource_types"` block uses a Boolean `AND` to combine the resource types. The `"conditions"` block uses a Boolean `AND` to combine resource types and tag conditions.
```
...
"resources":{
"resource_selection_name":{
"iam_role_arn":{"@@assign": "arn:aws:iam::$account:role/IAMRole"},
"resource_types":{
"@@assign": [
"arn:aws:ec2:*:*:volume/*",
"arn:aws:rds:*:*:db:*"
]
},
"conditions":{
"string_equals":{
"condition_name1":{
"condition_key":{"@@assign":"aws:ResourceTag/backup"},
"condition_value":{"@@assign":"true"}
},
"condition_name2":{
"condition_key":{"@@assign":"aws:ResourceTag/stage"},
"condition_value":{"@@assign":"prod"}
}
}
}
}
},
...
```
------
#### [ Example: Select all Amazon EBS volumes and Amazon RDS instances tagged with "backup" : "true" but not "stage" : "test" ]
The Boolean logic is similar to what you might use in IAM policies. The `"resource_types"` block uses a Boolean `AND` to combine the resource types. The `"conditions"` block uses a Boolean `AND` to combine resource types and tag conditions.
```
...
"resources":{
"resource_selection_name":{
"iam_role_arn":{"@@assign": "arn:aws:iam::$account:role/IAMRole"},
"resource_types":{
"@@assign": [
"arn:aws:ec2:*:*:volume/*",
"arn:aws:rds:*:*:db:*"
]
},
"conditions":{
"string_equals":{
"condition_name1":{
"condition_key":{"@@assign":"aws:ResourceTag/backup"},
"condition_value":{"@@assign":"true"}
}
},
"string_not_equals":{
"condition_name2":{
"condition_key":{"@@assign":"aws:ResourceTag/stage"},
"condition_value":{"@@assign":"test"}
}
}
}
}
},
...
```
------
#### [ Example: Select all resources tagged with "key1" and a value which begins with "include" but not with "key2" and value that contains the word "exclude" ]
The Boolean logic is similar to what you might use in IAM policies. The `"resource_types"` block uses a Boolean `AND` to combine the resource types. The `"conditions"` block uses a Boolean `AND` to combine resource types and tag conditions.
In this example, note the use of the wildcard character `(*)` in `include*`, `*exclude*`, and `arn:aws:rds:*:*:db:*`. You can use the wildcard character `(*)` at the start, end, and middle of a string.
```
...
"resources":{
"resource_selection_name":{
"iam_role_arn":{"@@assign": "arn:aws:iam::$account:role/IAMRole"},
"resource_types":{
"@@assign": [
"*"
]
},
"conditions":{
"string_like":{
"condition_name1":{
"condition_key":{"@@assign":"aws:ResourceTag/key1"},
"condition_value":{"@@assign":"include*"}
}
},
"string_not_like":{
"condition_name2":{
"condition_key":{"@@assign":"aws:ResourceTag/key2"},
"condition_value":{"@@assign":"*exclude*"}
}
}
}
}
},
...
```
------
#### [ Example: Select all resources tagged with "backup" : "true" except Amazon FSx file systems and Amazon RDS resources ]
The Boolean logic is similar to what you might use in IAM policies. The `"resource_types"` and `"not_resource_types"` blocks use a Boolean `AND` to combine the resource types. The `"conditions"` block uses a Boolean `AND` to combine resource types and tag conditions.
```
...
"resources":{
"resource_selection_name":{
"iam_role_arn":{"@@assign": "arn:aws:iam::$account:role/IAMRole"},
"resource_types":{
"@@assign": [
"*"
]
},
"not_resource_types":{
"@@assign":[
"arn:aws:fsx:*:*:file-system/*",
"arn:aws:rds:*:*:db:*"
]
},
"conditions":{
"string_equals":{
"condition_name1":{
"condition_key":{"@@assign":"aws:ResourceTag/backup"},
"condition_value":{"@@assign":"true"}
}
}
}
}
},
...
```
------
### Example 8: Backup plan with Amazon GuardDuty Malware Protection scanning
The following example shows a backup policy that enables Amazon GuardDuty Malware Protection scanning on backup recovery points. The policy uses `scan_actions` in the rule to enable scanning and `scan_settings` at the plan level to configure the scanner.
To use this feature, you must have the appropriate IAM role permissions. For more information, see [Access](https://docs.aws.amazon.com//aws-backup/latest/devguide/malware-protection.html#malware-access) in the *AWS Backup Developer Guide*.
```
{
"plans": {
"Malware_Scan_Backup_Plan": {
"regions": {
"@@assign": [
"us-east-1",
"us-west-2"
]
},
"rules": {
"Daily_With_Incremental_Scan": {
"schedule_expression": {
"@@assign": "cron(0 5 ? * * *)"
},
"start_backup_window_minutes": {
"@@assign": "60"
},
"target_backup_vault_name": {
"@@assign": "Default"
},
"lifecycle": {
"delete_after_days": {
"@@assign": "35"
}
},
"scan_actions": {
"GUARDDUTY": {
"scan_mode": {
"@@assign": "INCREMENTAL_SCAN"
}
}
}
},
"Monthly_With_Full_Scan": {
"schedule_expression": {
"@@assign": "cron(0 5 1 * ? *)"
},
"start_backup_window_minutes": {
"@@assign": "60"
},
"target_backup_vault_name": {
"@@assign": "Default"
},
"lifecycle": {
"delete_after_days": {
"@@assign": "365"
}
},
"scan_actions": {
"GUARDDUTY": {
"scan_mode": {
"@@assign": "FULL_SCAN"
}
}
}
}
},
"selections": {
"tags": {
"scan_selection": {
"iam_role_arn": {
"@@assign": "arn:aws:iam::$account:role/MyBackupRole"
},
"tag_key": {
"@@assign": "backup"
},
"tag_value": {
"@@assign": [
"true"
]
}
}
}
},
"scan_settings": {
"GUARDDUTY": {
"resource_types": {
"@@assign": [
"EBS"
]
},
"scanner_role_arn": {
"@@assign": "arn:aws:iam::$account:role/MyGuardDutyScannerRole"
}
}
}
}
}
}
```
The key points in this example are:
+ `scan_actions` is specified inside each rule. The scanner name `GUARDDUTY` is used as the key. The daily rule uses `INCREMENTAL_SCAN` and the monthly rule uses `FULL_SCAN`.
+ `scan_settings` is specified at the plan level (not inside a rule). It configures the scanner role and resource types to scan.
+ The `scanner_role_arn` must reference an IAM role with the `AWSBackupGuardDutyRolePolicyForScans` managed policy attached and a trust policy that allows the `malware-protection.guardduty.amazonaws.com` service principal to assume the role.
# Tag policies
Tag policies allow you to standardize the tags attached to the AWS resources in your organization's accounts.
You can use tag policies to maintain consistent tags, including the preferred case treatment of tag keys and tag values.
## What are tags?
*Tags* are custom attribute labels that you assign or that AWS assigns to AWS resources. Each tag has two parts:
+ A *tag key* (for example, `CostCenter`, `Environment`, or `Project`). Tag keys are case sensitive.
+ An optional field known as a *tag value* (for example, `111122223333` or `Production`). Omitting the tag value is the same as using an empty string. Like tag keys, tag values are case sensitive.
The rest of this page describes tag policies. For more information about tags, see the following sources:
+ For general information about tagging, including naming and usage conventions, see the [https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html).
+ For a list of services that support using tags, see the [https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/Welcome.html).
+ For information about using tags to categorize resources, see the [https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/tagging-best-practices.html).
+ For information on tagging Organizations resources, see [Tagging AWS Organizations resourcesConsiderations](orgs_tagging.md).
+ For information on tagging resources in other AWS services, see the documentation for that service.
## What are tag policies?
*Tag policies* are a type of policy that can help you standardize tags across resources in your organization's accounts. In a tag policy, you specify tagging rules applicable to resources when they are tagged.
For example, a tag policy can specify that when the `CostCenter` tag is attached to a resource, it must use the case treatment and tag values that the tag policy defines. A tag policy can also specify that noncompliant tagging operations on specified resource types are *enforced*. In other words, noncompliant tagging requests on specified resource types are prevented from completing. Untagged resources or tags that aren't defined in the tag policy aren't evaluated for compliance with the tag policy.
Using tag policies involves working with multiple AWS services:
+ Use **AWS Organizations** to manage *tag policies*. When you sign in to the organization's management account, you use Organizations to enable the tag policies feature. You must sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account. Then you can create tag policies and attach them to the organization entities to put those tagging rules in effect.
+ Use **AWS Resource Groups** to manage *compliance* with tag policies. When you sign in to an account in your organization, you use Resource Groups to find noncompliant tags on resources in the account. You can correct noncompliant tags in the AWS service where you created the resource. You can also use the [Tag Editor](https://docs.aws.amazon.com/tag-editor/latest/userguide/tag-editor.html) and the [Resource Groups Tagging](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/overview.html) API to tag and untag resources from multiples services.
If you sign in to the management account in your organization, you can view compliance information for all your organization's accounts.
Tag policies are available only in an organization that has [all features enabled](orgs_manage_org_support-all-features.md). For more information on what's required to use tag policies, see [Prerequisites and permissions for management policies for AWS Organizations](orgs_manage_policies_prereqs.md).
**Important**
To get started with tag policies, AWS strongly recommends that you follow the example workflow described in [Getting started with tag policies](orgs_manage_policies_tag-policies-getting-started.md) before moving on to more advanced tag policies. It's best to understand the effects of attaching a simple tag policy to a single account before expanding tag policies to an entire OU or organization. It's especially important to understand a tag policy's effects before you *enforce* compliance with any tag policy. The tables on the [Getting started with tag policies](orgs_manage_policies_tag-policies-getting-started.md) page also provide links to instructions for more advanced policy-related tasks.
# Best practices for using tag policies
AWS recommends the following best practices for using tag policies.
## Decide on a tag capitalization strategy
Determine how you want to capitalize tags and consistently implement that strategy across all resource types. For example, decide whether to use `Costcenter`, `costcenter`, or `CostCenter`, and use the same convention for all tags. For consistent results in compliance reports, avoid using similar tags with inconsistent case treatment. This strategy will help you define tag policies for your organization.
## Use the recommended workflow
Start small by creating a simple tag policy. Then attach it to a member account that you can use for testing purposes. Use the workflows described in [Getting started with tag policies](orgs_manage_policies_tag-policies-getting-started.md).
## Determine tagging rules
This will depend on your organization's needs. For example, you may want to specify that when a `CostCenter` tag is attached to AWS Secrets Manager secrets, it must use the specified case treatment. Create tag policies that define compliant tags and attach them to the organization entities where you want those tagging rules to be in effect.
## Educate account administrators
When you're ready to expand your use of tag policies, educate account administrators as follows:
+ Communicate your tagging strategy.
+ Emphasize that administrators need to use tags on specific resource types.
This is important, as untagged resources don't show as noncompliant in compliance results.
+ Provide guidance on checking compliance with tag policies. Instruct administrators to find and correct noncompliant tags on resources in their account using the procedure described in [Evaluating Compliance for an Account](https://docs.aws.amazon.com/tag-editor/latest/userguide/tag-policies-orgs-finding-noncompliant-tags.html) in the *Tagging AWS Resource User Guide.* Let them know how often you want them to check for compliance.
## Use caution in enforcing compliance
Enforcing compliance could prevent users in your organization's accounts from tagging the resources they need. Review the information in [Enforce tagging consistency](orgs_manage_policies_tag-policies-enforcement.md). Also see the workflows described in [Getting started with tag policies](orgs_manage_policies_tag-policies-getting-started.md).
## Be aware of tagging limits
AWS services generally have a limit of 50 user-defined tags that cannot be modified. When using features like Report Required Tags, ensure your organization's effective policies don't exceed 50 required tags for any given resource type. Exceeding this limit can cause two issues: resources may be unable to achieve compliance status in compliance summaries, and Infrastructure as Code (IaC) platforms may fail to create resources when more than 50 tags are defined as required.
## Consider creating an SCP to set guardrails around resource creation requests
Resources that have never had tags attached to them don't show as noncompliant in reports. Account administrators can still create untagged resources. In some cases, you can use a service control policy (SCP) to set guardrails around resource creation requests.
To learn whether an AWS service supports controlling access using tags, see [AWS services That Work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the *IAM User Guide*. Look for the services that have **Yes **in the **ABAC (authorization based on tags)** column. Choose the name of the service to view the authorization and access control documentation for that service.
# Getting started with tag policies
Using tag policies involves working with multiple AWS services. To get started, review the following pages. Then follow the workflows on this page to get familiar with tag policies and their effects.
+ [Prerequisites and permissions for management policies for AWS Organizations](orgs_manage_policies_prereqs.md)
+ [Best practices for using tag policies](orgs_manage_policies_tag-policies-best-practices.md)
## Using tag policies for the first time
Follow these steps to get started using tag policies for the first time.
| Task | Account to sign in to | AWS service console to use |
| --- | --- | --- |
| Step 1: [Enable tag policies for your organization.](enable-policy-type.md) | The organization's management account.¹ | [AWS Organizations](https://console.aws.amazon.com/organizations/) |
| Step 2: [Create a tag policy](orgs_policies_create.md#create-tag-policy-procedure). Keep your first tag policy simple. Enter one tag key in the case treatment you want to use and leave all other options at their defaults. | The organization's management account.¹ | [AWS Organizations](https://console.aws.amazon.com/organizations/) |
| Step 3: [Attach a tag policy to a single member account that you can use for testing.](orgs_policies_attach.md) You'll need to sign in to this account in the next step. | The organization's management account.¹ | [AWS Organizations](https://console.aws.amazon.com/organizations/) |
| Step 4: Create some resources with compliant tags and some with noncompliant tags. | The member account that you're using for testing purposes. | Any AWS service that you are comfortable with. For example, you can use [AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/) and follow the procedure in [Creating a Basic Secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) to create secrets with compliant and non-compliant secrets. |
| Step 5: [View the effective tag policy and evaluate the compliance status of the account.](https://docs.aws.amazon.com/tag-editor/latest/userguide/tag-policies-orgs-finding-noncompliant-tags.html) | The member account that you're using for testing purposes. | [Resource Groups](https://console.aws.amazon.com/resource-groups/) and the AWS service where the resource was created. If you created resources with compliant and non-compliant tags, you should see the non-compliant tags in the results. |
| Step 6: Repeat the process of finding and correcting compliance issues until the resources in the test account are compliant with your tag policy. | The member account that you're using for testing purposes. | [Resource Groups](https://console.aws.amazon.com/resource-groups/) and the AWS service where the resource was created. |
| At any time, you can [ evaluate organization-wide compliance](https://docs.aws.amazon.com/ARG/latest/userguide/tag-policies-orgs-evaluating-org-wide-compliance.html). | The organization's management account.¹ | [Resource Groups](https://console.aws.amazon.com/resource-groups/) |
¹ You must sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account.
## Expanding use of tag policies
You can perform the following tasks in any order to expand your use of tag policies.
| Advanced task | Account to sign in to | AWS service console to use |
| --- | --- | --- |
| [Create more advanced tag policies](orgs_policies_create.md#create-tag-policy-procedure). Follow the same process as for first-time users, but try other tasks. For example, define additional keys or values or specify different case treatment for a tag key. You can use the information in [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md) and [Tag policy syntax](orgs_manage_policies_example-tag-policies.md#tag-policy-syntax-reference) to create more detailed tag policies. | The organization's management account.¹ | [AWS Organizations](https://console.aws.amazon.com/organizations/) |
| [Attach tag policies to additional accounts or OUs. ](orgs_policies_attach.md) Check the [effective tag policy for an account](orgs_manage_policies_effective.md) after you attach more policies to it or to any OU in which the account is a member. | The organization's management account.¹ | [AWS Organizations](https://console.aws.amazon.com/organizations/) |
| Create an SCP to require tags when anyone creates new resources. | The organization's management account.¹ | [AWS Organizations](https://console.aws.amazon.com/organizations/) |
| [ Continue to evaluate the compliance status of the account against the effective tag policy as it changes. Correct noncompliant tags. ](https://docs.aws.amazon.com/ARG/latest/userguide/tag-policies-orgs-finding-noncompliant-tags.html) | A member account with an effective tag policy. | [Resource Groups](https://console.aws.amazon.com/resource-groups/) and the AWS service where the resource was created. |
| [ Evaluate organization-wide compliance](https://docs.aws.amazon.com/ARG/latest/userguide/tag-policies-orgs-evaluating-org-wide-compliance.html). | The organization's management account.¹ | [Resource Groups](https://console.aws.amazon.com/resource-groups/) |
¹ You must sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account.
## Enforcing tag policies for the first time
To enforce tag policies for the first time, follow a workflow similar to using tag policies for the first time and use a test account.
**Warning**
Use caution in enforcing compliance. Make sure that you understand the effects of using tag policies and follow the recommended workflow. Test how enforcement works on a test account before expanding it to more accounts. Otherwise, you could prevent users in your organization's accounts from tagging the resources they need. For more information, see [Enforce tagging consistency](orgs_manage_policies_tag-policies-enforcement.md).
| Enforcement tasks | Account to sign in to | AWS service console to use |
| --- | --- | --- |
| Step 1: [Create a tag policy](orgs_policies_create.md#create-tag-policy-procedure). Keep your first enforced tag policy simple. Enter one tag key in the case treatment you want to use, and choose the **Prevent noncompliant operations for this tag** option. Then specify one resource type to enforce it on. Continuing with our earlier example, you can choose to enforce it on Secrets Manager secrets. | The organization's management account.¹ | [AWS Organizations](https://console.aws.amazon.com/organizations/) |
| Step 2: [Attach a tag policy to a single, test account.](orgs_policies_attach.md) | The organization's management account.¹ | [AWS Organizations](https://console.aws.amazon.com/organizations/) |
| Step 3: Try creating some resources with compliant tags, and some with noncompliant tags. You shouldn't be allowed to create a tag on a resource of the type specified in the tag policy with a noncompliant tag. | The member account that you're using for testing purposes. | Any AWS service that you are comfortable with. For example, you can use [AWS Secrets Manager](https://console.aws.amazon.com/secretsmanager/) and follow the procedure in [Creating a Basic Secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) to create secrets with compliant and non-compliant secrets. |
| Step 4: [ Evaluate the compliance status of the account against the effective tag policy and correct noncompliant tags. ](https://docs.aws.amazon.com/ARG/latest/userguide/tag-policies-orgs-finding-noncompliant-tags.html) | The member account that you're using for testing purposes. | [Resource Groups](https://console.aws.amazon.com/resource-groups/) and the AWS service where the resource was created. |
| Step 5: Repeat the process of finding and correcting compliance issues until the resources in the test account are compliant with your tag policy. | The member account that you're using for testing purposes. | [Resource Groups](https://console.aws.amazon.com/resource-groups/) and the AWS service where the resource was created. |
| At any time, you can [ evaluate organization-wide compliance](https://docs.aws.amazon.com/ARG/latest/userguide/tag-policies-orgs-evaluating-org-wide-compliance.html). | The organization's management account.¹ | [Resource Groups](https://console.aws.amazon.com/resource-groups/) |
¹ You must sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account.
# Report tagging compliance
Tag policies provide reporting mode for "Basic compliance rules" and "Required tag key". You can use this mode to evaluate the compliance of an account in your organization with its effective tag policy. The generated report includes only resources that have had at least one user-defined tag at any point in their lifecycle.
**Important**
Untagged resources don't appear as non-compliant in results.
To find untagged resources in your account, use AWS Resource Explorer with a query that uses `tag:none`. For more information, see [Search for untagged resources](https://docs.aws.amazon.com/resource-explorer/latest/userguide/using-search-query-examples.html#example-1) in the *AWS Resource Explorer User Guide*.
**Topics**
+ [Reporting for "Basic compliance rules"](#reporting-basic-compliance-rules)
+ [Reporting for "Required tag key"](#reporting-required-tag-key)
+ [Generating an organization-wide compliance report](enforcement-report.md)
## Reporting for "Basic compliance rules"
With reporting for basic compliance rules, you can generate a tagging compliance report that checks for compliance against capitalization and allowed tag values.
**To report,**
From the Visual editor tab, enter the value for the tag key that you want to report compliance against. The screenshot below shows a customer compliance report for the "CostCenter" tag key. In this example, the report will highlight a tagged resource as compliant if it matches only a lowercase value of the "CostCenter" tag key, meaning the string is equal to "costcenter".
![\[Visual editor tab showing tag policy configuration for CostCenter tag with Legal and HR values\]](http://docs.aws.amazon.com/organizations/latest/userguide/images/tag-policies-basic-compliance-reporting.png)
The JSON below generates a compliance report for resources against a lowercase value of the "CostCenter" tag key.
```
{
"tags": {
"CostCenter": {}
}
}
```
**To report on capitalization,**
From the Visual editor tab, enter the value for the tag key that you want to report compliance against, and select the Capitalization option. The screenshot below shows a customer compliance report for the "CostCenter" tag key with capitalization. In this example, the report will highlight a tagged resource as compliant if it is an exact string match to the "CostCenter" tag key.
![\[Visual editor tab showing tag policy configuration for CostCenter tag with capitalization\]](http://docs.aws.amazon.com/organizations/latest/userguide/images/tag-policies-basic-compliance-capitalization.png)
The JSON below generates a compliance report for resources against the "CostCenter" tag key with capitalization.
```
{
"tags": {
"CostCenter": {
"tag_key": {
"@@assign": "CostCenter"
}
}
}
}
```
**To report on allowed tag values with capitalization,**
From the Visual editor tab, enter the value for the tag key that you want to report compliance against, select the Allowed values option, and enter values for allowed tag values. The screenshot below shows a customer compliance report for the "CostCenter" tag key with capitalization and allowed tag values. In this example, the report will highlight a tagged resource as compliant if it is an exact string match to the "CostCenter" tag key, and the tag value is either "HR" or "Legal".
![\[Visual editor tab showing tag policy configuration for CostCenter tag with capitalization and allowed tag values HR and Legal\]](http://docs.aws.amazon.com/organizations/latest/userguide/images/tag-policies-basic-compliance-allowed-tag-values-with-capitalization.png)
The JSON below generates a compliance report for resources against the "CostCenter" tag key with capitalization and allowed tag values "HR" and "Legal".
```
{
"tags": {
"CostCenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"tag_value": {
"@@assign": [
"HR",
"Legal"
]
}
}
}
}
```
## Reporting for "Required tag key"
**Warning**
The AWS Resource Groups console does not currently support reporting for required tag keys when evaluating compliance for an account. Noncompliant resources that are missing a required tag key will not appear in **Resources with noncompliant tags** section and will not mark the account as noncompliant. Use organization-wide compliance report instead to find noncompliant resources that are missing a required tag key.
With reporting for required tag keys, you can evaluate whether your resource creation operation is missing required or mandatory tag keys. Run the following command in your CLI to list required tag keys that are defined in the account's effective tag policy. You can use this information to manually verify that you are creating a resource with all required tags as defined by your account administrator.
```
$ aws resourcegroupstaggingapi list-required-tags
```
**To report required tag keys,**
From the Visual editor tab, enter the value for the tag key that you want to report compliance against, and select the **Mark tag as required for reporting** option. The screenshot below shows a customer compliance report for the "CostCenter" tag key with capitalization and reporting for required tag key. In this example, the report will highlight a tagged resource as compliant if it contains the exact string "CostCenter" as a tag key.
**Important**
You need to select both Capitalization and Mark tags as required for reporting options to generate a report of selected resource types that are missing the exact required tags. For example, you will use both of these options when you are trying to check for an exact match to the "CostCenter" tag key.
You can select only the Mark tags as required for reporting option to generate a report of selected resource types that are missing the required tags. In this scenario, the generated report will mark resources as compliant if they have "CostCenter", "costCenter", "Costcenter", "costcenter", or any similar variation. This feature allows you to generate compliance reports for selected resource types, instead of all tagged resources in your account.
Selecting only Capitalization will generate a report for ALL tagged resources, and mark those resources as non-compliant if the tag key does not have an exact string match.
![\[Visual editor tab showing tag policy configuration for required tag reporting\]](http://docs.aws.amazon.com/organizations/latest/userguide/images/tag-policies-basic-compliance-required-tag.png)
The JSON below generates a compliance report for resources against the "CostCenter" tag key with capitalization and mark tag as required for reporting.
```
{
"tags": {
"CostCenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"report_required_tag_for": {
"@@assign": [
"ec2:ALL_SUPPORTED"
]
}
}
}
}
```
**To enforce,**
You can use reporting with IaC tools such as CloudFormation, Terraform, and Pulumi to warn your developers or block deployments with missing required tags. You can now use one effective tag policy that works across CloudFormation, Terraform, and Pulumi. See [Enforce "Required tag key" with IaC](enforce-required-tag-keys-iac.md) for more details.
# Generating an organization-wide compliance report
At any time, you can generate a report that lists all tagged resources in the AWS accounts across your organization. The report shows whether each resource is compliant with the effective tag policy. Note that it can take up to 48 hours for changes you make to a tag policy or resources to be reflected in the organization-wide compliance report. For example, if you have a tag policy that defines a new standardized tag for a resource type, resources of that type that don't have this tag are shown as compliant in the report for up to 48 hours.
You can generate the report from your organization's management account in the `us-east-1` Region, provided that it has access to an Amazon S3 bucket. The bucket must have an attached bucket policy as shown in [Amazon S3 Bucket Policy for Storing Report](https://docs.aws.amazon.com/ARG/latest/userguide/tag-policies-prereqs.html#bucket-policy). To generate the report, run the following command:
```
$ aws resourcegroupstaggingapi start-report-creation --region us-east-1
```
You can generate one report at a time.
This report can take some time to complete. You can check the status by running the following command:
```
$ aws resourcegroupstaggingapi describe-report-creation --region us-east-1
{
"Status": "SUCCEEDED"
}
```
After the above command returns `SUCCEEDED`, you can open the report from the Amazon S3 bucket.
# Enforce tagging consistency
Tag policies provide two capabilities to help you enforce tagging consistency across your AWS environments: "Basic compliance rules" and "Required tag key". You can use these capabilities with two tag policy modes: enforcement and reporting. This section highlights enforcement mode for both capabilities. For details on reporting mode for both capabilities, see "Reporting tagging compliance".
**Topics**
+ [Enforce for "Basic compliance rules"](#basic-compliance-rules)
+ [Best practices](#best-practices)
+ [Enforce "Required tag key" with IaC](enforce-required-tag-keys-iac.md)
+ [Tag policy syntax and examples](orgs_manage_policies_example-tag-policies.md)
## Enforce for "Basic compliance rules"
With enforcement for basic compliance rules, you can prevent resource creation with tag values that do not meet the requirements specified in your tag policy. For example, you can define a policy that blocks Amazon EC2 create operations if the supplied 'CostCenter' tag key does not have a tag value of "Business" or "Legal". Basic compliance rules also allow you to apply enforcement based on capitalization of tag keys. Enabling capitalization ensures that tag keys are an exact string match. Capitalization treats "CostCenter", "costCenter", and "Costcenter" as unique tag keys, meaning tag key enforcement is case sensitive. Capitalization enforcement prevents teams from accidentally creating tag variations. Tagging consistency is critical for both cost tracking accuracy and attribute-based access control (ABAC) security policies that rely on precise tag matching to grant or deny resource access.
**Important**
Basic compliance rules do not enforce tag compliance on resources that are created without tags. This capability does not enforce missing tag keys. You cannot use this capability to ensure that required or mandatory tag keys are configured at resource creation. Use reporting mode in "Required tag keys" to enforce required tag keys for resources created by IaC tools such as CloudFormation, Terraform, and Pulumi. Use SCPs to prevent IAM users and roles in target accounts from creating certain resource types if the request doesn't include the specified tags.
To enforce basic compliance rules with tag policies, do one of the following when you [create a tag policy](orgs_policies_create.md):
+ From the **Visual editor** tab, select the option **Prevent noncompliant operations for this tag**. See [Create a tag policy](orgs_policies_create.md) section for steps on how to author and attach a tag policy.
+ From the **JSON** tab, use the `enforced_for` field. For information on tag policy syntax, see [Tag policy syntax and examples](orgs_manage_policies_example-tag-policies.md).
The image below shows the console experience of the Visual editor tab. In this example, the customer is defining a tag policy that will enforce tag value validation only for Amazon EC2 resource types that are supported by tag policies. This policy will check if the tag value is either "Legal" or "HR" when the supplied tag key is "CostCenter" for Amazon EC2 resource types. This policy also enforces capitalization, which means that the policy is looking for an exact string match to the "CostCenter" tag key.
![\[Visual editor tab showing tag policy configuration for CostCenter tag with Legal and HR values\]](http://docs.aws.amazon.com/organizations/latest/userguide/images/tag-policies-basic-compliance.png)
The JSON below is the generated tag policy from the above "CostCenter" example.
**Important**
We recommend that you use the Visual editor when you are defining your tag policy for the first time. The Visual editor ensures that your tag policy syntax is valid, with no additional steps, and gives you a simplified clickable experience to define your tag policy. You can use either the Visual editor or JSON tab to define your tag policy.
```
{
"tags": {
"CostCenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"tag_value": {
"@@assign": [
"HR",
"Legal"
]
},
"enforced_for": {
"@@assign": [
"ec2:ALL_SUPPORTED"
]
}
}
}
}
```
## Best practices
Follow these best practices for enforcement with "Basic compliance rules" and "Required tag keys for IaC" with tag policies:
+ **Use caution when enforcing compliance** – Make sure you understand the effects of using tag policies and follow the recommended workflows described in [Getting started with tag policies](orgs_manage_policies_tag-policies-getting-started.md). Test how enforcement works on a test account before expanding it to more accounts or organizational units. Otherwise, you could prevent users in your organization's accounts from creating the resources they need.
+ **Be aware of what resource types you can enforce on** – You can only enforce compliance with tag policies on [supported resource types](orgs_manage_policies_supported-resources-enforcement.md). Resource types that support enforcing compliance are listed when you use the visual editor to build a tag policy.
+ **Understand interactions with some services** – Some AWS services have container-like groupings of resources that automatically create resources for you and propagate tags from a resource in one service to another. For example, tags on Amazon EC2 groups and Amazon EMR clusters can automatically propagate to the contained Amazon EC2 instances. You may have tag policies for Amazon EC2 that are more strict than for groups or Amazon EMR clusters. If you enable enforcement, the tag policy prevents resources from being tagged and may block dynamic scaling and provisioning.
The following sections show how you can find non-compliant resources, and correct them to be compliant.
**Topics**
+ [Identify and remediate tagging inconsistencies](orgs_manage_policies_tag-policies-identify-remediate.md)
# Enforce "Required tag key" with IaC
Tag policies help you maintain consistent tagging across your infrastructure as code (IaC) deployments. With "Required tag keys", you can ensure that all resources created through IaC tools like CloudFormation, Terraform, and Pulumi include the mandatory tags defined by your organization.
This capability checks your IaC deployments against your organization's tag policies before resources are created. When a deployment is missing required tags, you can configure your IaC settings to either warn your development teams or prevent the deployment entirely. This proactive approach maintains tagging compliance from the moment resources are created, rather than requiring manual remediation later. The enforcement works across multiple IaC tools using a single tag policy definition, eliminating the need to configure separate tagging rules for each tool your organization uses.
**Topics**
+ [Enforce with CloudFormation](#enforce-with-cloudformation)
+ [Enforce with Terraform](#enforce-with-terraform)
+ [Enforce with Pulumi](#enforce-with-pulumi)
## Enforce with CloudFormation
**Note**
To enforce required tag keys with CloudFormation, you must specify required tags for your resource type in tag policies. See the [Reporting for "Required tag key"](orgs_manage_policies_tag-policies-report-tagging-compliance.md#reporting-required-tag-key) section for more details.
**Setup Execution Role for the AWS::TagPolicies::TaggingComplianceValidator Hook**
Before activating the `AWS::TagPolicies::TaggingComplianceValidator` hook, you must create an execution role that the hook uses to access AWS services. The role must have the following Trust Policy attached to it:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"resources.cloudformation.amazonaws.com",
"hooks.cloudformation.amazonaws.com"
]
},
"Action": [
"sts:AssumeRole"
]
}
]
}
```
The execution role must also have a Role Policy with at least the following permissions:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"tag:ListRequiredTags"
],
"Resource": "*"
}
]
}
```
For more information about setting up execution roles for public extensions, see [Configure an execution role with IAM permissions and a trust policy for public extension access](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/registry-public.html#registry-public-enable-execution-role) in the CloudFormation User Guide.
**Activate the AWS::TagPolicies::TaggingComplianceValidator Hook**
**Important**
Before you continue, verify that you have the permissions required to work with Hooks and view proactive controls from the CloudFormation console. For more information, see [Grant IAM permissions for CloudFormation Hooks](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/grant-iam-permissions-for-hooks.html).
After updating your tag policy, you must activate the `AWS::TagPolicies::TaggingComplianceValidator` hook in every AWS account and Region where you want to enforce required tagging compliance.
This AWS-managed hook can be configured in two modes:
+ **Warn mode**: Allows deployments to proceed but generates warnings when required tags are missing
+ **Fail mode**: Blocks deployments that are missing required tags
To activate the hook using the AWS CLI:
```
aws cloudformation activate-type \
--type HOOK \
--type-name AWS::TagPolicies::TaggingComplianceValidator \
--execution-role-arn arn:aws:iam::123456789012:role/MyHookExecutionRole \
--publisher-id aws-hooks \
--region us-east-1
```
```
aws cloudformation set-type-configuration \
--configuration '{"CloudFormationConfiguration":{"HookConfiguration":{"HookInvocationStatus": "ENABLED", "FailureMode": "WARN", "TargetOperations": ["STACK"], "Properties":{}}}}' \
--type-arn "arn:aws:cloudformation:us-east-1:123456789012:type/hook/AWS-TagPolicies-TaggingComplianceValidator" \
--region us-east-1
```
Replace `region` with your target AWS region, and change `"FailureMode":"FAIL"` to `"FailureMode":"WARN"` if you prefer warning mode.
**Activate the AWS::TagPolicies::TaggingComplianceValidator Hook across multiple accounts and Regions with CloudFormation StackSets**
For organizations with multiple AWS accounts, you can use AWS CloudFormation StackSets to activate the tagging compliance hook across all your accounts and Regions simultaneously.
CloudFormation StackSets allow you to deploy the same CloudFormation template to multiple accounts and Regions with a single operation. This approach ensures consistent tagging enforcement across your entire AWS organization without requiring manual configuration in each account.
To use CloudFormation StackSets for this purpose:
1. Create a CloudFormation template that activates the tagging compliance hook
1. Deploy the template using CloudFormation StackSets to target your organizational units or specific accounts
1. Specify all Regions where you want enforcement enabled
The CloudFormation StackSets deployment will automatically handle the activation process across all specified accounts and Regions, ensuring uniform tagging compliance throughout your organization. To learn how to deploy CloudFormation Hooks to an Organization with service-managed CloudFormation StackSets, see this [AWS blog](https://aws.amazon.com/blogs/devops/deploy-cloudformation-hooks-to-an-organization-with-service-managed-stacksets/).
*Deploy the CloudFormation template below using CloudFormation StackSets to activate the AWS::TagPolicies::TaggingComplianceValidator Hook for accounts in your organization.*
**Important**
This hook only functions as a StackHook. It has no effect when used as a resource hook.
```
Resources:
# Activate the AWS-managed hook type
HookTypeActivation:
Type: AWS::CloudFormation::TypeActivation
Properties:
AutoUpdate: True
PublisherId: "AWS"
TypeName: "AWS::TagPolicies::TaggingComplianceValidator"
# Configure the hook
HookTypeConfiguration:
Type: AWS::CloudFormation::HookTypeConfig
DependsOn: HookTypeActivation
Properties:
TypeName: "AWS::TagPolicies::TaggingComplianceValidator"
TypeArn: !GetAtt HookTypeActivation.Arn
Configuration: !Sub |
{
"CloudFormationConfiguration": {
"HookConfiguration": {
"TargetStacks": "ALL",
"TargetOperations": ["STACK"],
"Properties": {},
"FailureMode": "Warn",
"TargetFilters": {
"Actions": [
"CREATE",
"UPDATE"
]}
}
}
}
```
**Note**
For more information on running CloudFormation hooks, see [Activate a proactive control-based Hook in your account](https://docs.aws.amazon.com/cloudformation-cli/latest/hooks-userguide/proactive-controls-hooks-activate-hooks.html).
## Enforce with Terraform
To enforce required tag keys with Terraform, you need to update your Terraform AWS Provider to 6.22.0 or above and enable tag policy validation in your provider configuration. For implementation details and configuration examples, see the [ Terraform AWS Provider documentation on tag policy enforcement](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/tag-policy-compliance).
## Enforce with Pulumi
To enforce required tag keys with Pulumi, you need to enable the Tag Policy Reporting policy pack in Pulumi Cloud and configure your IAM role with tag policy read permissions. For implementation details and configuration examples, see the [ Pulumi documentation on tag policy enforcement](https://www.pulumi.com/docs/insights/policy/integrations/aws-organizations-tag-policies/#aws-organizations-tag-policies).
# Tag policy syntax and examples
This page describes tag policy syntax and provides examples.
**Topics**
+ [Tag policy syntax](#tag-policy-syntax-reference)
+ [Tag policy examples](#tag-policy-examples)
+ [Example 1: Define organization-wide tag key case](#tag-policy-example-key-case)
+ [Example 2: Prevent use of a tag key](#tag-policy-example-prevent-key)
+ [Example 3: Specify a tag policy for all supported resource types of a specific AWS service](#tag-policy-example-all-supported)
+ [Example 4: Enforce required tag keys for compliance](#tag-policy-example-required-tags)
## Tag policy syntax
A tag policy is a plaintext file that is structured according to the rules of [JSON](http://json.org). The syntax for tag policies follows the syntax for management policy types. For a complete discussion of that syntax, see [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md). This topic focuses on applying that general syntax to the specific requirements of the tag policy type.
The following tag policy shows basic tag policy syntax:
```
{
"tags": {
"costcenter": {
"tag_key": {
"@@assign": "CostCenter"
},
"tag_value": {
"@@assign": [
"100",
"200",
"300*"
]
},
"enforced_for": {
"@@assign": [
"secretsmanager:ALL_SUPPORTED"
]
}
}
}
}
```
Tag policy syntax includes the following elements:
+ The `tags` field key name. Tag policies always start with this fixed key name. It's the top line in the example policy above.
+ A *policy key* that uniquely identifies the policy statement. It must match the value for the *tag key*, except for the case treatment. The policy value is case sensitive.
In this example, `costcenter` is the policy key.
+ At least one *tag key* that specifies the allowed tag key with the capitalization that you want resources to be compliant with. If case treatment isn't defined, lowercase is the default case treatment for tag keys. The value for the tag key must match the value for the policy key. But since the policy key value is case insensitive, the capitalization can be different.
In this example, `CostCenter` is the tag key. This is the case treatment that is required for compliance with the tag policy. Resources with alternate case treatment for this tag key are noncompliant with the tag policy.
You can define multiple tag keys in a tag policy.
+ (Optional) A list of one or more acceptable *tag values* for the tag key. If the tag policy doesn't specify a tag value for a tag key, any value (including no value at all) is considered compliant.
In this example, acceptable values for the `CostCenter` tag key are `100`, `200`, and `300*`.
+ (Optional) An `enforced_for` option that indicates whether to prevent any noncompliant tagging operations on specified services and resources. In the console, this is the **Prevent noncompliant operations for this tag** option in the visual editor for creating tag policies. The default setting for this option is null.
The example tag policy specifies that the `CostCenter` tag applied to all AWS Secrets Manager resources must be compliant with this policy.
**Warning**
You should only change this option from the default if you are experienced with using tag policies. Otherwise, you could prevent users in your organization's accounts from creating the resources they need.
+ *Operators* that specify how the tag policy merges with other tag policies within the organization tree to create an account's [effective tag policy](orgs_manage_policies_effective.md). In this example, `@@assign` is used to assign strings to `tag_key`, `tag_value`, and `enforced_for`. For more information about operators, see [Inheritance operators](policy-operators.md).
+ You can use the `*` wildcard in tag values.
+ You can use only one wildcard per tag value. For example, `*@example.com` is allowed, but `*@*.com` is not.
+ You can use the `ALL_SUPPORTED` wildcard in the `enforced_for` field with some services to enable enforcement for all supported resources for that service. For a list of services and resource types that support `enforced_for`, see [Services and resource types that support enforcement](orgs_manage_policies_supported-resources-enforcement.md).
+ You can't use a wildcard to specify all services or to specify a resource for all services.
## Tag policy examples
The example [tag policies](orgs_manage_policies_tag-policies.md) that follow are for information purposes only.
**Note**
Before you attempt to use these example tag policies in your organization, note the following:
Make sure that you've followed the [recommended workflow](orgs_manage_policies_tag-policies-getting-started.md) for getting started with tag policies.
You should carefully review and customize these tag policies for your unique requirements.
All characters in your tag policy are subject to a [maximum size](orgs_reference_limits.md#min-max-values). The examples in this guide show tag policies formatted with extra white space to improve their readability. However, to save space if your policy size approaches the maximum size, you can delete any white space. Examples of white space include space characters and line breaks that are outside quotation marks.
Untagged resources don't appear as noncompliant in results.
## Example 1: Define organization-wide tag key case
The following example shows a tag policy that only defines two tag keys and the capitalization that you want accounts in your organization to standardize on.
**Policy A – organization root tag policy**
```
{
"tags": {
"CostCenter": {
"tag_key": {
"@@assign": "CostCenter",
"@@operators_allowed_for_child_policies": ["@@none"]
}
},
"Project": {
"tag_key": {
"@@assign": "Project",
"@@operators_allowed_for_child_policies": ["@@none"]
}
}
}
}
```
This tag policy defines two tag keys: `CostCenter` and `Project`. Attaching this tag policy to the organization root has the following effects:
+ All accounts in your organization inherit this tag policy.
+ All accounts in your organization must use the defined case treatment for compliance. Resources with `CostCenter` and `Project` tags are compliant. Resources with alternate case treatment for the tag key (for example, `costcenter`, `Costcenter`, or `COSTCENTER`) are noncompliant.
+ The `@@operators_allowed_for_child_policies": ["@@none"]` lines lock down the tag keys. Tag policies that are attached lower in the organization tree (child policies) can't use value-setting operators to change the tag key, including its case treatment.
+ As with all tag policies, untagged resources or tags that aren't defined in the tag policy aren't evaluated for compliance with the tag policy.
AWS recommends that you use this example as a guide in creating a similar tag policy for tag keys that you want to use. Attach it to the organization root. Then create a tag policy similar to the next example, which only defines the acceptable values for the defined tag keys.
### Next step: Define values
Assume that you attached the previous tag policy to the organization root. Next, you can create a tag policy like the following and attach it to an account. This policy defines acceptable values for the `CostCenter` and `Project` tag keys.
**Policy B – account tag policy**
```
{
"tags": {
"CostCenter": {
"tag_value": {
"@@assign": [
"Production",
"Test"
]
}
},
"Project": {
"tag_value": {
"@@assign": [
"A",
"B"
]
}
}
}
}
```
If you attach Policy A to the organization root and Policy B to an account, the policies combine to create the following effective tag policy for the account:
**Policy A \$1 Policy B = effective tag policy for account**
```
{
"tags": {
"Project": {
"tag_value": [
"A",
"B"
],
"tag_key": "Project"
},
"CostCenter": {
"tag_value": [
"Production",
"Test"
],
"tag_key": "CostCenter"
}
}
}
```
For more information about policy inheritance, including examples of how the inheritance operators work and example effective tag policies, see [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md).
## Example 2: Prevent use of a tag key
To prevent the use of a tag key, you can attach a tag policy like the following to an organization entity.
This example policy specifies that no values are acceptable for the `Color` tag key. It also specifies that no [operators](policy-operators.md) are allowed in child tag policies. Therefore, any `Color` tags on resources in affected accounts are considered non-compliant. However, the `enforced_for` option actually prevents affected accounts from tagging ***only*** Amazon DynamoDB tables with the `Color` tag.
```
{
"tags": {
"Color": {
"tag_key": {
"@@operators_allowed_for_child_policies": [
"@@none"
],
"@@assign": "Color"
},
"tag_value": {
"@@operators_allowed_for_child_policies": [
"@@none"
],
"@@assign": []
},
"enforced_for": {
"@@assign": [
"dynamodb:table"
]
}
}
}
}
```
## Example 3: Specify a tag policy for all supported resource types of a specific AWS service
To specify a tag policy for all supported resource types of a specific AWS service, you use the `ALL_SUPPORTED` wildcard.
This policy uses the `ALL_SUPPORTED` wildcard to specify that all Amazon EC2 instances with the tag key `Environment` can only have a tag value of `Prod` or `Non-prod`. This wildcard provides an effective, single-line alternative to listing each Amazon EC2 instance individually. For a list of services and resource types that support the `ALL_SUPPORTED` wildcard, see [Services and resource types that support enforcement](orgs_manage_policies_supported-resources-enforcement.md).
```
{
"tags": {
"Environment": {
"tag_key": {
"@@assign": "Environment",
"@@operators_allowed_for_child_policies": ["@@none"]
},
"tag_value": {
"@@assign": [
"Prod",
"Non-prod"
],
"@@operators_allowed_for_child_policies": ["@@none"]
},
"enforced_for": {
"@@assign": [
"ec2:ALL_SUPPORTED"
]
}
}
}
}
```
## Example 4: Enforce required tag keys for compliance
This example demonstrates how to define a tag policy that requires all resources to include mandatory compliance tags. Organizations commonly use this pattern to ensure proper cost allocation, ownership tracking, and environment identification.
```
{
"tags": {
"CostCenter": {
"report_required_tag_for": {
"@@assign": [
"ec2:instance",
"s3:bucket",
"rds:db",
"lambda:function"
]
},
"tag_key": {
"@@assign": "CostCenter"
}
},
"Environment": {
"report_required_tag_for": {
"@@assign": [
"ec2:ALL_SUPPORTED",
"rds:ALL_SUPPORTED",
"s3:ALL_SUPPORTED"
]
},
"tag_key": {
"@@assign": "Environment"
},
"tag_value": {
"@@assign": [
"Production",
"Staging",
"Development",
"Test"
]
}
},
"Owner": {
"report_required_tag_for": {
"@@assign": [
"ec2:ALL_SUPPORTED"
]
},
"tag_key": {
"@@assign": "Owner"
}
}
}
}
```
When you apply this policy and configure your IaC tool with tag policy enforcement:
+ CostCenter: Required for EC2 instances, S3 buckets, RDS databases, and Lambda functions
+ Environment: Required for all EC2, RDS, and S3 resources, with allowed values restricted to Production, Staging, Development, or Test
+ Owner: Required for all EC2 resources in your organization
Example infrastructure code that complies with this policy:
```
EC2Instance:
Type: AWS::EC2::Instance
Properties:
ImageId: ami-0c02fb55956c7d316
InstanceType: t2.micro
Tags:
- Key: CostCenter
Value: CC-12345
- Key: Environment
Value: Test
- Key: Owner
Value: john.doe@company.com
```
If you attempt to create a resource without the required tags, your IaC deployment will fail or generate a warning during the planning phase, depending on your configuration. When configured in fail mode, the deployment is blocked before any resources are created. When configured in warn mode, the deployment proceeds but alerts your team to the missing tags. The validation error message identifies exactly which required tags are missing and which resources need them.
For specific configuration instructions for your IaC tool:
+ **CloudFormation**: See [Enforce with CloudFormation](enforce-required-tag-keys-iac.md#enforce-with-cloudformation) to activate the tagging compliance hook
+ **Terraform**: See [Enforce with Terraform](enforce-required-tag-keys-iac.md#enforce-with-terraform) to enable tag policy validation in the AWS Provider
+ **Pulumi**: See [Enforce with Pulumi](enforce-required-tag-keys-iac.md#enforce-with-pulumi) to enable the Tag Policy Reporting policy pack
# Identify and remediate tagging inconsistencies
After implementing tag policies in your organization, you can identify resources with non-compliant tags and remediate them to ensure consistency across your AWS environment. This section provides guidance on finding and correcting tagging inconsistencies.
**Topics**
+ [Finding untagged and mistagged resources for your organization with Resource Explorer](finding-untagged-mistagged-resources.md)
+ [Correcting non-compliant tags in resources](enforcement-correcting.md)
+ [Using Amazon EventBridge to monitor noncompliant tags](orgs_manage_policies_tag-policies-cwe.md)
# Finding untagged and mistagged resources for your organization with Resource Explorer
To find untagged resources in your account, use AWS Resource Explorer with a query that uses `tag:none`. Resource Explorer provides comprehensive search capabilities to identify resources that lack proper tagging or have inconsistent tag values across your organization.
For detailed instructions on using Resource Explorer to find untagged and mistagged resources, see [Search for untagged resources](https://docs.aws.amazon.com/resource-explorer/latest/userguide/using-search-query-examples.html#example-1) in the *AWS Resource Explorer User Guide*.
# Correcting non-compliant tags in resources
After finding non-compliant tags, make corrections using any of the following methods. You must be signed in to the account that has the resource with non-compliant tags:
+ Use the console or tagging API operations of the AWS service that created the non-compliant resources.
+ Use the AWS Resource Groups [TagResources](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_TagResources.html) and [UntagResources](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_UntagResources.html) operations to add tags that are compliant with the effective policy or to remove non-compliant tags.
# Using Amazon EventBridge to monitor noncompliant tags
You can use Amazon EventBridge, formerly Amazon CloudWatch Events, to monitor when noncompliant tags are introduced. In the following example event, the `"false"` value for `tag-policy-compliant` indicates that a new tag is noncompliant with the effective tag policy.
```
{
"detail-type": "Tag Change on Resource",
"region": "us-east-1",
"resources": [
"arn:aws:ec2:us-east-1:123456789012:instance/i-0000000aaaaaaaaaa"
],
"detail": {
"changed-tag-keys": [
"a-new-key"
],
"service": "ec2",
"resource-type": "instance",
"version": 3,
"tag-policy-compliant": "false",
"tags": {
"a-new-key": "tag-value-on-new-key-just-added"
}
}
}
```
You can subscribe to events and specify strings or patterns to monitor. For more information on EventBridge, see the *[Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/)*.
# Services and resource types that support enforcement
The following services and resource types support enforcement with tag policies:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_supported-resources-enforcement.html)
+ See [Terraform documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/guides/tag-policy-compliance) for resource type support in Terraform AWS Provider.
+ See [Pulumi documentation](https://www.pulumi.com/docs/insights/policy/integrations/aws-organizations-tag-policies/#aws-provider-types) for resource type support in Pulumi Cloud.
# Supported Regions
Tag policy features are available in the following Regions:
| Region name | Region parameter |
| --- | --- |
| US East (N. Virginia) Region¹ | **`us-east-1`** |
| US East (Ohio) Region | `us-east-2` |
| US West (N. California) Region | `us-west-1` |
| US West (Oregon) Region | `us-west-2` |
| Africa (Cape Town) Region² | `af-south-1` |
| Asia Pacific (Hong Kong) Region² | `ap-east-1` |
| Asia Pacific (Taipei)² | `ap-east-2` |
| Asia Pacific (Mumbai) Region | `ap-south-1` |
| Asia Pacific (Hyderabad)² | `ap-south-2` |
| Asia Pacific (Tokyo) Region | `ap-northeast-1` |
| Asia Pacific (Seoul) Region | `ap-northeast-2` |
| Asia Pacific (Osaka) Region | `ap-northeast-3` |
| Asia Pacific (Singapore) Region | `ap-southeast-1` |
| Asia Pacific (Sydney) Region | `ap-southeast-2` |
| Asia Pacific (Jakarta) Region² | `ap-southeast-3` |
| Asia Pacific (Melbourne)² | `ap-southeast-4` |
| Asia Pacific (Malaysia) Region | `ap-southeast-5` |
| Asia Pacific (New Zealand)² | `ap-southeast-6` |
| Asia Pacific (Thailand) | `ap-southeast-7` |
| Canada (Central) Region | `ca-central-1` |
| Canada West (Calgary)² | `ca-west-1` |
| China (Beijing) Region | `cn-north-1` |
| China (Ningxia) Region | `cn-northwest-1` |
| Europe (Frankfurt) Region | `eu-central-1` |
| Europe (Zurich) Region² | `eu-central-2` |
| Europe (Milan) Region² | `eu-south-1` |
| Europe (Spain)² | `eu-south-2` |
| Europe (Ireland) Region | `eu-west-1` |
| Europe (London) Region | `eu-west-2` |
| Europe (Paris) Region | `eu-west-3` |
| Europe (Stockholm) Region | `eu-north-1` |
| Mexico (Central) Region | `mx-central-1` |
| Middle East (UAE) Region² | `me-central-1` |
| Middle East (Bahrain) Region² | `me-south-1` |
| South America (São Paulo) Region | `sa-east-1` |
| Israel (Tel Aviv)² | `il-central-1` |
| AWS GovCloud (US-East) | `us-gov-east-1` |
| AWS GovCloud (US-West) | `us-gov-west-1` |
**¹You must specify the `us-east-1` Region when calling the following Organizations operations:**
+ [DeletePolicy](https://docs.aws.amazon.com/organizations/latest/APIReference/API_DeletePolicy.html)
+ [DisablePolicyType](https://docs.aws.amazon.com/organizations/latest/APIReference/API_DisablePolicyType.html)
+ [EnablePolicyType](https://docs.aws.amazon.com/organizations/latest/APIReference/API_EnablePolicyType.html)
+ Any other operations on an organization root, such as [ListRoots](https://docs.aws.amazon.com/organizations/latest/APIReference/API_ListRoots.html).
**You must also specify the `us-east-1` Region when calling the following Resource Groups Tagging API operations that are part of the tag policies feature:**
+ [DescribeReportCreation](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_DescribeReportCreation.html)
+ [GetComplianceSummary](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_GetComplianceSummary.html)
+ [StartReportCreation](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_StartReportCreation.html)
**Note**
To evaluate organization-wide compliance with tag policies, you must also have access to an Amazon S3 bucket in the US East (N. Virginia) Region for report storage. For more information, see [Amazon S3 bucket policy for report storage](https://docs.aws.amazon.com/ARG/latest/userguide/tag-policies-prereqs.html#bucket-policy) in the *Tagging AWS Resources User Guide*.
²These Regions must be manually enabled. To learn more about enabling and disabling AWS Regions, see [Specify which AWS Regions your account can use](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html) in the *AWS Account Management Reference Guide*. The Resource Groups console isn't available in these Regions.
# Chat applications policies
Chat applications policies in AWS Organizations enable you to control access to your organization's accounts from chat applications such as Slack and Microsoft Teams.
[Amazon Q Developer in chat applications](https://docs.aws.amazon.com/chatbot/latest/adminguide/what-is.html) is an AWS service that enables DevOps and software development teams to use messaging program chat rooms to monitor and respond to operational events in their AWS Cloud. Amazon Q Developer in chat applications processes AWS service notifications from Amazon Simple Notification Service (Amazon SNS), and forwards them to chat rooms so teams can analyze and act on them immediately, regardless of location.
## How chat applications policies work
Using chat applications policies, the management account or delegated administrator of an organization can do the following across an organization:
+ Enforce which supported chat applications (Amazon Chime, Microsoft Teams, and Slack) can be used.
+ Restrict chat client access to specific workspaces (Slack) and teams (Microsoft Teams).
+ Restrict Slack channel visibility to either public or private channels.
+ Set and enforce specific [role settings](https://docs.aws.amazon.com/chatbot/latest/adminguide/understanding-permissions.html#role-settings).
Chat applications policies restrict and take precedence over account level settings such as [role settings](https://docs.aws.amazon.com/chatbot/latest/adminguide/understanding-permissions.html#role-settings) and [channel guardrail policies](https://docs.aws.amazon.com/chatbot/latest/adminguide/understanding-permissions.html#channel-guardrails). You can access and modify chat applications policies from the Amazon Q Developer in chat applications or the Organizations console.
After the policies are attached to accounts and organizational units (OU), any current and future Amazon Q Developer in chat applications configurations for the accounts in scope will automatically comply with the governance and permissions settings. For more information, see [Understanding management policy inheritance](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_inheritance_mgmt.html).
If you try to perform an action restricted by a chat applications policy, an error message will notify you that the action is not allowed due to the chat applications policy with the recommendation to contact the management account or delegated administrator of your organization.
**Note**
Chat applications policies are validated at runtime. This means that existing resources are continuously checked for compliance. There is no overlap with existing IAM permissions since runtime-based IAM permissions for sending notifications or interacting with Amazon Q Developer in chat applications are not currently supported.
# Getting started with chat applications policies
Follow these steps to get started using chat applications policies.
1. [Learn about the permissions you must have to perform chat applications policy tasks](orgs_manage_policies_prereqs.md).
1. [Enable chat applications policies for your organization](enable-policy-type.md).
1. [Create a chat applications policy](orgs_policies_create.md).
1. [Attach the chat applications policy to your organization's root, OU, or account](orgs_policies_attach.md).
1. [View the combined effective chat applications policy that applies to an account](orgs_manage_policies_effective.md).
For all of these steps, you sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account.
**Other information**
+ [Learn chat applications policy syntax and see example policies](orgs_manage_policies_chatbot_syntax.md)
# Chat applications policy syntax and examples
This topic describes chat applications policy syntax and provides examples.
## Syntax for chat applications policies
A chat applications policy is a plaintext file that is structured according to the rules of [JSON](http://json.org). The syntax for chat applications policies follows the syntax for management policy types. For a complete discussion of that syntax, see [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md). This topic focuses on applying that general syntax to the specific requirements of the chat applications policy type.
The following example shows the basic syntax for a chat applications policy:
```
{
"chatbot":{
"platforms":{
"slack":{
"client":{
"@@assign":"enabled" // enabled | disabled
},
"workspaces": { // limit 255
"@@assign":[
"Slack-Workspace-Id"
]
},
"default":{
"supported_channel_types":{
"@@assign":[
"private" // public | private
]
},
"supported_role_settings":{
"@@assign":[
"user_role" // user_role | channel_role
]
}
},
"overrides":{ // limit 255
"Slack-Workspace-Id":{
"supported_channel_types":{
"@@assign":[
"public" // public | private
]
},
"supported_role_settings":{
"@@assign":[
"user_role" // user_role | channel_role
]
}
}
}
},
"microsoft_teams":{
"client":{
"@@assign":"enabled"
},
"tenants":{ // limit 36
"Microsoft-Teams-Tenant-Id":{ // limit 36
"@@assign":[
"Microsoft-Teams-Team-Id"
]
}
},
"default":{
"supported_role_settings":{
"@@assign":[
"user_role" // user_role | channel_role
]
}
},
"overrides":{ // limit 36
"Microsoft-Teams-Tenant-Id":{ // limit 36
"Microsoft-Teams-Team-Id":{
"supported_role_settings":{
"@@assign":[
"user_role" // user_role | channel_role
]
}
}
}
}
},
"chime":{
"client":{
"@@assign":"disabled" // enabled | disabled
}
}
},
"default":{
"client":{
"@@assign":"disabled" // enabled | disabled
}
}
}
}
```
This chat applications policy includes the following elements:
+ The `chatbot` field key name. Chat applications policies always start with this fixed key name. It's the top line in this example policy.
+ Under `chatbot`, there is a `platforms` block, which contains the configuration for the different supported chat applications: Slack, Microsoft Teams, and Amazon Chime.
+ For Slack, the following fields are available:
+ `"client"`:
+ `"enabled"`: The Slack client is enabled. Slack integrations are allowed.
+ `"disabled"`: The Slack client is disabled. Slack integrations are not allowed.
+ `"workspaces"`: Comma-separated listed of allowed Slack workspaces. In this example, the allowed Slack workspaces are *Slack-Workspace-Id1* and *Slack-Workspace-Id2*.
+ `"default"`: The default settings for Slack workspaces.
+ `"supported_channel_types"`:
+ `"public"`: Slack workspaces in scope allow public Slack channels by default.
+ `"private"`: Slack workspaces in scope allow private Slack channels by default.
+ `supported_role_settings`:
+ `"user_role"`: Slack workspaces in scope allow User level IAM roles by default.
+ `"channel_role"`: Slack workspaces in scope allow Channel level IAM roles by default.
+ `"overrides"`: The override settings for the Slack workspaces.
+ `Slack-Workspace-Id2`: Comma-separated listed of Slack workspaces where the override setting apply. In this example, the Slack workspace is *Slack-Workspace-Id2*.
+ `"supported_channel_types"`:
+ `"public"`: Override setting whether Slack workspaces in scope allow public Slack channels.
+ `"private"`: Override setting whether Slack workspaces in scope allow private Slack channels.
+ `supported_role_settings`:
+ `"user_role"`: Override setting whether Slack workspaces in scope allow User level IAM roles.
+ `"channel_role"`: Override setting whether Slack workspaces in scope allow Channel level IAM roles.
+ For Microsoft Teams, the following fields are available:
+ `"client"`:
+ `"enabled"`: The Microsoft Teams client is enabled. Microsoft Teams integrations are allowed.
+ `"disabled"`: The Microsoft Teams client is disabled. Microsoft Teams integrations are not allowed.
+ `"tenants"`: Comma-separated listed of allowed Microsoft Teams tenants. In this example, the allowed tenant is *Microsoft-Teams-Tenant-Id*.
+ `Microsoft-Teams-Tenant-Id`: Comma-separated list of allowed teams within the tenant. In this example, the allowed team is *Microsoft-Teams-Team-Id*.
+ `"default"`: The default settings for the teams within the tenant.
+ `supported_role_settings`:
+ `"user_role"`: Teams in scope allow User level IAM roles by default.
+ `"channel_role"`: Teams in scope allow Channel level IAM roles by default.
+ `"overrides"`: The override settings for the Microsoft Teams tenants.
+ `Microsoft-Teams-Tenant-Id`: Comma-separated listed of tenants where the override setting apply. In this example, the tenant is *Microsoft-Teams-Tenant-Id*.
+ `Microsoft-Teams-Team-Id`: Comma-separate listed of teams within the tenant. In this example, the allowed team is *Microsoft-Teams-Team-Id*.
+ `supported_role_settings`:
+ `"user_role"`: Override setting whether the teams in scope allow User level IAM roles.
+ `"channel_role"`: Override setting whether the teams in scope allow Channel level IAM roles.
+ For Amazon Chime, the following fields are available:
+ `"client"`:
+ `"enabled"`: The Amazon Chime client is enabled. Amazon Chime integrations are allowed.
+ `"disabled"`: The Amazon Chime client is disabled. Amazon Chime integrations are not allowed.
+ Under `chatbot`, there is a `default` block which disables Amazon Q Developer in chat applications across the organization unless overridden at a lower level. This default also disables any new chat application that Amazon Q Developer in chat applications supports. For example, if Amazon Q Developer in chat applications supports a new chat application, this default disables that newly supported chat application as well.
**Note**
For more information about Channel level IAM roles and User level IAM roles, see [Understanding Amazon Q Developer in chat applications permissions](https://docs.aws.amazon.com/chatbot/latest/adminguide/understanding-permissions.html) in the *Amazon Q Developer in chat applications Administrator Guide*.
## Chat applications policy examples
The example policies that follow are for information purposes only.
### Example 1: Allow only private Slack Channels in a specific workspace, disable Microsoft Teams, all authentication modes supported
The following policy is focused on controlling the allowed configurations for Slack and Microsoft Teams chatbot integrations.
```
{
"chatbot": {
"platforms": {
"slack": {
"client": {
"@@assign": "enabled"
},
"workspaces": {
"@@assign": [
"Slack-Workspace-Id"
]
},
"default": {
"supported_channel_types": {
"@@assign": [
"private"
]
},
"supported_role_settings": {
"@@assign": [
"channel_role",
"user_role"
]
}
}
},
"microsoft_teams": {
"client": {
"@@assign": "disabled"
}
},
"chime":{
"client":{
"@@assign":"disabled"
}
},
"default":{
"client":{
"@@assign":"disabled"
}
}
}
}
}
```
**For Slack**
+ The Slack client is enabled.
+ Only the specific Slack workspace *Slack-Workspace-Id* is allowed.
+ The default settings are to allow only private Slack channels, Channel level IAM roles, and User level IAM roles.
**For Microsoft Team**
+ The Microsoft Teams client is disabled.
**For Amazon Chime**
+ The Amazon Chime client is disabled.
**Additional details**
+ The `default` block at the bottom sets the client to be disabled, which disables Amazon Q Developer in chat applications across the organization unless overridden at a lower level. This default also disables any new chat application that Amazon Q Developer in chat applications supports. For example, if Amazon Q Developer in chat applications supports a new chat application, this default disables that newly supported chat application as well.
### Example 2: Allow only Slack integrations with User Level IAM roles
The following policy takes a more permissive approach to Slack, allowing all Slack workspaces but restricting the authentication mode to only User level IAM roles.
```
{
"chatbot":{
"platforms":{
"slack":{
"client":{
"@@assign":"enabled"
},
"workspaces":
{
"@@assign":[
"*"
]
},
"default":{
"supported_role_settings":{
"@@assign":[
"user_role"
]
}
}
},
"microsoft_teams":{
"client":{
"@@assign":"disabled"
}
},
"chime":{
"client":{
"@@assign":"disabled"
}
}
},
"default":{
"client":{
"@@assign":"disabled"
}
}
}
}
```
**For Slack**
+ The Slack client is enabled.
+ No specific Slack workspaces are defined using the wildcard `"*"`, so all workspaces are permitted.
+ The default settings are to allow only User level IAM roles.
**For Microsoft Team**
+ The Microsoft Teams client is disabled.
**For Amazon Chime**
+ The Amazon Chime client is disabled.
**Additional details**
+ The `default` block at the bottom sets the client to be disabled, which disables Amazon Q Developer in chat applications across the organization unless overridden at a lower level. This default also disables any new chat application that Amazon Q Developer in chat applications supports. For example, if Amazon Q Developer in chat applications supports a new chat application, this default disables that newly supported chat application as well.
### Example 3: Allow only Microsoft Teams integrations in a specific Tenants
The following example policy locks down the organization to only allow Microsoft Teams chatbot integrations within the specified tenant, while completely blocking Slack integrations.
```
{
"chatbot":{
"platforms":{
"slack":{
"client": {
"@@assign": "disabled"
},
},
"microsoft_teams":{
"client": {
"@@assign": "enabled"
},
"tenants":{
"Microsoft-Teams-Tenant-Id":{
"@@assign":[
"*"
]
}
}
},
"chime": {
"client":{
"@@assign": "disabled"
}
}
}
}
}
```
**For Slack**
+ The Slack client is disabled.
**For Microsoft Team**
+ Only the specific tenant *Microsoft-Teams-Tenant-Id* is permitted, using the wildcard `"*"` to allow all teams within that tenant.
**For Amazon Chime**
+ The Amazon Chime client is disabled.
**Additional details**
+ The `default` block at the bottom sets the client to be disabled, which disables Amazon Q Developer in chat applications across the organization unless overridden at a lower level. This default also disables any new chat application that Amazon Q Developer in chat applications supports. For example, if Amazon Q Developer in chat applications supports a new chat application, this default disables that newly supported chat application as well.
### Example 4: Allows restricted Amazon Q Developer in chat applications access for Slack workspaces and a Microsoft Teams tenant
The following policy allows restricted Amazon Q Developer in chat applications access for selected Slack workspaces and a Microsoft Teams tenant.
```
{
"chatbot":{
"platforms":{
"slack":{
"client":{
"@@assign":"enabled"
},
"workspaces": {
"@@assign":[
"Slack-Workspace-Id1",
"Slack-Workspace-Id2"
]
},
"default":{
"supported_channel_types":{
"@@assign":[
"private"
]
},
"supported_role_settings":{
"@@assign":[
"user_role"
]
}
},
"overrides":{
"Slack-Workspace-Id2":{
"supported_channel_types":{
"@@assign":[
"public",
"private"
]
},
"supported_role_settings":{
"@@assign":[
"channel_role",
"user_role"
]
}
}
}
},
"microsoft_teams":{
"client":{
"@@assign":"enabled"
},
"tenants":{
"Microsoft-Teams-Tenant-Id":{
"@@assign":[
"Microsoft-Teams-Team-Id"
]
}
},
"default":{
"supported_role_settings":{
"@@assign":[
"user_role"
]
}
},
"overrides":{
"Microsoft-Teams-Tenant-Id":{
"Microsoft-Teams-Team-Id":{
"supported_role_settings":{
"@@assign":[
"channel_role",
"user_role"
]
}
}
}
}
}
},
"default":{
"client":{
"@@assign":"disabled"
}
}
}
}
```
**For Slack**
+ The Slack client is enabled.
+ The allowed Slack workspaces are *Slack-Workspace-Id1* and *Slack-Workspace-Id2*.
+ The default settings for Slack are to only allow private channels and User level IAM roles.
+ There is an override for the workspace *Slack-Workspace-Id2* that allows both public and private channels as well as both Channel level IAM roles and User level IAM roles.
**For Microsoft Team**
+ The Microsoft Teams is enabled.
+ The allowed Teams tenants are *Microsoft-Teams-Tenant-Id* with the team *Microsoft-Teams-Team-Id*.
+ The default settings are to only allow User level IAM roles.
+ There is an override for the tenant *Microsoft-Teams-Tenant-Id* that allows both Channel level IAM roles and User level IAM roles for the team *Microsoft-Teams-Team-Id*.
**Additional details**
+ The `default` block at the bottom sets the client to be disabled, which disables Amazon Q Developer in chat applications across the organization unless overridden at a lower level. This means Amazon Chime is disabled in this example. This default also disables any new chat application that Amazon Q Developer in chat applications supports. For example, if Amazon Q Developer in chat applications supports a new chat application, this default disables that newly supported chat application as well.
# AI services opt-out policies
AWS AI services may use and store customer content for service improvement, such as fixing operational issues, evaluating service performance, debugging, or model training. For this purpose, we might store such content in an AWS Region outside of the AWS Region where you are using the service. You can opt out of use of your content for service improvement by using the AWS Organizations opt-out policy.
You can create opt-out policies for an individual AI service, or for all services supported by AI services opt-out policies. You can also query the effective policy applicable to each account to see the effects of your setting choices.
For more detailed information, see [AWS Machine Learning and Artificial Intelligence Services](https://aws.amazon.com/service-terms) in the AWS Service Terms. For a list of services supported by AI services opt-out policies, see [List of supported AI services](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out_all.html#ai-opt-out-all-list).
**Topics**
+ [Considerations](#orgs_manage_policies-ai-opt-out-considerations)
+ [Getting started](orgs_manage_policies-ai-opt-out_getting-started.md)
+ [Opt out from all AI services](orgs_manage_policies_ai-opt-out_all.md)
+ [AI services opt-out policy syntax and examples](orgs_manage_policies_ai-opt-out_syntax.md)
## Considerations when using AI services opt-out policies
**Opting out deletes all of the associated historical content**
When you opt out of content use by an AWS AI service, that service deletes all of the associated historical content that was shared with AWS before you set the option. This deletion is limited to content stored that is not required to provide service functions.
For example, when you use a service while opted in, that service might store copies of your content for service improvement. When you opt out, any copies that have been stored by the service for that purpose are deleted, but any content that is used to provide the service to you is not deleted.
# Getting started with AI services opt-out policies
Follow these steps to get started using Artificial Intelligence (AI) services opt-out policies.
1. [Learn about the permissions you must have to perform backup policy tasks](orgs_manage_policies_prereqs.md).
1. [Enable AI services opt-out policies for your organization](enable-policy-type.md).
1. [Create an AI services opt-out policy](orgs_policies_create.md#create-ai-opt-out-policy-procedure).
1. [Attach the AI services opt-out policy to your organization's root, OU, or account](orgs_policies_attach.md).
1. [View the combined effective AI services opt-out policy that applies to an account](orgs_manage_policies_effective.md).
For all of these steps, you sign in as an AWS Identity and Access Management (IAM) user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account.
**Other information**
+ [Learn policy syntax for AI services opt-out policies and see policy examples](orgs_manage_policies_ai-opt-out_syntax.md)
# Opt out from all supported AWS AI services
**In this topic:**
+ You can opt out with a one button selection in the AWS Organizations console.
+ You can opt out by attaching the provided example policy using the AWS CLI & AWS SDKs.
+ You can view a list of AWS services supported by the AI services opt-out policy.
## Opt out from all supported AI services
You can opt your organization out of having its content used for service improvement by creating and attaching an AI services opt-out policy. This policy applies to all current and future supported AWS AI services. Member accounts cannot update the policy.
------
#### [ AWS Management Console ]
**To opt out from all AI services**
1. Sign in to the [AWS Organizations console](https://console.aws.amazon.com/organizations/v2). You must sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization’s management account.
1. On the **[AI services opt-out policies](https://console.aws.amazon.com/organizations/v2/home/policies/aiservices-opt-out-policy)** page, choose **Opt out from all services**.
1. On the **Opt out from all services** confirmation page, choose **Opt out from all services**.
------
#### [ AWS CLI & AWS SDKs ]
**To opt out from all AI services**
1. Copy "Example 1: Opt out of all AI services for all accounts in the organization" in [AI services opt-out examples](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out_syntax.html#ai-opt-out-policy-examples).
1. Follow the instruction in [Attaching and detaching AI services opt-out](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out_attach.html).
------
**Note**
Additional steps are required to opt out from Amazon Monitron. For more information, see [AWS Service Terms](https://aws.amazon.com/service-terms/#81._Industrial_AI_Services).
## List of services supported by the AI services opt-out policy
The following is a list of AWS services supported by the AI services opt-out policy:
+ [Amazon AI Operations](https://aws.amazon.com/what-is/aiops)
+ [Amazon Chime SDK voice analytics](https://docs.aws.amazon.com/chime-sdk/latest/dg/voice-analytics.html)
+ [Amazon CloudWatch](https://docs.aws.amazon.com/cloudwatch)
+ [Amazon CodeGuru Profiler](https://docs.aws.amazon.com/codeguru)
+ [Amazon CodeWhisperer](https://docs.aws.amazon.com/codewhisperer) (now part of [Amazon Q Developer](https://docs.aws.amazon.com/amazonq))
+ [Amazon Comprehend](https://docs.aws.amazon.com/comprehend)
+ [Amazon Connect](https://docs.aws.amazon.com/connect)
+ [Amazon Connect Optimization](https://docs.aws.amazon.com/connect)
+ [Amazon Connect Contact Lens](https://docs.aws.amazon.com/connect/latest/adminguide/contact-lens.html)
+ [AWS Database Migration Service](https://docs.aws.amazon.com/dms)
+ [Amazon DataZone](https://docs.aws.amazon.com/datazone) (and [Amazon SageMaker Data Agent](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/sagemaker-data-agent.html))
+ [AWS DevOps Agent](https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent.html)
+ [AWS Entity Resolution](https://docs.aws.amazon.com/entityresolution)
+ [Amazon Fraud Detector](https://docs.aws.amazon.com/frauddetector)
+ [AWS Glue](https://docs.aws.amazon.com/glue)
+ [Amazon GuardDuty](https://docs.aws.amazon.com/guardduty)
+ [Amazon Lex](https://docs.aws.amazon.com/lex)
+ [Amazon Polly](https://docs.aws.amazon.com/polly)
+ [Amazon Q](https://docs.aws.amazon.com/amazonq)
+ [Amazon Quick](https://docs.aws.amazon.com/quicksight)
+ [Amazon Rekognition](https://docs.aws.amazon.com/rekognition)
+ [Amazon Security Lake](https://docs.aws.amazon.com/security-lake/)
+ [AWS Supply Chain](https://docs.aws.amazon.com/aws-supply-chain)
+ [Amazon Textract](https://docs.aws.amazon.com/textract)
+ [Amazon Transcribe](https://docs.aws.amazon.com/transcribe)
+ [AWS Transform](https://docs.aws.amazon.com/transform/latest/userguide/what-is.html)
+ [Amazon Translate](https://docs.aws.amazon.com/translate)
+ [Amazon WorkSpaces](https://docs.aws.amazon.com/workspaces)
+ [AWS Security Hub](https://docs.aws.amazon.com/securityhub)
# AI services opt-out policy syntax and examples
This topic describes Artificial Intelligence (AI) services opt-out policy syntax and provides examples.
## Syntax for AI services opt-out policies
An AI services opt-out policy is a plaintext file that is structured according to the rules of [JSON](http://json.org). The syntax for AI services opt-out policies follows the syntax for management policy types. For a complete discussion of that syntax, see [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md). This topic focuses on applying that general syntax to the specific requirements of the AI services opt-out policy type.
**Important**
The capitalization of the values discussed in this section are important. Enter the values with upper and lower case letters as shown in this topic. The policies do not work if you use unexpected capitalization.
The following policy shows the basic AI services opt-out policy syntax. If this example was attached directly to an account, that account would be explicitly opted out of one service and opted in to another. Other services could be opted in or opted out by policies inherited from higher levels (OU or root policies).
```
{
"services": {
"rekognition": {
"opt_out_policy": {
"@@assign": "optOut"
}
},
"lex": {
"opt_out_policy": {
"@@assign": "optIn"
}
}
}
}
```
Imagine the following example policy attached to the organization's root. It sets the default for the organization to opt out of all AI services. This automatically includes any AI services not otherwise explicitly exempted, including any AI services that AWS might deploy in the future. You can attach child policies to OUs or directly to accounts to override this setting for any AI service except Amazon Comprehend. The second entry in the following example uses `@@operators_allowed_for_child_policies` set to `none` to prevent it from being overridden. The third entry in the example makes an organization-wide exemption for Amazon Rekognition. It opts in the entire organization for that service, but the policy does allow child policies to override where appropriate.
```
{
"services": {
"default": {
"opt_out_policy": {
"@@assign": "optOut"
}
},
"comprehend": {
"opt_out_policy": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "optOut"
}
},
"rekognition": {
"opt_out_policy": {
"@@assign": "optIn"
}
}
}
}
```
AI services opt-out policy syntax includes the following elements:
+ The `services` element. An AI services opt-out policy is identified by this fixed name as the outermost JSON containing element.
An AI services opt-out policy can have one or more statements under the `services` element. Each statement contains the following elements:
+ A *service name key* that identifies an AWS AI service. The following key names are valid values for this field:
+ **`default`** – represents **all** currently available AI services and implicitly and automatically includes any AI services that might be added in the future.
+ `aiops`
+ `aidevops`
+ `awssupplychain`
+ `chimesdkvoiceanalytics`
+ `cloudwatch`
+ `codeguruprofiler`
+ `codewhisperer`
+ `comprehend`
+ `connect`
+ `connectamd`
+ `connectoptimization`
+ `contactlens`
+ `datazone`
+ `dms`
+ `entityresolution`
+ `frauddetector`
+ `glue`
+ `guardduty`
+ `lex`
+ `polly`
+ `q`
+ `quicksightq`
+ `rekognition`
+ `securitylake`
+ `textract`
+ `transcribe`
+ `transform`
+ `translate`
+ `workspaces`
+ `securityhub`
Each policy statement identified by a service name key can contain the following elements:
+ The `opt_out_policy` key. This key must be present. This is the only key you can place under a service name key.
The `opt_out_policy` key can contain ***only*** the `@@assign` operator with one of the following values:
+ `optOut` – you choose to opt out of content use for the specified AI service.
+ `optIn` – you choose to opt in to content use for the specified AI service.
**Notes**
You can't use the `@@append` and `@@remove` inheritance operators in AI services opt-out policies.
You can't use the `@@enforced_for` operator in AI services opt-out policies.
+ At any level, you can specify the `@@operators_allowed_for_child_policies` operator to control what child policies can do to override settings imposed by parent policies. You can specify one of the following values:
+ `@@assign` – child policies of this policy can use the `@@assign` operator to override the inherited value with a different value.
+ `@@none` – child policies of this policy can't change the value.
The behavior of the `@@operators_allowed_for_child_policies` depends on where you place it. You can use the following locations:
+ Under the `services` key – controls whether a child policy can add to or change the list of services in the effective policy.
+ Under the key for a specific AI service or the `default` key - controls whether a child policy can add to or change the list of keys under this specific entry.
+ Under the `opt_out_policies` key for a specific service – controls whether a child policy can change only the setting for this specific service.
## AI services opt-out policy examples
The example policies that follow are for information purposes only.
### Example 1: Opt out of all AI services for all accounts in the organization
The following example shows a policy that you could attach to your organization's root to opt out of AI services for accounts in your organization.
**Tip**
If you copy the following example using the copy button in the example's upper-right corner, the copy doesn't include the line numbers. It's ready to paste.
```
| {
| "services": {
[1] | "@@operators_allowed_for_child_policies": ["@@none"],
| "default": {
[2] | "@@operators_allowed_for_child_policies": ["@@none"],
| "opt_out_policy": {
[3] | "@@operators_allowed_for_child_policies": ["@@none"],
| "@@assign": "optOut"
| }
| }
| }
| }
```
+ [1] – The `"@@operators_allowed_for_child_policies": ["@@none"]` that is under `services` prevents any child policy from adding any new sections for individual services other than the `default` section that is already there. `Default` is the placeholder that represents "all AI services".
+ [2] – The `"@@operators_allowed_for_child_policies": ["@@none"]` that is under `default` prevents any child policy from adding any new sections other than the `opt_out_policy` section that is already there.
+ [3] – The `"@@operators_allowed_for_child_policies": ["@@none"]` that is under `opt_out_policy` prevents child policies from changing the value of the `optOut` setting or adding any additional settings.
### Example 2: Set an organization default setting for all services, but allow child policies to override the setting for individual services
The following example policy sets an organization-wide default for all AI services. The value for `default` prevents a child policy from change the `optOut` value for service `default`, the placeholder for all AI services. If this policy is applied as a parent policy by attaching it to the root or to an OU, child policies can still change the opt-out setting for individual services, as shown in the second policy.
+ Because there is no `"@@operators_allowed_for_child_policies": ["@@none"]` under the `services` key, child policies can add new sections for individual services.
+ The `"@@operators_allowed_for_child_policies": ["@@none"]` that is under `default` prevents any child policy from adding any new sections other than the `opt_out_policy` section that is already there.
+ The `"@@operators_allowed_for_child_policies": ["@@none"]` that is under `opt_out_policy` prevents child policies from changing the value of the `optOut` setting or adding any additional settings.
**Organization root userAI services opt-out parent policy**
```
{
"services": {
"default": {
"@@operators_allowed_for_child_policies": ["@@none"],
"opt_out_policy": {
"@@operators_allowed_for_child_policies": ["@@none"],
"@@assign": "optOut"
}
}
}
}
```
The following example policy assumes that the previous example policy is attached to either the organization root or to a parent OU, and that you attach this example to an account affected by the parent policy. It overrides the default opt-out setting and explicitly opts in to only the Amazon Lex service.
**AI services opt-out child policy**
```
{
"services": {
"lex": {
"opt_out_policy": {
"@@assign": "optIn"
}
}
}
}
```
The resulting effective policy for the AWS account is that the account opts in to only Amazon Lex, and opts out of all other AWS AI services because of the inherited `default` opt-out setting from the parent policy.
### Example 3: Define an organization-wide AI services opt-out policy for a single service
The following example shows an AI services opt-out policy that defines an `optOut` setting for a single AI service. If this policy is attached to the organization's root, it prevents any child policy from overriding the `optOut` setting for this one service. Other services are not addressed by this policy, but could be affected by child policies in other OUs or accounts.
```
{
"services": {
"rekognition": {
"opt_out_policy": {
"@@assign": "optOut",
"@@operators_allowed_for_child_policies": ["@@none"]
}
}
}
}
```
# Security Hub policies
AWS Security Hub policies provide security teams with a centralized approach to managing security configurations across their AWS Organizations. By leveraging these policies, you can establish and maintain consistent security controls through a central configuration mechanism. This integration allows you to address security coverage gaps by creating policies that align with your organization's security requirements and centrally applying them across accounts and organizational units (OUs).
Security Hub policies are fully integrated with AWS Organizations, allowing management accounts or delegated administrators to define and enforce security configurations. When accounts join your organization, they automatically inherit the applicable policies based on their location in the organizational hierarchy. This ensures that your security standards are consistently applied as your organization grows. The policies respect existing organizational structures and provide flexibility in how security configurations are distributed, while maintaining central control over critical security settings.
## Key features and benefits
Security Hub policies provide a comprehensive set of capabilities that help you manage and enforce security configurations across your AWS organization. These features streamline security management while ensuring consistent control over your multi-account environment.
+ Centrally [enable Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/security-hub-adv-getting-started-enable.html#security-hub-adv-getting-started-enable-org-account) across accounts and Regions in your organization
+ Create security policies that define your security configuration across accounts and OUs
+ Automatically apply security configurations to new accounts when they join your organization
+ Ensure consistent security settings across your organization
+ Prevent member accounts from modifying organization-level security configurations
## What are Security Hub policies?
Security Hub policies are AWS Organizations policies that provide centralized control over security configurations across your organization's accounts. These policies work seamlessly with AWS Organizations to help you establish and maintain consistent security standards throughout your multi-account environment.
When you implement Security Hub policies, you gain the ability to define specific security configurations that automatically propagate across your organization. This ensures that all accounts, including newly created ones, align with your organization's security requirements and best practices.
These policies also help you maintain compliance by enforcing consistent security controls and preventing individual accounts from modifying organization-level security settings. This centralized approach significantly reduces the administrative overhead of managing security configurations across large, complex AWS environments.
## How Security Hub policies work
When you attach an Security Hub policy to your organization or organizational unit, AWS Organizations automatically evaluates the policy and applies it based on the scope you define. The policy enforcement process follows specific conflict resolution rules:
When regions appear in both enable and disable lists, the disable configuration takes precedence. For example, if a region is listed in both enable and disable configurations, Security Hub will be disabled in that region.
When `ALL_SUPPORTED` is specified for enablement, Security Hub is enabled in all current and future regions unless explicitly disabled. This allows you to maintain comprehensive security coverage as AWS expands into new regions.
Child policies can modify parent policy settings using inheritance operators, allowing for granular control at different organizational levels. This hierarchical approach ensures that specific organizational units can customize their security settings while maintaining baseline controls.
## Terminology
This topic uses the following terms when discussing Security Hub policies.
**Security Hub policy terminology**
| Term | Definition |
| --- | --- |
| Effective policy | The final policy that applies to an account after combining all inherited policies. |
| Policy inheritance | The process by which accounts inherit policies from parent organizational units. |
| Delegated administrator | An account designated to manage Security Hub policies on behalf of the organization. |
| Service-linked role | An IAM role that allows Security Hub to interact with other AWS services. |
## Use cases for Security Hub policies
Security Hub policies address common security management challenges in multi-account environments. The following use cases demonstrate how organizations typically implement these policies to enhance their security posture.
### Example use case: Regional compliance requirements
A multinational corporation needs different Security Hub configurations for different geographical regions. They create a parent policy enabling Security Hub in all regions using `ALL_SUPPORTED`, then use child policies to disable specific regions where different security controls are required. This allows them to maintain compliance with regional regulations while ensuring comprehensive security coverage.
### Example use case: Development team security standards
A software development organization implements Security Hub policies that enable monitoring in production regions while keeping development regions unmanaged. They use explicit region lists in their policies rather than `ALL_SUPPORTED` to maintain precise control over security monitoring coverage. This approach allows them to enforce stricter security controls in production environments while maintaining flexibility in development areas.
## Policy inheritance and enforcement
Understanding how policies are inherited and enforced is crucial for effective security management across your organization. The inheritance model follows the AWS Organizations hierarchy, ensuring predictable and consistent policy application.
+ Policies attached at the root level apply to all accounts
+ Accounts inherit policies from their parent organizational units
+ Multiple policies can apply to a single account
+ More specific policies (closer to the account in the hierarchy) take precedence
## Policy validation
When creating Security Hub policies, the following validations occur:
+ Region names must be valid AWS region identifiers
+ Regions must be supported by Security Hub
+ Policy structure must follow AWS Organizations policy syntax rules
+ Both `enable_in_regions` and `disable_in_regions` lists must be present, though they can be empty
## Regional considerations and supported Regions
Security Hub policies operate across multiple Regions, requiring careful consideration of your global security requirements. Understanding regional behavior helps you implement effective security controls across your organization's global footprint.
+ Policy enforcement occurs in each Region independently
+ You can specify which Regions to include or exclude in your policies
+ New Regions are automatically included when using the `ALL_SUPPORTED` option
+ Policies only apply to Regions where Security Hub is available
## Next steps
To get started with Security Hub policies:
1. Review the prerequisites in Getting started with Security Hub policies
1. Plan your policy strategy using our best practices guide
1. Learn about policy syntax and view example policies
# Getting started with Security Hub policies
Before you configure Security Hub policies, ensure you understand the prerequisites and implementation requirements. This topic guides you through the process of setting up and managing these policies in your organization.
## Before you begin
Review the following requirements before implementing Security Hub policies:
+ Your account must be part of an AWS Organizations organization
+ You must be signed in as either:
+ The management account for the organization
+ A delegated administrator account with permissions to manage Security Hub policies
+ You must enable trusted access for Security Hub in your organization
+ You must enable the Security Hub policy type in the root of your organization
Additionally, verify that:
+ Security Hub is supported in the Regions where you want to apply policies
+ You have the `AWSServiceRoleForSecurityHubV2` service-linked role configured in your management account. To verify this role exists, run `aws iam get-role --role-name AWSServiceRoleForSecurityHubV2`. If you need to create this role, you can either run `aws securityhub enable-security-hub-v2` in any Region from your management account, or create it directly by running `aws iam create-service-linked-role --aws-service-name securityhubv2.amazonaws.com`.
## Implementation steps
To implement Security Hub policies effectively, follow these steps in sequence. Each step ensures proper configuration and helps prevent common issues during setup. The management account or delegated administrator can perform these steps through the AWS Organizations console, AWS Command Line Interface (AWS CLI), or AWS SDKs.
1. [Enable trusted access for Security Hub](orgs_integrate_services.md#orgs_how-to-enable-disable-trusted-access).
1. [Enable Security Hub policies for your organization](enable-policy-type.md).
1. [Create a Security Hub policy](orgs_policies_create.md#create-security-hub-policy-procedure).
1. [Attach the Security Hub policy to your organization's root, OU, or account](orgs_policies_attach.md).
1. [View the combined effective Security Hub policy that applies to an account](orgs_manage_policies_effective.md).
For all of these steps, you sign in as an AWS Identity and Access Management (IAM) user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account.
**Other information**
+ [Learn policy syntax for Security Hub policies and see policy examples](orgs_manage_policies_security_hub_syntax.md)
# Best practices for using Security Hub policies
When implementing Security Hub policies across your organization, following established best practices helps ensure successful deployment and maintenance of your security configurations. These guidelines specifically address the unique aspects of Security Hub policy management and enforcement within AWS Organizations.
## Policy design principles
Before creating Security Hub policies, establish clear principles for your policy structure. Keep policies simple and avoid complex cross-attribute or nested rules that make it difficult to determine the final outcome. Start with broad policies at the organization root level and refine them through child policies where needed.
Consider using empty region lists strategically. You can leave `enable_in_regions` empty when you only need to disable Security Hub in specific regions, or leave `disable_in_regions` empty to keep regions unmanaged by policy. This flexibility helps you maintain precise control over your security monitoring coverage.
## Region management strategies
When managing regions through Security Hub policies, consider these proven approaches. Use `ALL_SUPPORTED` when you want to automatically include future regions in your security coverage. For more granular control, explicitly list regions rather than relying on `ALL_SUPPORTED`, especially when different regions require different security configurations.
Document your region-specific requirements, particularly for:
+ Compliance-mandated regions that require specific configurations
+ Development versus production environment differences
+ Opt-in regions with special considerations
+ Regions where Security Hub must remain disabled
## Policy inheritance planning
Carefully plan your policy inheritance structure to maintain effective security control while allowing necessary flexibility. Document which organizational units can modify inherited policies and what modifications are allowed. Consider restricting inheritance operators (@@assign, @@append, @@remove) at parent levels when you need to enforce strict security controls.
## Monitoring and validation
Implement regular monitoring practices to ensure your policies remain effective. Review policy attachments periodically, especially after organizational changes. Validate that region configurations match your intended security coverage, particularly when using `ALL_SUPPORTED` or when managing multiple region lists.
## Troubleshooting strategies
When troubleshooting Security Hub policies, focus first on policy precedence and inheritance. Remember that disable configurations take precedence over enable configurations when regions appear in both lists. Check policy inheritance chains to understand how parent and child policies combine to create the effective policy for each account.
# Security Hub policy syntax and examples
Security Hub policies follow a standardized JSON syntax that defines how Security Hub is enabled and configured across your organization. Understanding the policy structure helps you create effective policies for your security requirements.
## Considerations
Before creating Security Hub policies, understand these key points about policy syntax:
+ Both `enable_in_regions` and `disable_in_regions` lists are required in the policy, though they can be empty
+ When processing effective policies, `disable_in_regions` takes precedence over `enable_in_regions`
+ Child policies can modify parent policies using inheritance operators unless explicitly restricted
+ The `ALL_SUPPORTED` designation includes both current and future regions
+ Region names must be valid and available in Security Hub
## Basic policy structure
A Security Hub policy uses this basic structure:
```
{
"securityhub": {
"enable_in_regions": {
"@@append": ["ALL_SUPPORTED"],
"@@operators_allowed_for_child_policies": ["@@all"]
},
"disable_in_regions": {
"@@append": [],
"@@operators_allowed_for_child_policies": ["@@all"]
}
}
}
```
## Policy components
Security Hub policies contain these key components:
`securityhub`
The top-level container for policy settings
Required for all Security Hub policies
`enable_in_regions`
List of regions where Security Hub should be enabled
Can contain specific region names or `ALL_SUPPORTED`
Required field but can be empty
When using `ALL_SUPPORTED`, includes future regions
`disable_in_regions`
List of regions where Security Hub should be disabled
Can contain specific region names or `ALL_SUPPORTED`
Required field but can be empty
Takes precedence over `enable_in_regions` when regions appear in both lists
Inheritance operators
@@assign - Overwrites inherited values
@@append - Adds new values to existing ones
@@remove - Removes specific values from inherited settings
## Security Hub policy examples
The following examples demonstrate common Security Hub policy configurations.
The example below enables Security Hub in all current and future regions. By using `ALL_SUPPORTED` in the `enable_in_regions` list and leaving `disable_in_regions` empty, this policy ensures comprehensive security coverage as new regions become available.
```
{
"securityhub":{
"enable_in_regions":{
"@@assign":[
"ALL_SUPPORTED"
]
},
"disable_in_regions":{
"@@assign":[
]
}
}
}
```
This example disables Security Hub in all regions including any future regions since `disable_in_regions` list takes precedence over `enable_in_regions`.
```
{
"securityhub":{
"enable_in_regions":{
"@@assign":[
"us-east-1",
"us-west-2"
]
},
"disable_in_regions":{
"@@assign":[
"ALL_SUPPORTED"
]
}
}
}
```
The following example demonstrates how child policies can modify parent policy settings using inheritance operators. This approach allows for granular control while maintaining the overall policy structure. The child policy adds a new region to `enable_in_regions` and removes a region from `disable_in_regions`.
```
{
"securityhub":{
"enable_in_regions":{
"@@append":[
"eu-central-1"
]
},
"disable_in_regions":{
"@@remove":[
"us-west-2"
]
}
}
}
```
This example shows how to enable Security Hub in multiple specific regions without using `ALL_SUPPORTED`. This provides precise control over which regions have Security Hub enabled, while leaving unspecified regions unmanaged by the policy.
```
{
"securityhub":{
"enable_in_regions":{
"@@assign":[
"us-east-1",
"us-west-2",
"eu-west-1",
"ap-southeast-1"
]
},
"disable_in_regions":{
"@@assign":[
]
}
}
}
```
The following example demonstrates how to handle regional compliance requirements by enabling Security Hub in most regions while explicitly disabling it in specific locations. The `disable_in_regions` list takes precedence, ensuring Security Hub remains disabled in those regions regardless of other policy settings.
```
{
"securityhub":{
"enable_in_regions":{
"@@assign":[
"ALL_SUPPORTED"
]
},
"disable_in_regions":{
"@@assign":[
"ap-east-1",
"me-south-1"
]
}
}
}
```
# Amazon Bedrock policies
Amazon Bedrock policies allow you to enforce safeguards configured in Amazon Bedrock Guardrails automatically across any element in your organization structure for all model inference calls to Amazon Bedrock. This eliminates the need to configure an individual guardail for each account. Amazon Bedrock Guardrails provides configurable safeguards to help safely build generative AI applications at scale, with a standard approach for a wide range of foundation models including: models supported in Amazon Bedrock, fine-tuned models, and models hosted outside of Amazon Bedrock.
Amazon Bedrock policies in AWS Organizations allow you to reference a guardrail created in your management account in a JSON format. You can attach any policy into the required element of your organization structure, such as the root, organizational units (OUs), and individual accounts. AWS Organizations applies inheritance rules to combine the policies, which results in an effective policy for each account that dictates how safeguards are enforced for your generative AI application.
## How it works
Amazon Bedrock policies give you control over automatic enforcement of safeguards within guardrails across multiple accounts, allowing you to enforce guardrails on all or a subset of models for inference calls to Amazon Bedrock. You need to reference a specific version of the appropriate guardrail within your policy, adhering to your organization's responsible AI requirements. This is specific to the AWS region where your guardrail exists, and you need to have different guardrails for each AWS region where you want the enforcement of safety controls. You can then attach this policy to any node of the organization, and accounts beneath that node will then automatically inherit those safeguards and apply them for every model invocation to Amazon Bedrock.
Amazon Bedrock policies help you ensure consistent safety controls throughout your organization, and provide a centralized approach to safely build generative AI applications at scale.
# Getting started with Amazon Bedrock policies
Before you configure Amazon Bedrock policies, ensure you understand the prerequisites and implementation requirements. This topic guides you through the process of setting up and managing these policies in your organization.
## Before you begin
Review the following requirements before implementing Amazon Bedrock policies:
+ Your account must be part of an AWS organization
+ You must be signed in as either:
+ The management account for the organization
+ A delegated administrator account with permissions to manage Amazon Bedrock policies
+ You must enable the Amazon Bedrock policy type in the root of your organization
## Implementation steps
To implement Amazon Bedrock policies effectively, follow these steps in sequence. Each step ensures proper configuration and helps prevent common issues during setup. The management account or delegated administrator can perform these steps through the AWS Organizations console, AWS Command Line Interface (AWS CLI), or AWS SDKs.
1. [Enable Amazon Bedrock policies for your organization](enable-policy-type.md).
1. [Create an Amazon Bedrock policy](orgs_manage_policies_bedrock_syntax.md).
1. [Attach the Amazon Bedrock policy to your organization's root, OU, or account](orgs_policies_attach.md).
1. [View the combined effective Amazon Bedrock policy that applies to an account](orgs_manage_policies_effective.md).
# Best practices for using Amazon Bedrock policies
## Use a valid guardrail identifier
An incorrect or malformed identifier will cause all Amazon Bedrock API calls across the target organization to fail. [Monitor CloudTrail for invalid effective policy alerts to detect misconfigurations quickly](https://docs.aws.amazon.com/organizations/latest/userguide/invalid-policy-alerts.html).
## Exclude automated reasoning policies
Guardrails that include an automated reasoning policy are not supported for organization-level enforcement. Verify that your selected Amazon Bedrock Guardrail does not contain one.
## Grant the necessary IAM permissions
Use [Amazon Bedrock Guardrails resource-based policies](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-resource-based-policies.html) to grant the organization and its member accounts permissions to evaluate the enforced guardrail at runtime.
## Review Amazon Bedrock Service Limits for Guardrails
Member account calls using the Amazon Bedrock Policy will count towards the Service Quotas for the member. Review the Service Quotas Console and be sure that your Guardrails runtime limits are sufficient for your call volume.
## Start small, then scale
Attach your policy to a few accounts to start, making sure the policy is being applied in the way you expect. Make sure to test that the Guardrail permissions are configured to allow cross-account access.
## Validate changes to your Amazon Bedrock policies using DescribeEffectivePolicy
After you make a change to an Amazon Bedrock policy, check the effective policies for representative accounts below the level where you made the change. You can view the effective policy by using the AWS Management Console, or by using the `DescribeEffectivePolicy` API operation or one of its AWS CLI or AWS SDK variants. Ensure that the change you made had the intended impact on the effective policy.
## Communicate and train
Ensure your organizations understand the purpose and impact of your Amazon Bedrock policies. Provide clear guidance on Amazon Bedrock Guardrails behavior and what to expect.
# Amazon Bedrock policy syntax and examples
An Amazon Bedrock policy is a plaintext file that is structured according to the rules of JSON. The syntax for Amazon Bedrock policies follows the syntax for all management policy types. For more information, see [Policy syntax and inheritance for management policy types](orgs_manage_policies_inheritance_mgmt.md). This topic focuses on applying that general syntax to the specific requirements of the Amazon Bedrock policy type.
The following Amazon Bedrock policy example shows the basic Amazon Bedrock policy syntax:
```
{
"bedrock": {
"guardrail_inference": {
"us-east-1": {
"config_1": {
"identifier": {
"@@assign": "arn:aws:bedrock:us-east-1:123456789012:guardrail/hu1dlsv9wy1d:1"
},
"selective_content_guarding": {
"system": {
"@@assign": "selective"
},
"messages": {
"@@assign": "comprehensive"
}
},
"model_enforcement": {
"included_models": {
"@@assign": ["ALL"]
},
"excluded_models": {
"@@assign": ["amazon.titan-embed-text-v2:0", "cohere.embed-english-v3"]
}
}
}
}
}
}
}
```
## The Amazon Bedrock policy syntax includes the following elements
`"bedrock"`
The top-level key for Amazon Bedrock policy documents.
`"guardrail_inference"`
Defines guardrail enforcement configuration.
``
The region where the policy will be enforced. For example, `"us-east-1"`.
`"config_1"`
Configuration identifier for the guardrail settings.
`"identifier"` (Required)
Guardrail ARN, followed by `:version`, the Guardrail version.
+ The Guardrail must be owned by the Management account. You cannot create a policy using a Guardrail from another account.
+ The Guardrail must have a version, and that version cannot be DRAFT. To create a version of your guardrail, see [Create a version of a guardrail](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-versions-create.html) in the Amazon Bedrock user guide.
+ The Guardrail must have a Resource Based Policy that allows organization members to call `ApplyGuardrail`.
+ The Guardrail must be created and used in the specified region.
`"selective_content_guarding"` (Optional)
Amazon Bedrock APIs allow marking specific content within the input that the caller wants guardrails to process. These settings let enforcers control whether or not to respect content tagging decisions made by the caller. When specified, one of `"system"` or `"messages"` is required.
`"system"` (Optional)
Choose how system prompts will be processed by guardrails. Defaults to `comprehensive` when not specified.
+ `"comprehensive"`: Evaluate all content regardless of guard content tags.
+ `"selective"`: Only evaluate content within guard content tags. Does not evaluate any content when no tags are specified.
`"messages"` (Optional)
Choose how message content with user and assistant conversation will be processed by guardrails. Defaults to `comprehensive` when not specified.
+ `"comprehensive"`: Evaluate all content regardless of guard content tags.
+ `"selective"`: Only evaluate content within guard content tags. Evaluates all content within messages when no tags are specified.
`"model_enforcement"` (Optional)
Model-specific information for the enforced guardrail configuration. If not present, the configuration is enforced on all models.
`"included_models"` (Required)
List of models to enforce the guardrail on. When empty, applies enforcement to all models. Also accepts the keyword “ALL” to explicitly include all models.
`"excluded_models"` (Required)
Models to exclude from enforcement of the guardrail. When empty, does not exclude any models from enforcement. If a model is present in both the included and excluded models lists, it is excluded.
# Amazon Inspector policies
Amazon Inspector policies allow you to centrally enable and manage Amazon Inspector across accounts in your AWS organization. With an Amazon Inspector policy, you specify which organizational entities (root, OUs, or accounts) have Amazon Inspector automatically enabled and linked to the Amazon Inspector delegated administrator account. You can use Amazon Inspector policies to simplify service-wide onboarding and ensure consistent enablement of Amazon Inspector in all existing and newly created accounts.
## Key Features and Benefits
Amazon Inspector policies let you define which scan types should be enabled for your organization or subsets of it, ensuring consistent coverage and reducing manual effort. When implemented, they help you onboard new accounts automatically and maintain your scanning baseline as your organization scales.
## How it works
When you attach an Amazon Inspector policy to an organizational entity, the policy automatically enables Amazon Inspector for all member accounts within that scope. Also, if you have finalized Amazon Inspector setup by registering a delegated administrator for Amazon Inspector, that account will have centralized vulnerability visibility over accounts in the organization that have Amazon Inspector enabled.
Amazon Inspector policies can be applied to the entire organization, to specific organizational units (OUs), or to individual accounts. Accounts that join the organization—or move into an OU with an attached Amazon Inspector policy—automatically inherit the policy and have Amazon Inspector enabled and linked to the Amazon Inspector delegated administrator. Amazon Inspector policies allow you to enable Amazon EC2 scanning, Amazon ECR scanning, or Lambda Standard and code scanning, as well as Code Security. Specific configuration settings and suppression rules can be managed via the delegated administrator account for the organization.
When you attach an Amazon Inspector policy to your organization or organizational unit, AWS Organizations automatically evaluates the policy and applies it based on the scope you define. The policy enforcement process follows specific conflict resolution rules:
+ When regions appear in both enable and disable lists, the disable configuration takes precedence. For example, if a region is listed in both enable and disable configurations, Amazon Inspector will be disabled in that region.
+ When `ALL_SUPPORTED` is specified for enablement, Amazon Inspector is enabled in all current and future regions unless explicitly disabled. This allows you to maintain comprehensive coverage as AWS expands into new regions.
+ Child policies can modify parent policy settings using inheritance operators, allowing for granular control at different organizational levels. This hierarchical approach ensures that specific organizational units can customize their security settings while maintaining baseline controls.
### Terminology
This topic uses the following terms when discussing Amazon Inspector policies.
| Term | Definition |
| --- | --- |
| Effective policy | The final policy that applies to an account after combining all inherited policies. |
| Policy inheritance | The process by which accounts inherit policies from parent organizational units. |
| Delegated administrator | An account designated to manage Amazon Inspector policies on behalf of the organization. |
| Service-linked role | An IAM role that allows Amazon Inspector to interact with other AWS services. |
### Use cases for Amazon Inspector policies
Organizations launching large-scale workloads across multiple accounts can use this policy to ensure all accounts immediately enable the correct scan types and avoid gaps. Regulatory or compliance-driven environments can use child policies to override or limit scan-types by OU. Rapid growth environments can automate enablement for newly created accounts so they're always compliant with the baseline.
### Policy inheritance and enforcement
Understanding how policies are inherited and enforced is crucial for effective security management across your organization. The inheritance model follows the AWS Organizations hierarchy, ensuring predictable and consistent policy application.
+ Policies attached at the root level apply to all accounts
+ Accounts inherit policies from their parent organizational units
+ Multiple policies can apply to a single account
+ More specific policies (closer to the account in the hierarchy) take precedence
### Policy validation
When creating Amazon Inspector policies, the following validations occur:
+ Region names must be valid AWS region identifiers
+ Regions must be supported by Amazon Inspector
+ Policy structure must follow AWS Organizations policy syntax rules
+ Both `enable_in_regions` and `disable_in_regions` lists must be present, though they can be empty
### Regional considerations and supported Regions
Amazon Inspector policies apply only in Regions where Amazon Inspector and AWS Organizations trusted access are available. Understanding regional behavior helps you implement effective security controls across your organization's global footprint.
+ Policy enforcement occurs in each Region independently
+ You can specify which Regions to include or exclude in your policies
+ New Regions are automatically included when using the `ALL_SUPPORTED` option
+ Policies only apply to Regions where Amazon Inspector is available
### Detachment behavior
If you detach an Amazon Inspector policy, Amazon Inspector remains enabled in previously covered accounts. However, future changes to the organizational structure (such as new accounts joining or existing accounts moving into the OU) will no longer automatically enable Amazon Inspector. Any further enablement must be performed manually or through re-attaching a policy.
## Additional details
### Delegated Administrator
Only one delegated administrator can be registered for Amazon Inspector in an organization. You must configure this in the Amazon Inspector console or via APIs before attaching Amazon Inspector policies.
### Prerequisites
You must enable trusted access for AWS Organizations, have a delegated administrator for Amazon Inspector registered, and have service-linked roles available in all accounts.
### Supported Regions
All Regions where Amazon Inspector is available.
# Getting started with Amazon Inspector policies
Before you configure Amazon Inspector policies, ensure you understand the prerequisites and implementation requirements. This topic guides you through the process of setting up and managing these policies in your organization.
## Learn about required permissions
To enable or attach Amazon Inspector policies, you must have the following permissions in the management account:
+ `organizations:EnableAWSServiceAccess` for `inspector2.amazonaws.com`
+ `organizations:RegisterDelegatedAdministrator` for `inspector2.amazonaws.com`
+ `organizations:AttachPolicy`, `organizations:CreatePolicy`, `organizations:DescribeEffectivePolicy`
+ `inspector2:Enable` (for management account and delegated admin)
## Before you begin
Review the following requirements before implementing Amazon Inspector policies:
+ Your account must be part of an AWS organization
+ You must be signed in as either:
+ The management account for the organization
+ An AWS Organizations delegated administrator with permissions to manage Amazon Inspector policies
+ You must enable trusted access for Amazon Inspector in your organization
+ You must enable the Amazon Inspector policy type in the root of your organization
Additionally, verify that:
+ Amazon Inspector is supported in the Regions where you want to apply policies
+ You have the `AWSServiceRoleForInspectorV2` service-linked role configured in your management account. To verify this role exists, run `aws iam get-role --role-name AWSServiceRoleForInspectorV2`. If you need to create this role, you can either run `aws inspector2 enable` in any Region from your management account, or create it directly by running `aws iam create-service-linked-role --aws-service-name inspector2.amazonaws.com`.
## Implementation steps
To implement Amazon Inspector policies effectively, follow these steps in sequence. Each step ensures proper configuration and helps prevent common issues during setup. The management account or delegated administrator can perform these steps through the AWS Organizations console, AWS Command Line Interface (AWS CLI), or AWS SDKs.
1. [Enable trusted access for Amazon Inspector](orgs_integrate_services.md#orgs_how-to-enable-disable-trusted-access).
1. [Enable Amazon Inspector policies for your organization](enable-policy-type.md).
1. [Create an Amazon Inspector policy](orgs_manage_policies_inspector_syntax.md).
1. [Attach the Amazon Inspector policy to your organization's root, OU, or account](orgs_policies_attach.md).
1. [View the combined effective Amazon Inspector policy that applies to an account](orgs_manage_policies_effective.md).
## Create an Amazon Inspector policy
### Minimum permissions
To create an Amazon Inspector policy, you need the following permission:
+ `organizations:CreatePolicy`
### AWS Management Console
**To create an Amazon Inspector policy**
1. Sign in to the [AWS Organizations console](https://console.aws.amazon.com/organizations/v2). You must sign in as an IAM user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization’s management account.
1. Set a delegated administrator for the service in use within Amazon Inspector console.
1. Once the delegated administrator has been set up for Amazon Inspector, visit AWS organization console to set up the policies. On AWS organization console, visit the Amazon Inspector Policies page, choose **Create policy**.
1. On the **Create new Amazon Inspector policy** page, enter a **Policy name** and an optional **Policy description**.
1. (Optional) You can add one or more tags to the policy by choosing **Add tag** and then entering a key and an optional value. Leaving the value blank sets it to an empty string; it isn't `null`. You can attach up to 50 tags to a policy. For more information, see [Tagging AWS Organizations resourcesConsiderations](orgs_tagging.md).
1. Enter or paste the policy text in the JSON code box. For information about the Amazon Inspector policy syntax, and example policies you can use as a starting point, see [Amazon Inspector policy syntax and examples](orgs_manage_policies_inspector_syntax.md).
1. When you're finished editing your policy, choose **Create policy** at the lower-right corner of the page.
# Best practices for using Amazon Inspector policies
When implementing Amazon Inspector policies across your organization, following established best practices helps ensure successful deployment and maintenance.
## Start simply and make small changes
Begin by enabling Amazon Inspector policies at a limited organizational unit (for example, "Security Pilot") to validate expected behavior before rolling out to all accounts. This incremental approach allows you to identify and resolve potential issues in a controlled environment before broader deployment.
## Establish review processes
Regularly monitor for new accounts joining your organization and confirm they inherit Amazon Inspector enablement automatically. Review policy attachment scopes quarterly to ensure your security coverage remains aligned with your organizational structure and security requirements.
## Validate changes using DescribeEffectivePolicy
After attaching or modifying a policy, run `DescribeEffectivePolicy` for representative accounts to ensure that Amazon Inspector enablement is reflected properly. This validation step helps you confirm that your policy changes have the intended effect across your organization.
## Communicate and train
Educate account owners that Amazon Inspector will be enabled automatically and findings may appear in their Security Hub or Amazon Inspector dashboards once they are linked to the Amazon Inspector delegated administrator. Clear communication helps ensure that account owners understand the security monitoring in place and can respond appropriately to findings.
## Plan your delegated administrator strategy
Designate a security or compliance account as the delegated administrator for Amazon Inspector. Set the delegated administrator from the Amazon Inspector console or via AWS Organizations APIs. This approach enables consistent security monitoring and management across your organization.
## Handle regional considerations
Enable Amazon Inspector in Regions where your workloads run. Consider your compliance requirements and operational needs when determining which Regions require Amazon Inspector coverage. Document your region-specific requirements to maintain consistent security monitoring across your infrastructure.
# Amazon Inspector policy syntax and examples
Amazon Inspector policies follow a standardized JSON syntax that defines how Amazon Inspector is enabled and configured across your organization. An Amazon Inspector policy is a JSON document structured according to the AWS Organizations management-policy syntax. It defines which organizational entities will have Amazon Inspector automatically enabled.
## Basic policy structure
An Amazon Inspector policy uses this basic structure:
```
{
"inspector": {
"enablement": {
"ec2_scanning": {
"enable_in_regions": {
"@@assign": ["us-east-1", "us-west-2"]
},
"disable_in_regions": {
"@@assign": ["eu-west-1"]
}
}
}
}
}
```
## Policy components
Amazon Inspector policies contain these key components:
`inspector`
The top-level key for Amazon Inspector policy documents, which is required for all Amazon Inspector policies.
`enablement`
Defines how Amazon Inspector is enabled across the organization, and contains scan type configurations.
`Regions (Array of Strings)`
Specifies the Regions where Amazon Inspector should be auto-enabled.
## Amazon Inspector policy examples
The following examples demonstrate common Amazon Inspector policy configurations.
### Example 1 – Enable Amazon Inspector organization-wide
The following example enables Amazon Inspector in `us-east-1` and `us-west-2` for all accounts in the organization root.
Create a file `inspector-policy-enable.json`:
```
{
"inspector": {
"enablement": {
"lambda_standard_scanning": {
"enable_in_regions": {
"@@assign": [
"us-east-1",
"us-west-2"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-1"
]
},
"lambda_code_scanning": {
"enable_in_regions": {
"@@assign": [
"us-east-1",
"us-west-2"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-1"
]
}
}
},
"ec2_scanning": {
"enable_in_regions": {
"@@assign": [
"us-east-1",
"us-west-2"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-1"
]
}
},
"ecr_scanning": {
"enable_in_regions": {
"@@assign": [
"us-east-1",
"us-west-2"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-1"
]
}
},
"code_repository_scanning": {
"enable_in_regions": {
"@@assign": [
"us-east-1",
"us-west-2"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-1"
]
}
}
}
}
}
```
When attached to the root, all accounts in the organization automatically enable Amazon Inspector, and their scan findings are available to the Amazon Inspector delegated administrator.
Create and attach the policy:
```
POLICY_ID=$(aws organizations create-policy \
--content file://inspector-policy-enable.json \
--name InspectorOrgPolicy \
--type INSPECTOR_POLICY \
--description "Inspector organization policy to enable all resources in IAD and PDX." \
--query 'Policy.PolicySummary.Id' \
--output text)
aws organizations attach-policy --policy-id $POLICY_ID --target-id
```
Any new account joining the organization automatically inherits enablement.
If detached, existing accounts remain enabled, but future accounts are not auto-enabled:
```
aws organizations detach-policy --policy-id $POLICY_ID --target-id
```
### Example 2 – Enable Amazon Inspector for a specific OU
Create a file `inspector-policy-eu-west-1.json`:
```
{
"inspector": {
"enablement": {
"lambda_standard_scanning": {
"enable_in_regions": {
"@@assign": [
"eu-west-1"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-2"
]
},
"lambda_code_scanning": {
"enable_in_regions": {
"@@assign": [
"eu-west-1"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-2"
]
}
}
},
"ec2_scanning": {
"enable_in_regions": {
"@@assign": [
"eu-west-1"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-2"
]
}
},
"ecr_scanning": {
"enable_in_regions": {
"@@assign": [
"eu-west-1"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-2"
]
}
},
"code_repository_scanning": {
"enable_in_regions": {
"@@assign": [
"eu-west-1"
]
},
"disable_in_regions": {
"@@assign": [
"eu-west-2"
]
}
}
}
}
}
```
Attach this to an OU to ensure all production accounts in `eu-west-1` will have Amazon Inspector enabled and linked to the Amazon Inspector delegated administrator:
```
aws organizations update-policy --policy-id $POLICY_ID --content file://inspector-policy-eu-west-1.json --description "Inspector organization policy - Enable all (eu-west-1)"
aws organizations attach-policy --policy-id $POLICY_ID --target-id ou-aaaa-12345678
```
Accounts outside the OU are unaffected.
# Upgrade rollout policies
AWS Organizations upgrade rollout policies allow you to centrally manage and stagger automatic upgrades across multiple AWS resources and accounts in your organization. With these policies, you can define the order in which resources receive upgrades, ensuring changes are validated in less critical environments before reaching production.
In today's complex cloud environments, managing upgrades across numerous resources and accounts can be challenging. Upgrade rollout policies address this challenge by providing a systematic approach to implementing upgrades. By using these policies, you can align your upgrade process with your organization's change management practices, reducing risk and improving operational efficiency.
Upgrade rollout policies leverage the hierarchical structure of AWS Organizations to apply policies across your entire organization or specific organizational units (OUs). This integration allows you to manage upgrades at scale, eliminating the need for manual coordination or custom automation scripts.
## Key features and benefits
Upgrade rollout policies provide comprehensive capabilities for managing upgrades while offering significant advantages for organizations managing resources across multiple accounts and environments. The following table outlines the key features and their associated benefits:
**Features and benefits of upgrade rollout policies**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_upgrade_rollout.html)
For more information about policy inheritance, see [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md).
## What are upgrade rollout policies?
Upgrade rollout policies are a set of rules that determine how and when automatic upgrades are applied to your AWS resources. These policies allow you to designate different upgrade orders for your resources, typically aligning with your development, testing, and production environments. By doing so, you can ensure that upgrades are first applied to less critical systems, allowing you to identify and address any issues before they affect your production workloads.
The policies support three upgrade orders: First, Second, and Last. These orders create a staged approach to upgrades, with resources designated as "First" receiving upgrades initially, followed by "Second" after a waiting period, and finally "Last" after another waiting period. This staggered approach gives you time to validate upgrades at each stage before they progress to more critical systems.
Upgrade rollout policies are particularly valuable for organizations with complex, multi-account structures or those with strict change management requirements. They provide a balance between maintaining up-to-date systems and minimizing the risk of upgrade-related disruptions to critical services.
## How upgrade rollout policies work
Upgrade rollout policies integrate seamlessly with your existing AWS infrastructure and processes. When you create and attach an upgrade rollout policy to an organizational unit, it applies to all accounts within that OU. You can then use resource tags or patch orders to specify which resources should be upgraded in which order.
When a supported AWS service releases an upgrade, it consults the upgrade rollout policies to determine the order in which resources should receive the upgrade. The service first applies the upgrade to resources marked as "First" during their configured maintenance windows. After a service-specific waiting period, typically around one week, resources marked as "Second" become eligible for the upgrade. Finally, after another waiting period, resources marked as "Last" receive the upgrade.
This process ensures that upgrades are applied in a controlled, predictable manner across your organization. It allows you to monitor the impact of upgrades at each stage and take corrective action if needed before the changes reach your most critical environments. The automated nature of this process reduces the operational overhead of managing upgrades, while still providing you with the control and visibility you need to maintain the stability and security of your AWS resources.
## Terminology
Here are the key terms you should understand when working with upgrade rollout policies:
**Upgrade rollout policy terms**
| Term | Definition |
| --- | --- |
| Active Date | The date when the AmVU becomes visible in the Describe Pending Maintenance Actions API and available for application. |
| AmVU (Auto minor version upgrade) | The automatic upgrade process for minor versions of database engines. |
| Effective policy | The final set of rules that apply to an account or resource after considering all inherited and directly attached policies. |
| Maintenance window | A recurring time period during which automatic upgrades can be applied to a resource. Upgrade rollout policies work within these configured maintenance windows. |
| Organizational unit (OU) | A container for AWS accounts in your organization. Upgrade rollout policies can be attached at the OU level to affect all accounts within it. |
| Patch order | The sequence in which resources receive upgrades (First, Second, Last). |
| Policy target | The scope to which an upgrade rollout policy applies, which can be an entire organization, specific OUs, or individual accounts. |
| Resource tags | Key-value pairs that can be used to identify which resources should follow specific upgrade orders within a policy. |
| Scheduling window | The time frame during which resources of a specific patch order receive upgrades. |
| Service-specific waiting period | The designated time interval between upgrading resources of different upgrade orders. This period varies by AWS service and upgrade type. |
| Upgrade order | A designation that determines when a resource receives upgrades relative to other resources. Can be set to First, Second, or Last. |
| Upgrade rollout policy | The AWS Organizations policy type used to manage upgrade schedules across resources. |
## Use cases for upgrade rollout policies
Organizations of different sizes and industries can benefit from upgrade rollout policies. The following fictitious scenarios demonstrate common upgrade management challenges and how upgrade rollout policies provide efficient solutions. These examples are based on typical customer experiences but have been simplified to highlight key benefits and implementation patterns.
Many organizations face similar challenges: they need to keep their resources up-to-date with the latest versions while minimizing risk to their production environments. Without a centralized policy-based approach, teams often resort to manual processes or complex automation scripts. The following examples demonstrate how two different organizations might solve similar challenges using upgrade rollout policies:
### Example use case: Global Financial Services Company
A financial services company operates hundreds of Aurora PostgreSQL databases across multiple AWS accounts. Before upgrade rollout policies, their DevOps team spent several days each month manually coordinating database upgrades, ensuring changes were tested in development environments before reaching production systems. By implementing upgrade rollout policies, they:
+ Tagged development databases with upgrade order "First"
+ Assigned QA databases to upgrade order "Second"
+ Designated production databases as upgrade order "Last"
+ Reduced upgrade coordination from days to minutes
+ Automatically validated changes in lower environments first
+ Maintained compliance with their change management requirements
### Example use case: IoT Device Platform Provider
An IoT company processes millions of device events daily using multiple Amazon RDS databases. They needed to ensure automatic minor version upgrades wouldn't disrupt their production services. Using upgrade rollout policies, they:
+ Created a policy that applies across their organizational structure
+ Configured canary environments to receive upgrades first
+ Set up monitoring in early-upgrade environments
+ Gained time to detect and respond to any issues before production upgrades
+ Replaced complex custom upgrade automation with a simple policy
+ Maintained high availability for their production workloads while staying current with database versions
## Supported AWS services
Upgrade rollout policies integrate with the following AWS services while supporting automatic minor version upgrades:
**Supported services for upgrade rollout policies**
| Service name | Purpose |
| --- | --- |
| Amazon Aurora PostgreSQL-Compatible Edition | [ Automatic minor version upgrades](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.Maintenance.html#Aurora.Maintenance.AMVU) |
| Amazon Aurora MySQL-Compatible Edition | [ Automatic minor version upgrades](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_UpgradeDBInstance.Maintenance.html#Aurora.Maintenance.AMVU) |
| Amazon Relational Database Service for PostgreSQL | [ Automatic minor version upgrades](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.PostgreSQL.Minor.html) |
| Amazon Relational Database Service for SQL Server | [Automatic minor version upgrades](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.SQLServer.html) |
| Amazon Relational Database Service for Oracle | [ Automatic minor version upgrades](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.Oracle.Minor.html#oracle-minor-version-upgrade-tuning-on) |
| Amazon Relational Database Service for MariaDB | [ Automatic minor version upgrades](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.MariaDB.Minor.html) |
| Amazon Relational Database Service for MySQL | [ Automatic minor version upgrades](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.MySQL.Minor.html) |
| Amazon Relational Database Service for Db2 | [Automatic minor version upgrades](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Db2.Concepts.VersionMgmt.html) |
## Prerequisites
The following are prerequisites and required permissions necessary for managing upgrade rollout policies in AWS Organizations:
+ AWS Organizations management account or delegated administrator access
+ Resources in supported services (currently Amazon Aurora and Amazon Relational Database Service database engines)
+ Proper IAM permissions to manage upgrade rollout policies
## Next steps
To begin using upgrade rollout policies:
1. Review the [Getting started with upgrade rollout policies](orgs_manage_policies_upgrade_getting_started.md) to learn how to create and manage policies
1. Explore [Best practices for using upgrade rollout policies](orgs_manage_policies_upgrade_best_practices.md) for implementing upgrade rollout policies
1. Understand [Upgrade rollout policy syntax and examples](orgs_manage_policies_upgrade_syntax.md)
# Getting started with upgrade rollout policies
Follow these steps to implement upgrade rollout policies in your organization. Each step links to detailed information to help you complete the implementation successfully.
## Before you begin
Ensure you have the following:
+ Administrative access to AWS Organizations
+ Resources in supported AWS services (such as Aurora or Amazon Relational Database Service)
+ Necessary IAM permissions configured
## Implementation steps
1. [Enable upgrade rollout policies for your organization.](enable-policy-type.md)
1. [Understand how upgrade rollout policies work.](orgs_manage_policies_upgrade_rollout.md#orgs_manage_policies_upgrade_rollout_how_work)
+ Identify development, testing, and production environments
+ Determine which resources should be upgraded first, second, and last
+ Document your tagging strategy for resource identification
1. [Create a upgrade rollout policy](orgs_policies_create.md#create-upgrade-rollout-policy-procedure):
+ Define the default rollout order (organizational unit or account level)
+ Specify resource targeting using tags
+ Configure any policy exclusions
1. [Attach an upgrade rollout policy to a single member account that you can use for testing.](orgs_policies_attach.md):
+ Start with a test organizational unit
+ Verify policy inheritance
+ Confirm policy attachment status
1. Tag your resources according to your upgrade order strategy:
+ Apply tags to development resources for first upgrades
+ Tag testing resources for second-order upgrades
+ Designate production resources for last-order upgrades
1. Monitor and validate the policy:
+ Review upgrade order assignments
+ Verify policy effects on test resources
1. Test the upgrade process:
+ Wait for a service upgrade to become available
+ Monitor the upgrade progression through your environments
+ Verify that upgrades follow your specified order
1. Enable upgrade rollout policies for additional organizational units as needed
**Other information**
+ [Learn upgrade rollout policy syntax and see example policies](orgs_manage_policies_upgrade_syntax.md)
# Best practices for using upgrade rollout policies
AWS recommends the following best practices for using upgrade rollout policies.
**Topics**
+ [Start small and scale gradually](#orgs_manage_policies_upgrade_best_practices_scale)
+ [Establish review processes](#orgs_manage_policies_upgrade_best_practices_review)
+ [Validate policy changes effectively](#orgs_manage_policies_upgrade_best_practices_validate)
+ [Monitor and communicate changes](#orgs_manage_policies_upgrade_best_practices_monitor)
+ [Maintain compliance and security](#orgs_manage_policies_upgrade_best_practices_compliance)
+ [Optimize operational efficiency](#orgs_manage_policies_upgrade_best_practices_optimize)
## Start small and scale gradually
Begin your implementation with a test policy attached to a single account in a non-critical environment. This approach allows you to validate the behavior and impact of upgrade rollout policies without risking disruption to critical workloads. Once you've confirmed the policy works as expected, incrementally move it up your organizational structure to include more accounts and organizational units.
This gradual scaling helps you identify and address any issues early in the implementation process. Consider creating a pilot group of resources that represents the diversity of your environment but carries minimal operational risk. Document the results of each expansion phase to inform future policy rollouts and adjustments.
## Establish review processes
Implement regular review processes to monitor for new upgrade rollout policy attributes and evaluate policy exceptions. These reviews should align with your organization's security and operational requirements. Create a schedule for reviewing policy effectiveness and maintain documentation of any adjustments made.
Your review process should include regular assessments of which resources are governed by policies, verification that upgrade orders align with your intended strategy, and evaluation of any policy exceptions. Consider establishing criteria for when policies need updating and maintain a change log to track policy evolution over time.
## Validate policy changes effectively
After making changes to an upgrade rollout policy, check the effective policies for representative accounts at each level of your organization. Use the AWS Management Console or `DescribeEffectivePolicy` API operation to verify that your changes have the intended impact. This validation should include checking resources across different organizational units and confirming that inheritance works as expected.
Pay special attention to resources that have explicit upgrade orders assigned versus those using default values. Establish a validation checklist that includes verifying tag-based targeting, confirming maintenance window alignments, and testing policy inheritance.
## Monitor and communicate changes
Establish comprehensive monitoring for your upgrade rollout policies and create clear communication channels for sharing upgrade-related information. Document clear procedures for handling upgrade failures and create response plans for different scenarios.
Maintain regular communication with teams managing resources affected by upgrade policies. Consider creating dashboards that provide visibility into upcoming upgrades and their expected progression through your environments.
## Maintain compliance and security
Regularly audit your upgrade rollout policies to ensure they align with your compliance requirements. Document all policy decisions and maintain clear records of upgrade patterns and exceptions. Implement security controls around policy modifications and maintain an audit trail of policy changes using AWS CloudTrail.
Review access permissions to policy management functions regularly and implement least-privilege access for policy administration. Create procedures for emergency policy modifications and maintain documentation of security-related upgrade requirements.
## Optimize operational efficiency
Design your policies to minimize operational overhead while maintaining necessary controls. To prevent unintended behavior, do not reuse tags across different use cases. Automate policy compliance checking where possible and create standard operating procedures for common policy management tasks.
Consider creating templates for different types of upgrade scenarios and maintain documentation of successful policy patterns. Regular review of operational metrics can help identify opportunities for policy optimization and process improvement.
# Upgrade rollout policy syntax and examples
An upgrade rollout policy defines how AWS services apply automatic upgrades across your resources. Understanding the policy syntax helps you create effective policies that match your organization's upgrade requirements.
**Topics**
+ [Considerations](#orgs_manage_policies_upgrade_syntax_considerations)
+ [Basic policy structure](#orgs_manage_policies_upgrade_syntax_structure)
+ [Policy components](#orgs_manage_policies_upgrade_syntax_components)
+ [Upgrade rollout policy examples](#orgs_manage_policies_upgrade_syntax_examples)
## Considerations
When implementing upgrade rollout policies, consider these important factors:
+ Policy names must be unique within your organization and should be clear and descriptive. Choose names that reflect the policy's purpose and scope. For more information, see [Optimize operational efficiency](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_optimize).
+ Testing is crucial before broad deployment. Validate new policies in non-production environments first and expand gradually to ensure desired behavior. For more information, see [Start small and scale gradually](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_scale).
+ Policy changes may take several hours to propagate across your organization. Plan your implementations accordingly and ensure proper monitoring is in place. For more information, see [Monitor and communicate changes](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_monitor).
+ JSON formatting must be valid and stay within the maximum policy size of 5,120 bytes. Keep policy structures as simple as possible while meeting your requirements.
+ Regular policy reviews help maintain effectiveness. Schedule periodic evaluations of your policies to ensure they continue to meet your organizational needs. For more information, see [Establish review processes](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_review).
+ Resources without an assigned upgrade order default to the "Second" order. Consider explicitly setting upgrade orders for critical resources rather than relying on defaults. For more information, see [Validate policy changes effectively](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_validate).
+ Manual upgrades take precedence over policy-defined upgrade orders. Ensure your change management processes account for both automatic and manual upgrade scenarios. For more information, see [Establish review processes](orgs_manage_policies_upgrade_best_practices.md#orgs_manage_policies_upgrade_best_practices_review).
**Note**
When implementing tag-based upgrade rollout policies from your management account, be aware that the management account cannot directly view or access resource-level tags in member accounts. We recommend establishing a process where member accounts apply consistent resource tags, and then create organization-level policies that reference these tags. This ensures proper coordination between resource-level tagging and organizational policy enforcement. You can also use [Tag policies](orgs_manage_policies_tag-policies.md) to help maintain consistent tags when resources are tagged across your organization.
## Basic policy structure
Upgrade rollout policies use a JSON structure that includes the following main elements:
+ Policy metadata (such as version information)
+ Resource targeting rules
+ Upgrade order specifications
+ Optional exception messages
+ Service-specific attributes
The following example shows a basic upgrade rollout policy structure:
```
{
"upgrade_rollout":{
"default":{
"patch_order":{
"@@assign":"last"
}
},
"tags":{
"devtag":{
"tag_values":{
"tag1":{
"patch_order":{
"@@assign":"first"
}
},
"tag2":{
"patch_order":{
"@@assign":"second"
}
},
"tag3":{
"patch_order":{
"@@assign":"last"
}
}
}
}
}
}
}
```
## Policy components
An upgrade rollout policy consists of two key components that work together to control how upgrades are applied across your resources. These components include configuration options for both default behaviors and tag-based overrides. Understanding how these components interact helps you create effective policies that match your organizational needs.
### Default patch order setup
When you create an upgrade rollout policy without specifying any resource-specific overrides, all resources default to a base upgrade order. You can set this default using the "default" field in your policy. Resources without explicit upgrade order assignments through tags will follow this default order.
**Note**
The console experience today requires a default order to be specified.
The following example shows how to set all resources to receive upgrades last by default, unless overridden by tags. This approach is useful when you want to ensure most resources update later in the upgrade cycle:
```
"upgrade_rollout": {
"default": {
"patch_order": "last"
}
}
```
### Resource level overriding via Tags
You can override the default upgrade order for specific resources using tags. This allows you to create granular control over which resources receive upgrades in which order. For example, you can assign different upgrade orders based on your environment types, development stages, or workload criticality.
The following example shows how to configure development resources to receive upgrades first and production resources to receive them last. This configuration ensures your development environments can validate upgrades before they reach production:
```
"upgrade_rollout": {
"tags": {
"environment": {
"tag_values": {
"development": {
"patch_order": "first"
},
"production": {
"patch_order": "last"
}
}
}
}
}
```
## Upgrade rollout policy examples
Here are common upgrade rollout policy scenarios:
### Example 1: Development environment first
This example shows how to configure resources in your development environment to receive upgrades first. By targeting resources with the "development" environment tag, you ensure your development environments are the first to receive and validate new upgrades. This pattern helps identify potential issues before upgrades reach more critical environments:
```
{
"tags": {
"environment": {
"tag_values": {
"development": {
"upgrade_order": "first"
}
}
}
}
}
```
### Example 2: Production environment last
This example demonstrates how to ensure your production environments receive upgrades last. By explicitly setting production-tagged resources to the last upgrade order, you maintain stability in your production environment while allowing adequate testing in pre-production environments. This approach is particularly useful for organizations with strict change management requirements:
```
{
"tags": {
"environment": {
"tag_values": {
"production": {
"upgrade_order": "last"
}
}
}
}
}
```
### Example 3: Multiple upgrade orders using tags
The following example demonstrates how to use a single tag key with different values to specify all three upgrade orders. This approach is useful when you want to manage upgrade orders through a single tagging scheme:
```
{
"upgrade_rollout":{
"default":{
"patch_order":{
"@@assign":"last"
}
},
"tags":{
"devtag":{
"tag_values":{
"tag1":{
"patch_order":{
"@@assign":"first"
}
},
"tag2":{
"patch_order":{
"@@assign":"second"
}
},
"tag3":{
"patch_order":{
"@@assign":"last"
}
}
}
}
}
}
}
```
# Amazon S3 policies
Amazon S3 policies allow you to centrally manage configurations for Amazon S3 resources at scale across the accounts in an organization. Amazon S3 policies currently support settings for blocking public access.
You can use an Amazon S3 policy to specify whether to enable or disable all four Block Public Access settings, and that specification will apply to all Amazon S3 resources within selected accounts. You can use Block Public Access settings in an Amazon S3 policy to enforce consistent security posture across your organization and eliminate the operational overhead of managing individual account configurations.
## How it works
When you attach an Amazon S3 policy to an organizational entity, it defines settings that apply to all Amazon S3 resources within accounts in that scope. These configurations override account-level settings, allowing you to centrally manage Amazon S3 settings.
Amazon S3 policies can be applied to an entire organization, organizational units (OUs), or individual accounts. Accounts joining an organization will automatically inherit any Amazon S3 policies based on their location in the organization hierarchy.
Detachment behavior: If an Amazon S3 policy is detached, accounts automatically revert to their previous account-level configuration. Amazon S3 preserves the original account-level settings to enable seamless restoration.
## Key features
+ Unified control: All four Block Public Access settings (BlockPublicAcls, BlockPublicPolicy, IgnorePublicAcls, RestrictPublicBuckets) are controlled together as a single configuration
+ Automatic inheritance: New accounts automatically inherit policies based on their organizational placement
+ Override protection: Prevents account-level modifications when organization policies are active
+ Seamless restoration: Original account settings are preserved and restored when policies are detached
## Prerequisites
Before using Amazon S3 policies, ensure you have:
+ An AWS organization in all features mode
+ Permissions to manage AWS Organizations policies (organizations:CreatePolicy, organizations:AttachPolicy, etc.)
+ The Amazon S3 policy type enabled for your organization
# Best practices for using Amazon S3 policies
When implementing Amazon S3 policies across your organization, following established best practices helps ensure successful deployment and maintenance.
## Start simply and make small changes
To simplify debugging, start with simple policies and make changes one item at a time. Validate the behavior and impact of each change before making the next change. This approach reduces the number of variables you have to account for when an error or unexpected result does happen.
## Establish review processes
Implement processes to monitor for new policy attributes, evaluate policy exceptions, and make adjustments to maintain alignment with your organizational security and operational requirements.
## Validate changes to your Amazon S3 policies using DescribeEffectivePolicy
After you make a change to an Amazon S3 policy, check the effective policies for representative accounts below the level where you made the change. You can view the effective policy by using the AWS Management Console, or by using the DescribeEffectivePolicy API operation or one of its AWS CLI or AWS SDK variants. Ensure that the change you made had the intended impact on the effective policy.
## Communicate and train
Ensure your organization understands the purpose and impact of your policies. Provide clear guidance on the expected behaviors and how to handle failures due to policy enforcement.
## Plan for legitimate public access needs
Before implementing organization-level policies, identify accounts that require public Amazon S3 buckets for legitimate business purposes (such as static website hosting). Consider using OU-level or account-level policy attachment to exclude these accounts, or consolidate public bucket needs into dedicated accounts.
## Monitor policy enforcement
Use AWS CloudTrail to monitor policy attachment and enforcement actions. Set up EventBridge rules to automate responses to policy violations or changes.
# Amazon S3 policy syntax and examples
An Amazon S3 policy is a plaintext file that is structured according to the rules of [JSON](http://json.org). The syntax for Amazon S3 policies follows the syntax for all management policy types. For more information, see [Understanding management policy inheritance](orgs_manage_policies_inheritance_mgmt.md). This topic focuses on applying that general syntax to the specific requirements of the Amazon S3 policies and the Block Public Access settings they help manage.
The following Amazon S3 policy example shows the basic policy syntax:
```
{
"s3_attributes": {
"public_access_block_configuration": {
"@@assign": "all"
}
}
}
```
## The Amazon S3 policy syntax includes the following elements
`s3_attributes`
The top-level key for Amazon S3 policy configuration.
`public_access_block_configuration`
Defines the Block Public Access behavior for the organization.
`@@assign`
The assignment operator that accepts one of two values:
+ `"all"` - Enables all four Amazon S3 Block Public Access settings at the organization level
+ `"none"` - Disables organization-level control, allowing individual accounts to manage their own Block Public Access settings
Amazon S3 Block Public Access has four settings that control public access:
1. **BlockPublicAcls** - Amazon S3 will block public access permissions applied to newly added buckets or objects, and prevent the creation of new public access control lists (ACLs) for existing buckets and objects. This setting doesn't change any existing permissions that allow public access to Amazon S3 resources using ACLs.
1. **BlockPublicPolicy** - Amazon S3 will block new bucket and access point policies that grant public access to buckets and objects. This setting doesn't change any existing policies that allow public access to Amazon S3 resources.
1. **IgnorePublicAcls** - Amazon S3 will ignore all ACLs that grant public access to buckets and objects.
1. **RestrictPublicBuckets** - Amazon S3 will ignore public and cross-account access for buckets or access points with policies that grant public access to buckets and objects.
When you set `@@assign` to `"all"`, all four settings are consolidated and enabled at the organization level, providing comprehensive protection against public access across all accounts in your organization.
# AWS Shield Network Security Director policies
AWS Shield Network Security Director helps secure your AWS environment by discovering your compute, networking, and network security resources. Network Security Director evaluates each resource's security configuration by analyzing network topology and security configurations against AWS best practices and threat intelligence.
AWS Shield Network Security Director policies allow you to centrally enable and manage Network Security Director across accounts in your AWS organization. With a Network Security Director policy, you specify which organizational entities (root, OUs, or accounts) have Network Security Director enabled. When accounts join your organization, they automatically inherit the applicable policies based on their location in the organizational hierarchy. This ensures that your resources are analyzed for network security configuration gaps as your organization grows. The policies respect existing organizational structures and provide flexibility in determining which accounts are analyzed.
AWS Shield Network Security Director is currently available in preview.
## How it works
When you attach an AWS Shield Network Security Director policy to an organizational entity, the policy automatically enables Network Security Director for all member accounts within that scope. Also, if you have finalized AWS Shield Network Security Director setup by registering a delegated administrator, that account will have centralized visibility over the network security posture of accounts in the organization that have AWS Shield Network Security Director enabled.
AWS Shield Network Security Director policies can be applied to the entire organization, to specific organizational units (OUs), or to individual accounts. Accounts that join the organization—or move into an OU with an attached policy—automatically inherit the policy and have AWS Shield Network Security Director enabled and linked to the Network Security Director delegated administrator. Network Security Director policies allow you to enable a network analysis, view the network topology and network security findings for your resources, and receive remediation recommendations for resolving configuration gaps. Specific configuration settings and suppression of individual findings can be managed via the Network Security Director delegated administrator account for the organization.
When you attach an AWS Shield Network Security Director policy to your organization or organizational unit, AWS Organizations automatically evaluates the policy and applies it based on the scope you define. The policy enforcement logic follows specific conflict resolution rules:
+ When regions appear in both enable and disable lists, the disable configuration takes precedence. For example, if a region is listed in both enable and disable configurations, AWS Shield Network Security Director will be disabled in that region.
+ When `ALL_SUPPORTED` is specified for enablement, AWS Shield Network Security Director is enabled in all current and future regions unless explicitly disabled. This allows you to maintain comprehensive coverage as AWS expands into new regions.
# Getting started with AWS Shield Network Security Director policies
Before you configure Network Security Director policies, ensure you understand the prerequisites and implementation requirements. This topic guides you through the process of setting up and managing these policies in your organization.
## Before you begin
Review the following requirements before implementing AWS Shield Network Security Director policies:
+ Your account must be part of an AWS organization
+ You must be signed in as either:
+ The management account for the organization
+ An AWS Organizations delegated administrator with permissions to manage AWS Shield Network Security Director policies
+ You must enable trusted access for Network Security Director in your organization
+ You must enable the Network Security Director policy type in the root of your organization
Additionally, verify that:
+ AWS Shield Network Security Director is supported in the Regions where you want to apply policies
+ You have the AWS Shield Network Security Director service-linked role configured in your management account. If you need to create this role, you can create it directly by running `aws iam create-service-linked-role --aws-service-name network-director.amazonaws.com`.
## Implementation steps
To implement Network Security Director policies effectively, follow these steps in sequence. Each step ensures proper configuration and helps prevent common issues during setup. These steps can be performed through the AWS Organizations console, AWS Command Line Interface (AWS CLI), or AWS SDKs.
1. [Enable trusted access for AWS Shield Network Security Director](orgs_integrate_services.md#orgs_how-to-enable-disable-trusted-access).
1. [Enable AWS Shield Network Security Director policies for your organization](enable-policy-type.md).
1. [Create an AWS Shield Network Security Director policy](orgs_manage_policies_network_security_director_syntax.md).
1. [Attach the policy to your organization's root, OU, or account](orgs_policies_attach.md).
1. [View the combined effective Network Security Director policy that applies to an account](orgs_manage_policies_effective.md).
# AWS Shield Network Security Director policy syntax and examples
Network Security Director policies follow a standardized JSON syntax that defines how Network Security Director is enabled and configured across your organization. An AWS Shield Network Security Director policy is a JSON document structured according to the AWS Organizations management-policy syntax. It defines which organizational entities will have AWS Shield Network Security Director automatically enabled.
## Basic policy structure
An AWS Shield Network Security Director policy uses this basic structure:
```
{
"network_security_director": {
"enablement": {
"network_security_scan": {
"enable_in_regions": {
"@@assign": ["us-east-1", "eu-west-1"]
},
"disable_in_regions": {
"@@assign": []
}
}
},
}
}
}
```
## Policy components
AWS Shield Network Security Director policies contain these key components:
`network_security_director`
The top-level key for Network Security Director policy documents, which is required for all Network Security Director policies.
`enablement`
Defines how Network Security Director is enabled across the organization, and contains scan configurations.
`network_security_scan`
Defines enforcement configuration for network security scanning.
`enable_in_regions`
Configuration identifier for region settings. Defines where the network security scan should be enabled.
`disable_in_regions`
Configuration identifier for region settings. Defines where the network security scan should be disabled.