# Integrating Security Hub CSPM with AWS Organizations To integrate AWS Security Hub CSPM and AWS Organizations, you create an organization in Organizations and use the organization management account to designate a delegated Security Hub CSPM administrator account. This enables Security Hub CSPM as a trusted service in Organizations. It also enables Security Hub CSPM in the current AWS Region for the delegated administrator account, and it allows the delegated administrator to enable Security Hub CSPM for member accounts, view data in member accounts, and perform other [allowed actions](securityhub-accounts-allowed-actions.md) on member accounts. If you use [central configuration](central-configuration-intro.md), then the delegated administrator can also create Security Hub CSPM configuration policies that specify how the Security Hub CSPM service, standards, and controls should be configured in organization accounts. ## Creating an organization An organization is an entity that you create to consolidate your AWS accounts so that you can administer them as a single unit. You can create an organization by using either the AWS Organizations console or by using a command from the AWS CLI or one of the SDK APIs. For detailed instructions, see [Create an organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_create.html) in the *AWS Organizations User Guide*. You can use AWS Organizations to centrally view and manage all of the accounts within your organization. An organization has one management account along with zero or more member accounts. You can organize the accounts in a hierarchical, tree-like structure with a root at the top and organizational units (OUs) nested under the root. Each account can be directly under the root, or placed in one of the OUs in the hierarchy. An OU is a container for specific accounts. For example, you can create a finance OU that includes all accounts related to financial operations. ## Recommendations for choosing the delegated Security Hub CSPM administrator If you have an administrator account in place from the manual invitation process and are transitioning to account management with AWS Organizations, we recommend designating that account as the delegated Security Hub CSPM administrator. Although the Security Hub CSPM APIs and console allow the organization management account to be the delegated Security Hub CSPM administrator, we recommend choosing two different accounts. This is because users who have access to the organization management account to manage billing are likely to be different from users who need access to Security Hub CSPM for security management. We recommend using the same delegated administrator across Regions. If you opt in to central configuration, Security Hub CSPM automatically designates the same delegated administrator in your home Region and any linked Regions. ## Verify permissions to configure the delegated administrator To designate and remove a delegated Security Hub CSPM administrator account, the organization management account must have permissions for the `EnableOrganizationAdminAccount` and `DisableOrganizationAdminAccount` actions in Security Hub CSPM. The Organizations management account must also have administrative permissions for Organizations. To grant all of the required permissions, attach the following Security Hub CSPM managed policies to the IAM principal for the organization management account: + [https://docs.aws.amazon.com/securityhub/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-awssecurityhubfullaccess](https://docs.aws.amazon.com/securityhub/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-awssecurityhubfullaccess) + [https://docs.aws.amazon.com/securityhub/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-awssecurityhuborganizationsaccess](https://docs.aws.amazon.com/securityhub/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-awssecurityhuborganizationsaccess) ## Designating the delegated administrator To designate the delegated Security Hub CSPM administrator account, you can use the Security Hub CSPM console, Security Hub CSPM API, or AWS CLI. Security Hub CSPM sets the delegated administrator in the current AWS Region only, and you must repeat the action in other Regions. If you start using central configuration, then Security Hub CSPM automatically sets the same delegated administrator in the home Region and linked Regions. The organization management account doesn't have to enable Security Hub CSPM in order to designate the delegated Security Hub CSPM administrator account. We recommend that the organization management account is not the delegated Security Hub CSPM administrator account. However, if you do choose the organization management account as the Security Hub CSPM delegated administrator, the management account must have Security Hub CSPM enabled. If the management account does not have Security Hub CSPM enabled, you must enable Security Hub CSPM for it manually. Security Hub CSPM can't be enabled automatically for the organization management account. You must designate the delegated Security Hub CSPM administrator using one of the following methods. Designating the delegated Security Hub CSPM administrator with Organizations APIs doesn't reflect in Security Hub CSPM. Choose your preferred method, and follow the steps to designate the delegated Security Hub CSPM administrator account. ------ #### [ Security Hub CSPM console ] **To designate the delegated administrator while onboarding** 1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 1. Choose **Go to Security Hub CSPM**. You're prompted to sign in to the organization management account. 1. On the **Designate delegated administrator** page, in the **Delegated administrator account** section, specify the delegated administrator account. We recommend choosing the same delegated administrator that you have set for other AWS security and compliance services. 1. Choose **Set delegated administrator**. You're prompted to sign in to the delegated administrator account (if you're not already) to continue onboarding with central configuration. If you don't want to start central configuration, choose **Cancel**. Your delegated administrator is set, but you aren't yet using central configuration. **To designate the delegated administrator from the **Settings** page** 1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 1. In the Security Hub CSPM navigation pane, choose **Settings**. Then choose **General**. 1. If a Security Hub CSPM administrator account is currently assigned, then before you can designate a new account, you must remove the current account. Under **Delegated Administrator**, to remove the current account, choose **Remove**. 1. Enter the account ID of the account you want to designate as the **Security Hub CSPM** administrator account. You must designate the same Security Hub CSPM administrator account in all Regions. If you designate an account that is different from the account designated in other Regions, the console returns an error. 1. Choose **Delegate**. ------ #### [ Security Hub CSPM API, AWS CLI ] From the organization management account, use the [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_EnableOrganizationAdminAccount.html](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_EnableOrganizationAdminAccount.html) operation of the Security Hub CSPM API. If you're using the AWS CLI, run the [https://docs.aws.amazon.com/cli/latest/reference/securityhub/enable-organization-admin-account.html](https://docs.aws.amazon.com/cli/latest/reference/securityhub/enable-organization-admin-account.html) command. Provide the AWS account ID of the delegated Security Hub CSPM administrator. The following example designates the delegated Security Hub CSPM administrator. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability. ``` $ aws securityhub enable-organization-admin-account --admin-account-id 123456789012 ``` ------ # Removing or changing the delegated administrator Only the organization management account can remove the delegated Security Hub CSPM administrator account. To change the delegated Security Hub CSPM administrator, you must first remove the current delegated administrator account and then designate a new one. **Warning** When you use [central configuration](central-configuration-intro.md), you can't use the Security Hub CSPM console or Security Hub CSPM APIs to change or remove the delegated administrator account. If the organization management account uses the AWS Organizations console or AWS Organizations APIs to change or remove the delegated Security Hub CSPM administrator, Security Hub CSPM automatically stops central configuration, and deletes your configuration policies and policy associations. Member accounts retain the configurations they had before the delegated administrator was changed or removed. If you use the Security Hub CSPM console to remove the delegated administrator in one Region, it is automatically removed in all Regions. The Security Hub CSPM API only removes the delegated Security Hub CSPM administrator account from the Region where the API call or command is issued. You must repeat the action in other Regions. If you use the Organizations API to remove the delegated Security Hub CSPM administrator account, it is automatically removed in all Regions. ## Removing the delegated administrator (Organizations API, AWS CLI) You can use Organizations to remove the delegated Security Hub CSPM administrator in all Regions. If you use central configuration to manage accounts, removing the delegated administrator account results in the deletion of your configuration policies and policy associations. Member accounts retain the configurations that they had before the delegated administrator was changed or removed. However, these accounts can't be managed by the removed delegated administrator account anymore. They become self-managed accounts that must be configured separately in each Region. Choose your preferred method, and follow the instructions to remove the delegated Security Hub CSPM administrator account with AWS Organizations. ------ #### [ Organizations API, AWS CLI ] **To remove the delegated Security Hub CSPM administrator** From the organization management account, use the [https://docs.aws.amazon.com/organizations/latest/APIReference/API_DeregisterDelegatedAdministrator.html](https://docs.aws.amazon.com/organizations/latest/APIReference/API_DeregisterDelegatedAdministrator.html) operation of the Organizations API. If you're using the AWS CLI, run the [deregister-delegated-administrator](https://docs.aws.amazon.com/cli/latest/reference/organizations/deregister-delegated-administrator.html) command. Provide the account ID of the delegated administrator, and the service principal for Security Hub CSPM, which is `securityhub.amazonaws.com`. The following example removes the delegated Security Hub CSPM administrator. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability. ``` $ aws organizations deregister-delegated-administrator --account-id 123456789012 --service-principal securityhub.amazonaws.com ``` ------ ## Removing the delegated administrator (Security Hub CSPM console) You can use the Security Hub CSPM console to remove the delegated Security Hub CSPM administrator in all Regions. When the delegated Security Hub CSPM administrator account is removed, the member accounts are disassociated from the removed delegated Security Hub CSPM administrator account. Security Hub CSPM is still enabled in the member accounts. They become standalone accounts until a new Security Hub CSPM administrator enables them as member accounts. If the organization management account isn't an enabled account in Security Hub CSPM, then use the option on the **Welcome to Security Hub CSPM** page. **To remove the delegated Security Hub CSPM administrator account from the **Welcome to Security Hub CSPM** page** 1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 1. Choose **Go to Security Hub**. 1. Under **Delegated Administrator**, choose **Remove**. If the organization management account is an enabled account in **Security Hub**, then use the option on the **General** tab of the **Settings** page. **To remove the delegated Security Hub CSPM administrator account from the **Settings** page** 1. Open the AWS Security Hub CSPM console at [https://console.aws.amazon.com/securityhub/](https://console.aws.amazon.com/securityhub/). 1. In the Security Hub CSPM navigation pane, choose **Settings**. Then choose **General**. 1. Under **Delegated Administrator**, choose **Remove**. ## Removing the delegated administrator (Security Hub CSPM API, AWS CLI) You can use the Security Hub CSPM API or Security Hub CSPM operations for the AWS CLI to remove the delegated Security Hub CSPM administrator. When you remove the delegated administrator with one of these methods, it is only removed in the Region where the API call or command was issued. Security Hub CSPM doesn't update other Regions, and it doesn't remove the delegated administrator account in AWS Organizations. Choose your preferred method, and follow these steps to remove the delegated Security Hub CSPM administrator account with Security Hub CSPM. ------ #### [ Security Hub CSPM API, AWS CLI ] **To remove the delegated Security Hub CSPM administrator** From the organization management account, use the [https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_DisableOrganizationAdminAccount.html](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_DisableOrganizationAdminAccount.html) operation of the Security Hub CSPM API. If you're using the AWS CLI, run the [https://docs.aws.amazon.com/cli/latest/reference/securityhub/disable-organization-admin-account.html](https://docs.aws.amazon.com/cli/latest/reference/securityhub/disable-organization-admin-account.html) command. Provide the account ID of the delegated Security Hub CSPM administrator. The following example removes the delegated Security Hub CSPM administrator. This example is formatted for Linux, macOS, or Unix, and it uses the backslash (\$1) line-continuation character to improve readability. ``` $ aws securityhub disable-organization-admin-account --admin-account-id 123456789012 ``` ------ # Disabling Security Hub CSPM integration with AWS Organizations After an AWS Organizations organization is integrated with AWS Security Hub CSPM, the Organizations management account can subsequently disable the integration. As a user of the Organizations management account, you can do this by disabling trusted access for Security Hub CSPM in AWS Organizations. When you disable trusted access for Security Hub CSPM, the following occurs: + Security Hub CSPM loses its status as a trusted service in AWS Organizations. + The Security Hub CSPM delegated administrator account loses access to Security Hub CSPM settings, data, and resources for all Security Hub CSPM member accounts in all AWS Regions. + If you were using [central configuration](central-configuration-intro.md), Security Hub CSPM automatically stops using it for your organization. Your configuration policies and policy associations are deleted. Accounts retain the configurations that they had before you disabled trusted access. + All Security Hub CSPM member accounts become standalone accounts and retain their current settings. If Security Hub CSPM was enabled for a member account in one or more Regions, Security Hub CSPM continues to be enabled for the account in those Regions. Enabled standards and controls are also unchanged. You can change these settings separately in each account and Region. However, the account is no longer associated with a delegated administrator in any Region. For additional information about the results of disabling trusted service access, see [Using AWS Organizations with other AWS services](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_integrate_services.html) in the *AWS Organizations User Guide*. To disable trusted access, you can use the AWS Organizations console, Organizations API, or the AWS CLI. Only a user of the Organizations management account can disable trusted service access for Security Hub CSPM. For details about the permissions that you need, see [Permissions required to disable trusted access](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_integrate_services.html#orgs_trusted_access_disable_perms) in the *AWS Organizations User Guide*. Before you disable trusted access, we recommend working with the delegated administrator for your organization to disable Security Hub CSPM in member accounts and to clean up Security Hub CSPM resources in those accounts. Choose your preferred method, and follow the steps to disable trusted access for Security Hub CSPM. ------ #### [ Organizations console ] **To disable trusted access for Security Hub CSPM** 1. Sign in to the AWS Management Console using the credentials of the AWS Organizations management account. 1. Open the Organizations console at [https://console.aws.amazon.com/organizations/](https://console.aws.amazon.com/organizations/). 1. In the navigation pane, choose **Services**. 1. Under **Integrated services**, choose **AWS Security Hub CSPM**. 1. Choose **Disable trusted access**. 1. Confirm that you want to disable trusted access. ------ #### [ Organizations API ] **To disable trusted access for Security Hub CSPM** Invoke the [DisableAWSServiceAccess](https://docs.aws.amazon.com/organizations/latest/APIReference/API_DisableAWSServiceAccess.html) operation of the AWS Organizations API. For the `ServicePrincipal` parameter, specify the Security Hub CSPM service principal (`securityhub.amazonaws.com`). ------ #### [ AWS CLI ] **To disable trusted access for Security Hub CSPM** Run the [disable-aws-service-access](https://docs.aws.amazon.com/cli/latest/reference/organizations/disable-aws-service-access.html) command of the AWS Organizations API. For the `service-principal` parameter, specify the Security Hub CSPM service principal (`securityhub.amazonaws.com`). **Example:** ``` aws organizations disable-aws-service-access --service-principal securityhub.amazonaws.com ``` ------