# Declarative policies
<a name="orgs_manage_policies_declarative"></a>

Declarative policies allow you to centrally declare and enforce your desired configuration for a given Amazon Web Services 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 Amazon Web Services service with a few selections in the Amazon Organizations and Amazon Control Tower consoles or with a few commands using the Amazon CLI & Amazon SDKs.
+ **Set once and forget**: The baseline configuration for an Amazon Web Services 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 Amazon Web Services services and attributes, see [Supported Amazon Web Services 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
<a name="orgs_manage_policies_declarative-how-work"></a>

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.amazonaws.cn/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 Amazon 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 Amazon Web Services 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.amazonaws.cn/organizations/latest/userguide/orgs_policies_create.html#create-declarative-policy-procedure) and [attached](https://docs.amazonaws.cn/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.amazonaws.cn/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
<a name="orgs_manage_policies_declarative-custom-message"></a>

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, Amazon 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 Amazon CloudTrail. CloudTrail can flag API operation failures due to declarative policies. For more information, see [Logging and monitoring](https://docs.amazonaws.cn/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
<a name="orgs_manage_policies_declarative-account-status-report"></a>

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.amazonaws.cn/en_us/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 Amazon Web Services services and attributes
<a name="orgs_manage_policies_declarative-supported-controls"></a>

### Supported attributes for declarative policies for EC2
<a name="orgs_manage_policies_declarative-supported-controls-ec2"></a>

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.amazonaws.cn/en_us/organizations/latest/userguide/orgs_manage_policies_declarative.html)