Designating the Detective administrator account for an organization

In the organization behavior graph, the Detective administrator account manages the behavior graph membership for all organization accounts.

How the Detective administrator account is managed

The organization management account designates the Detective administrator account for the organization in each AWS Region.

Setting the Detective administrator account as the delegated administrator account

The Detective administrator account also becomes the delegated administrator account for Detective in AWS Organizations. The exception is if the organization management account designates itself as the Detective administrator account. The organization management account cannot be a delegated administrator in Organizations.

After the delegated administrator account is set in Organizations, the organization management account can only choose either the delegated administrator account or their own account as the Detective administrator account. We recommend that you choose the delegated administrator account in all Regions.

Creating and managing the organization behavior graph

When the organization management account chooses a Detective administrator account, Detective creates a new behavior graph for that account. That behavior graph is the organization behavior graph.

If the Detective administrator account is an administrator account for an existing behavior graph, then that behavior graph becomes the organization behavior graph.

The Detective administrator account chooses organization accounts to enable as member accounts in the organization behavior graph.

The Detective administrator account can also send invitations to accounts that do not belong to the organization. For more information, see Managing organization accounts as member accounts and Managing invited member accounts.

Removing the Detective administrator account

The organization management account can remove the current Detective administrator account in a Region. When you remove the Detective administrator account, Detective only removes it from the current Region. It does not change the delegated administrator account in Organizations.

When the organization management account removes the Detective administrator account in a Region, Detective deletes the organization behavior graph. Detective is disabled for the removed Detective administrator account.

To remove the current delegated administrator account for Detective, you use the Organizations API. When you remove the delegated administrator account for Detective in Organizations, Detective deletes all of the organization behavior graphs where the delegated administrator account is the Detective administrator account. Organization behavior graphs that have the organization management account as the Detective administrator account are not affected.

Required permissions to configure the Detective administrator account

To ensure that the organization management account is able to configure the Detective administrator account, you can attach the AmazonDetectiveOrganizationsAccess managed policy to your AWS Identity and Access Management (IAM) entities.

Designating a Detective administrator account (console)

The organization management account can use the Detective console to designate the Detective administrator account.

You do not need to enable Detective in order to manage the Detective administrator account. You can manage the Detective administrator account from the Enable Detective page.

To designate a Detective administrator account (Enable Detective page)

1. Open the Amazon Detective console at https://console.aws.amazon.com/detective/.

2. Choose Get started.

3. In the Required permissions for administrator accounts panel, grant necessary the permissions to the account you choose so that they can operate as a Detective administrator with full access to all actions in Detective. To operate as an administrator, We recommend attaching the AmazonDetectiveFullAccess policy to the principal.

4. Choose Attach policy from IAM to view the recommended policy directly in the IAM console.

5. Depending on whether you have permissions in the IAM console, proceed as follows:

   • If you have permissions to operate in the IAM console, attach the recommended policy to the principal you use for Detective.

   • If you don't have permissions to operate in the IAM console, copy the Amazon Resource Name (ARN) of the policy and provide it to your IAM administrator. They can then attach the policy on your behalf.

6. Under Delegated administrator, choose the Detective administrator account.

   The available options depend on whether you have a delegated administrator account for Detective in Organizations.

   • If you do not have a delegated administrator account for Detective in Organizations, then enter the account identifier of the account to designate it as the Detective administrator account.

     You might have an existing administrator account and behavior graph from the manual invitation process. If so, we recommend that you designate that account as the Detective administrator account.

     If you have a delegated administrator account in Organizations for Amazon GuardDuty, AWS Security Hub, or Amazon Macie, then Detective prompts you to select one of those accounts. You can also enter a different account.

   • If you do have a delegated administrator account for Detective in Organizations, then you are prompted to choose either that account or your account. We recommend that you choose the delegated administrator account in all Regions.

7. Choose Delegate.

If you have Detective enabled, or are a member account in an existing behavior graph, then you can designate the Detective administrator account from the General page.

To designate a Detective administrator account (General page)

1. Open the Amazon Detective console at https://console.aws.amazon.com/detective/.

2. In the Detective navigation pane, under Settings, choose General.

3. In the Managed policies panel, you can learn more about all the managed policies Detective supports. You can grant necessary permissions to an account depending on the actions you want users to perform in Detective. To operate as an administrator, We recommend attaching the AmazonDetectiveFullAccess policy to the principal.

4. Depending on whether you have permissions in the IAM console, proceed as follows:

   • If you have permissions to operate in the IAM console, attach the recommended policy to the principal you use for Detective.

   • If you don't have permissions to operate in the IAM console, copy the Amazon Resource Name (ARN) of the policy and provide it to your IAM administrator. They can then attach the policy on your behalf.

   The available options depend on whether you have a delegated administrator account for Detective in Organizations.

   • If you do not have a delegated administrator account for Detective in Organizations, then enter the account identifier of the account to designate it as the Detective administrator account.

     You might have an existing administrator account and behavior graph from the manual invitation process. If so, then we recommend that you designate that account as the Detective administrator account.

     If you have a delegated administrator account in Organizations for Amazon GuardDuty, AWS Security Hub, or Amazon Macie, then Detective prompts you to select one of those accounts. You can also enter a different account.

   • If you do have a delegated administrator account for Detective in Organizations, then you are prompted to choose either that account or your account. We recommend that you choose the delegated administrator account in all Regions.

5. Choose Delegate.

Designating a Detective administrator account (Detective API, AWS CLI)

To designate the Detective administrator account, you can use an API call or the AWS Command Line Interface. You must use the organization management account credentials.

If you already have a delegated administrator account for Detective in organizations, then you must choose either that account or your account we recommend that you choose the delegated administrator account.

To designate the Detective administrator account (Detective API, AWS CLI)

• Detective API: Use the EnableOrganizationAdminAccount operation. You must provide the AWS account identifier of the Detective administrator account. To obtain the account identifier, use the ListOrganizationAdminAccounts operation.

• AWS CLI: At the command line, run the enable-organization-admin-account command.

  aws detective enable-organization-admin-account --account-id <admin account ID>

  Example

  aws detective enable-organization-admin-account --account-id 777788889999

Removing a Detective administrator account (console)

From the Detective console, you can remove the Detective administrator account.

When you remove the Detective administrator account, Detective is disabled for the account, and the organization behavior graph is deleted. The Detective administrator account is only removed in the current Region.

Important

Removing a Detective administrator account does not affect the delegated administrator account in Organizations.

To remove the Detective administrator account (Enable Detective page)

1. Open the Amazon Detective console at https://console.aws.amazon.com/detective/.

2. Choose Get started.

3. Under Delegated Administrator, choose Disable Amazon Detective.

4. On the confirmation dialog box, enter disable, then choose Disable Amazon Detective.

To remove a Detective administrator account (General page)

1. Open the Amazon Detective console at https://console.aws.amazon.com/detective/.

2. In the Detective navigation pane, under Settings, choose General.

3. Under Delegated Administrator, choose Disable Amazon Detective.

4. On the confirmation dialog box, enter disable, then choose Disable Amazon Detective.

Removing the Detective administrator account (Detective API, AWS CLI)

To remove the Detective administrator account, you can use an API call or the AWS CLI. You must use the organization management account credentials.

When you remove the Detective administrator account, Detective is disabled for the account, and the organization behavior graph is deleted.

Important

Removing a Detective administrator account does not affect the delegated administrator account in Organizations.

To remove the Detective administrator account (Detective API, AWS CLI)

• Detective API: Use the DisableOrganizationAdminAccount operation.

  When you use the Detective API to remove the Detective administrator account, it is only removed in the Region where the API call or command was issued.

• AWS CLI: At the command line, run the disable-organization-admin-account command.

  aws detective disable-organization-admin-account

Removing the delegated administrator account (Organizations API, AWS CLI)

Removing the Detective administrator account does not automatically remove the delegated administrator account in Organizations. To remove the delegated administrator account for Detective, you can use the Organizations API.

When you remove the delegated administrator account, this deletes all organization behavior graphs where the delegated administrator account is the Detective administrator account. It also disables Detective for the account in those Regions.

To remove the delegated administrator account (Organizations API, AWS CLI)

• Organizations API: Use the DeregisterDelegatedAdministrator operation. You must provide the account identifier of the Detective administrator account, and the service principal for Detective, which is detective.amazonaws.com.

• AWS CLI: At the command line, run the deregister-delegated-administrator command.

  aws organizations deregister-delegated-administrator --account-id <Detective administrator account ID> --service-principal <Detective service principal>

  Example

  aws organizations deregister-delegated-administrator --account-id 777788889999 --service-principal detective.amazonaws.com