policies

Creates, updates, deletes, gets or lists a policies resource.

Overview

Name	policies
Type	Resource
Id	aws.organizations.policies

Fields

The following fields are returned by SELECT queries:

describe_policy

Name	Datatype	Description
content	string	The text content of the policy. (pattern: <code>[\s\S]*</code>)
policy_summary	object	A structure that contains additional details about the policy.

list_policies

Name	Datatype	Description
arn	string	The Amazon Resource Name (ARN) of the policy. For more information about ARNs in Organizations, see ARN Formats Supported by Organizations in the Amazon Web Services Service Authorization Reference. (pattern: <code>^(arn:aws:organizations::\d{12}:policy/o-[a-z0-9]{10,32}/[0-9a-z_]+/p-[0-9a-z]{10,32})|(arn:aws:organizations::aws:policy/[0-9a-z_]+/p-[0-9a-zA-Z_]{10,128})</code>)
aws_managed	boolean	A boolean value that indicates whether the specified policy is an Amazon Web Services managed policy. If true, then you can attach the policy to roots, OUs, or accounts, but you cannot edit it.
description	string	The description of the policy. (pattern: <code>[\s\S]*</code>)
id	string	The unique identifier (ID) of the policy. The regex pattern for a policy ID string requires "p-" followed by from 8 to 128 lowercase or uppercase letters, digits, or the underscore character (). (pattern: <code>^p-[0-9a-zA-Z]{8,128}$</code>)
name	string	The friendly name of the policy. The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range. (pattern: <code>[\s\S]*</code>)
type	string	The type of policy. (SERVICE_CONTROL_POLICY, RESOURCE_CONTROL_POLICY, TAG_POLICY, BACKUP_POLICY, AISERVICES_OPT_OUT_POLICY, CHATBOT_POLICY, DECLARATIVE_POLICY_EC2, SECURITYHUB_POLICY, INSPECTOR_POLICY, UPGRADE_ROLLOUT_POLICY, BEDROCK_POLICY, S3_POLICY, NETWORK_SECURITY_DIRECTOR_POLICY)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_policy	select	region		Retrieves information about a policy. You can only call this operation from the management account or a member account that is a delegated administrator.
list_policies	select	region		Retrieves the list of all policies in an organization of a specified type. When calling List* operations, always check the NextToken response parameter value, even if you receive an empty result set. These operations can occasionally return an empty set of results even when more results are available. Continue making requests until NextToken returns null. A null NextToken value indicates that you have retrieved all available results. You can only call this operation from the management account or a member account that is a delegated administrator.
create_policy	insert	region, Content		Creates a policy of a specified type that you can attach to a root, an organizational unit (OU), or an individual Amazon Web Services account. For more information about policies and their use, see Managing Organizations policies. If the request includes tags, then the requester must have the organizations:TagResource permission. You can only call this operation from the management account or a member account that is a delegated administrator.
attach_policy	update	region, PolicyId, TargetId		Attaches a policy to a root, an organizational unit (OU), or an individual account. How the policy affects accounts depends on the type of policy. Refer to the Organizations User Guide for information about each policy type: SERVICE_CONTROL_POLICY RESOURCE_CONTROL_POLICY DECLARATIVE_POLICY_EC2 BACKUP_POLICY TAG_POLICY CHATBOT_POLICY AISERVICES_OPT_OUT_POLICY SECURITYHUB_POLICY UPGRADE_ROLLOUT_POLICY INSPECTOR_POLICY BEDROCK_POLICY S3_POLICY NETWORK_SECURITY_DIRECTOR_POLICY You can only call this operation from the management account or a member account that is a delegated administrator.
update_policy	update	region, PolicyId		Updates an existing policy with a new name, description, or content. If you don't supply any parameter, that value remains unchanged. You can't change a policy's type. You can only call this operation from the management account or a member account that is a delegated administrator.
delete_policy	delete	region		Deletes the specified policy from your organization. Before you perform this operation, you must first detach the policy from all organizational units (OUs), roots, and accounts. You can only call this operation from the management account or a member account that is a delegated administrator.
detach_policy	exec	region, PolicyId, TargetId		Detaches a policy from a target root, organizational unit (OU), or account. If the policy being detached is a service control policy (SCP), the changes to permissions for Identity and Access Management (IAM) users and roles in affected accounts are immediate. Every root, OU, and account must have at least one SCP attached. If you want to replace the default FullAWSAccess policy with an SCP that limits the permissions that can be delegated, you must attach the replacement SCP before you can remove the default SCP. This is the authorization strategy of an "allow list". If you instead attach a second SCP and leave the FullAWSAccess SCP still attached, and specify "Effect": "Deny" in the second SCP to override the "Effect": "Allow" in the FullAWSAccess policy (or any other attached SCP), you're using the authorization strategy of a "deny list". You can only call this operation from the management account or a member account that is a delegated administrator.
disable_policy_type	exec	region, RootId, PolicyType		Disables an organizational policy type in a root. A policy of a certain type can be attached to entities in a root only if that type is enabled in the root. After you perform this operation, you no longer can attach policies of the specified type to that root or to any organizational unit (OU) or account in that root. You can undo this by using the EnablePolicyType operation. This is an asynchronous request that Amazon Web Services performs in the background. If you disable a policy type for a root, it still appears enabled for the organization if all features are enabled for the organization. Amazon Web Services recommends that you first use ListRoots to see the status of policy types for a specified root, and then use this operation. You can only call this operation from the management account or a member account that is a delegated administrator. To view the status of available policy types in the organization, use ListRoots.
enable_policy_type	exec	region, RootId, PolicyType		Enables a policy type in a root. After you enable a policy type in a root, you can attach policies of that type to the root, any organizational unit (OU), or account in that root. You can undo this by using the DisablePolicyType operation. This is an asynchronous request that Amazon Web Services performs in the background. Amazon Web Services recommends that you first use ListRoots to see the status of policy types for a specified root, and then use this operation. You can only call this operation from the management account or a member account that is a delegated administrator. You can enable a policy type in a root only if that policy type is available in the organization. To view the status of available policy types in the organization, use ListRoots.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_policy

Retrieves information about a policy. You can only call this operation from the management account or a member account that is a delegated administrator.

SELECT
content,
policy_summary
FROM aws.organizations.policies
WHERE region = '{{ region }}' -- required
;

list_policies

Retrieves the list of all policies in an organization of a specified type. When calling List* operations, always check the NextToken response parameter value, even if you receive an empty result set. These operations can occasionally return an empty set of results even when more results are available. Continue making requests until NextToken returns null. A null NextToken value indicates that you have retrieved all available results. You can only call this operation from the management account or a member account that is a delegated administrator.

SELECT
arn,
aws_managed,
description,
id,
name,
type
FROM aws.organizations.policies
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_policy

Creates a policy of a specified type that you can attach to a root, an organizational unit (OU), or an individual Amazon Web Services account. For more information about policies and their use, see Managing Organizations policies. If the request includes tags, then the requester must have the organizations:TagResource permission. You can only call this operation from the management account or a member account that is a delegated administrator.

INSERT INTO aws.organizations.policies (
Content,
Description,
Name,
Type,
Tags,
region
)
SELECT 
'{{ Content }}' /* required */,
'{{ Description }}',
'{{ Name }}',
'{{ Type }}',
'{{ Tags }}',
'{{ region }}'
RETURNING
policy
;

Manifest

# Description fields are for documentation purposes
- name: policies
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the policies resource.
  - name: Content
    value: "{{ Content }}"
    description: |
      The policy text content to add to the new policy. The text that you supply must adhere to the rules of the policy type you specify in the Type parameter. The maximum size of a policy document depends on the policy's type. For more information, see Maximum and minimum values in the Organizations User Guide.
  - name: Description
    value: "{{ Description }}"
    description: |
      An optional description to assign to the policy.
  - name: Name
    value: "{{ Name }}"
    description: |
      The friendly name to assign to the policy. The regex pattern that is used to validate this parameter is a string of any of the characters in the ASCII character range.
  - name: Type
    value: "{{ Type }}"
    description: |
      The type of policy to create. You can specify one of the following values: SERVICE_CONTROL_POLICY RESOURCE_CONTROL_POLICY DECLARATIVE_POLICY_EC2 BACKUP_POLICY TAG_POLICY CHATBOT_POLICY AISERVICES_OPT_OUT_POLICY SECURITYHUB_POLICY UPGRADE_ROLLOUT_POLICY INSPECTOR_POLICY BEDROCK_POLICY S3_POLICY NETWORK_SECURITY_DIRECTOR_POLICY
    valid_values: ['SERVICE_CONTROL_POLICY', 'RESOURCE_CONTROL_POLICY', 'TAG_POLICY', 'BACKUP_POLICY', 'AISERVICES_OPT_OUT_POLICY', 'CHATBOT_POLICY', 'DECLARATIVE_POLICY_EC2', 'SECURITYHUB_POLICY', 'INSPECTOR_POLICY', 'UPGRADE_ROLLOUT_POLICY', 'BEDROCK_POLICY', 'S3_POLICY', 'NETWORK_SECURITY_DIRECTOR_POLICY']
  - name: Tags
    description: |
      A list of tags that you want to attach to the newly created policy. For each tag in the list, you must specify both a tag key and a value. You can set the value to an empty string, but you can't set it to null. For more information about tagging, see Tagging Organizations resources in the Organizations User Guide. If any one of the tags is not valid or if you exceed the allowed number of tags for a policy, then the entire request fails and the policy is not created.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"

UPDATE examples

attach_policy

Attaches a policy to a root, an organizational unit (OU), or an individual account. How the policy affects accounts depends on the type of policy. Refer to the Organizations User Guide for information about each policy type: SERVICE_CONTROL_POLICY RESOURCE_CONTROL_POLICY DECLARATIVE_POLICY_EC2 BACKUP_POLICY TAG_POLICY CHATBOT_POLICY AISERVICES_OPT_OUT_POLICY SECURITYHUB_POLICY UPGRADE_ROLLOUT_POLICY INSPECTOR_POLICY BEDROCK_POLICY S3_POLICY NETWORK_SECURITY_DIRECTOR_POLICY You can only call this operation from the management account or a member account that is a delegated administrator.

UPDATE aws.organizations.policies
SET 
PolicyId = '{{ PolicyId }}',
TargetId = '{{ TargetId }}'
WHERE 
region = '{{ region }}' --required
AND PolicyId = '{{ PolicyId }}' --required
AND TargetId = '{{ TargetId }}' --required;

update_policy

Updates an existing policy with a new name, description, or content. If you don't supply any parameter, that value remains unchanged. You can't change a policy's type. You can only call this operation from the management account or a member account that is a delegated administrator.

UPDATE aws.organizations.policies
SET 
PolicyId = '{{ PolicyId }}',
Name = '{{ Name }}',
Description = '{{ Description }}',
Content = '{{ Content }}'
WHERE 
region = '{{ region }}' --required
AND PolicyId = '{{ PolicyId }}' --required
RETURNING
policy;

DELETE examples

delete_policy

Deletes the specified policy from your organization. Before you perform this operation, you must first detach the policy from all organizational units (OUs), roots, and accounts. You can only call this operation from the management account or a member account that is a delegated administrator.

DELETE FROM aws.organizations.policies
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

detach_policy

Detaches a policy from a target root, organizational unit (OU), or account. If the policy being detached is a service control policy (SCP), the changes to permissions for Identity and Access Management (IAM) users and roles in affected accounts are immediate. Every root, OU, and account must have at least one SCP attached. If you want to replace the default FullAWSAccess policy with an SCP that limits the permissions that can be delegated, you must attach the replacement SCP before you can remove the default SCP. This is the authorization strategy of an "allow list". If you instead attach a second SCP and leave the FullAWSAccess SCP still attached, and specify "Effect": "Deny" in the second SCP to override the "Effect": "Allow" in the FullAWSAccess policy (or any other attached SCP), you're using the authorization strategy of a "deny list". You can only call this operation from the management account or a member account that is a delegated administrator.

EXEC aws.organizations.policies.detach_policy 
@region='{{ region }}' --required 
@@json=
'{
"PolicyId": "{{ PolicyId }}", 
"TargetId": "{{ TargetId }}"
}'
;

disable_policy_type

Disables an organizational policy type in a root. A policy of a certain type can be attached to entities in a root only if that type is enabled in the root. After you perform this operation, you no longer can attach policies of the specified type to that root or to any organizational unit (OU) or account in that root. You can undo this by using the EnablePolicyType operation. This is an asynchronous request that Amazon Web Services performs in the background. If you disable a policy type for a root, it still appears enabled for the organization if all features are enabled for the organization. Amazon Web Services recommends that you first use ListRoots to see the status of policy types for a specified root, and then use this operation. You can only call this operation from the management account or a member account that is a delegated administrator. To view the status of available policy types in the organization, use ListRoots.

EXEC aws.organizations.policies.disable_policy_type 
@region='{{ region }}' --required 
@@json=
'{
"RootId": "{{ RootId }}", 
"PolicyType": "{{ PolicyType }}"
}'
;

enable_policy_type

Enables a policy type in a root. After you enable a policy type in a root, you can attach policies of that type to the root, any organizational unit (OU), or account in that root. You can undo this by using the DisablePolicyType operation. This is an asynchronous request that Amazon Web Services performs in the background. Amazon Web Services recommends that you first use ListRoots to see the status of policy types for a specified root, and then use this operation. You can only call this operation from the management account or a member account that is a delegated administrator. You can enable a policy type in a root only if that policy type is available in the organization. To view the status of available policy types in the organization, use ListRoots.

EXEC aws.organizations.policies.enable_policy_type 
@region='{{ region }}' --required 
@@json=
'{
"RootId": "{{ RootId }}", 
"PolicyType": "{{ PolicyType }}"
}'
;