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.
Topics
- How declarative policies work
- Custom error messages for declarative policies
- Account status report for declarative policies
- Supported AWS services and attributes
- Getting started with declarative policies
- Best practices for using declarative policies
- Generating the account status report for declarative policies
- Declarative policy syntax and examples
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). 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. |
| Example policy | Deny access to AWS based on the requested AWS Region | Restrict access to only HTTPS connections to your resources | Allowed Images Settings |
After you have created and attached 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.
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.
If a declarative policy is detached, 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.
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, Instance Metadata Defaults, Snapshot Block Public Access, and Allowed Images Settings. 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.
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.
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.
| AWS service | Attribute | Policy effect | Policy contents | More information |
|---|---|---|---|---|
| Amazon VPC | VPC Block Public Access | Controls if resources in Amazon VPCs and subnets can reach the internet through internet gateways (IGWs). | View policy | For more information, see Block public access to VPCs and subnets in the Amazon VPC User Guide. |
| Amazon EC2 | Serial Console Access | Controls if the EC2 serial console is accessible. | View policy | For more information, see Configure access to the EC2 Serial Console in the Amazon Elastic Compute Cloud User Guide. |
| Image Block Public Access | Controls if Amazon Machine Images (AMIs) are publicly sharable. | View policy | For more information, see Understand block public access for AMIs in the Amazon Elastic Compute Cloud User Guide. | |
| Allowed Images Settings | Controls the discovery and use of Amazon Machine Images (AMI) in Amazon EC2 with Allowed AMIs. | View policy | For more information, see Amazon Machine Images (AMIs) in the Amazon Elastic Compute Cloud User Guide. | |
| Instance Metadata Defaults | Controls IMDS defaults for all new EC2 instances launches. | View policy | For more information, see Configure instance metadata options for new instances in the Amazon Elastic Compute Cloud User Guide. | |
| Amazon EBS | Snapshot Block Public Access | Controls if Amazon EBS snapshots are publicly accessible. | View policy | For more information, see Block public access for Amazon EBS snapshots in the Amazon Elastic Block Store User Guide. |
