Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.
Managing GuardDuty accounts with Amazon Organizations
When you use GuardDuty with an Amazon Organizations organization, you can designate any account within the
organization to be the GuardDuty delegated administrator. Only the organization management account can designate
GuardDuty delegated administrators.
An account that is designated as a delegated administrator becomes a GuardDuty administrator account, has GuardDuty
automatically enabled in the designated Region, and is granted permission to enable and
manage GuardDuty for all accounts in the organization within that Region. The other accounts in
the organization can be viewed and added as GuardDuty member accounts associated with the
delegated administrator account.
If you have already set up a GuardDuty administrator with associated member accounts by invitation,
and the member accounts are part of the same organization, their Type
changes from by Invitation to via Organizations
when you set a GuardDuty delegated administrator for your organization. If the new delegated administrator previously added
members by invitation that are not part of the same organization, their
Type is by Invitation. In both cases, these
previously added accounts are member accounts to the organization's GuardDuty delegated administrator.
You can continue to add accounts as members even if they are outside of your organization.
To learn more, see Designating administrator and member accounts
through invitation (console) and Designating GuardDuty administrator and member accounts
through invitation (API).
Important considerations for GuardDuty
delegated administrators
Take note of the following factors that define how the delegated administrator operates in
GuardDuty:
- A delegated administrator can manage a maximum of 5000
members.
-
There is a limit of 5000 member accounts per GuardDuty delegated administrator. However, there
could be more than 5000 accounts in your organization. The number of
All accounts in your organization is displayed on
the Accounts page of the GuardDuty console.
If you exceed 5000 member accounts you will receive a notification through
CloudWatch, Amazon Health Dashboard, and in an email to the delegated administrator account.
- A delegated administrator is Regional.
-
Unlike Amazon Organizations, GuardDuty is a Regional service. This means that GuardDuty
delegated administrators, and their member accounts must be added in each
desired Region for account management through Amazon Organizations to be active in every
Region. In other words, if the organization management account designates a
delegated administrator for GuardDuty in only US East (N. Virginia) that delegated administrator will only manage
member accounts added in that Region. For more information on Regions in
GuardDuty see Regions and endpoints.
- An organization can designate only one GuardDuty
delegated administrator.
-
You can designate only one GuardDuty delegated administrator to your organization. If you have
designated an account as a delegated administrator in one Region, that account must be the
delegated administrator in all other regions. You can designate a new delegated administrator at any point
in time. For more, see De-registering a GuardDuty delegated administrator.
- Not recommended to set your organization's
management account as the delegated administrator.
-
Your organization's management account can be the delegated administrator, but this is not
recommended based on Amazon Security best practices following the principle
of least privilege.
- Changing a delegated administrator does not disable GuardDuty for member
accounts.
-
If you remove the delegated administrator, all associated member accounts are removed as
GuardDuty members, but GuardDuty is not disabled in those accounts.
Permissions required to designate a
delegated administrator
When delegating a GuardDuty delegated administrator you must have permissions to enable GuardDuty as well as
certain Amazon Organizations API actions listed in the following policy statement.
You can add the following statement to the end of an IAM policy to grant these
permissions:
{
"Sid": "PermissionsForGuardDutyAdmin",
"Effect": "Allow",
"Action": [
"guardduty:EnableOrganizationAdminAccount",
"organizations:EnableAWSServiceAccess",
"organizations:RegisterDelegatedAdministrator",
"organizations:ListDelegatedAdministrators",
"organizations:ListAWSServiceAccessForOrganization",
"organizations:DescribeOrganizationalUnit",
"organizations:DescribeAccount",
"organizations:DescribeOrganization"
],
"Resource": "*"
}
Additionally, if you wish to designate your Amazon Organizations management account as the GuardDuty
delegated administrator that entity will need CreateServiceLinkedRole
permissions to
initialize GuardDuty. This can be added to an IAM policy using the following statement,
replacing the account ID with the ID of your organization management account:
{
"Sid": "PermissionsToEnableGuardDuty"
"Effect": "Allow",
"Action": [
"iam:CreateServiceLinkedRole"
],
"Resource": "arn:aws:iam::111122223333
:role/aws-service-role/guardduty.amazonaws.com/AWSServiceRoleForAmazonGuardDuty",
"Condition": {
"StringLike": {
"iam:AWSServiceName": "guardduty.amazonaws.com"
}
}
}
If you're using GuardDuty in a manually-enabled Region, replace the value for the
"Service" with the Regional endpoint for the Region. For example, if you're using
GuardDuty in the Middle East (Bahrain) (me-south-1) Region, replace "Service":
"guardduty.amazonaws.com"
with "Service":
"guardduty.me-south-1.amazonaws.com"
.
Designating a GuardDuty delegated administrator
Choose your access method to designate a delegated administrator for your Amazon organization and add
member accounts.
- Console
-
Step 1 —
Register a GuardDuty delegated administrator for your organization
Open the GuardDuty console at https://console.amazonaws.cn/guardduty/.
To log in, use the management account for your Amazon Organizations
organization.
-
Is GuardDuty already enabled in your account?
-
If GuardDuty is not yet enabled, select Get
Started, and then designate a GuardDuty delegated administrator
on the Welcome to GuardDuty page.
The management account must have the GuardDuty
service-linked role in order for the delegated
administrator to be able to enable and manage GuardDuty in
that account. You can enable GuardDuty in any region of the
management account to create this role
automatically.
-
If GuardDuty is already enabled, you can designate a GuardDuty
delegated administrator on the Settings page.
-
Enter the 12-digit Amazon account ID
of the
account that you want to designate as the GuardDuty delegated administrator for the
organization.
-
Choose Delegate. If GuardDuty is not already
enabled, designating a delegated administrator will enable GuardDuty for that account in
your current Region.
-
If you want to allow the delegated administrator to attach relevant permissions to
member accounts to enable Malware Protection, turn on the
Permissions setting.
-
(Recommended) Repeat the previous steps in each Amazon
Region.
After you designate the delegated administrator, you only need to use the organization
management account to change or remove the delegated administrator account.
When you add an account as a member, GuardDuty is automatically enabled in
that account in the current Region. This behavior differs from the
invitation method, in which GuardDuty must be enabled prior to the account
being added as a member.
You must add your organization members in each Region to enable GuardDuty for
those Regions.
Step 2 - Add existing
organization accounts as members
Open the GuardDuty console at
https://console.amazonaws.cn/guardduty/.
-
In the navigation panel, choose Settings, and
then choose Accounts.
The accounts table displays all of the accounts in the
organization. The Type for these accounts is
via organizations. The status of accounts
that are not member accounts associated with the organization's
GuardDuty delegated administrator is Not a member.
-
Choose the account or accounts that you want to add as members by
checking the box next to the account ID.
You can enable GuardDuty in the current Region for all
organization accounts by choosing enable in
the banner at the top of the page. This action also turns on the
Auto-Enable feature that enables GuardDuty
in any future accounts that you add to your organization.
Alternately, you can use the filter
field to filter by Relationship status: Not a
member, and then choose every account that
doesn't have GuardDuty enabled in the current Region.
-
Choose Actions, then choose Add
member.
-
Confirm that you want to add the selected
accounts as members. The Status for the
accounts will change to Enabled.
-
(Recommended) Repeat these steps in each Amazon Region to ensure
that your delegated administrator can manage findings for member accounts in all
Regions.
Step 3 - Automate the
addition of new organization accounts as members
Open the GuardDuty console at https://console.amazonaws.cn/guardduty/.
Log in using the delegated administrator credentials.
-
In the navigation pane, under Settings,
choose Accounts, and then turn on
Auto-enable.
-
In addition to GuardDuty, if you want to enable optional detection
features for your new accounts, choose Actions,
and then choose Enable S3 Protection,
Enable Kubernetes Audit Logs Monitoring, or
Enable Malware Protection. For more
information about these features, see Configuring S3 protection in multiple-account
environments,
Configuring EKS Protection in multiple-account
environments, or Configuring GuardDuty Malware Protection in
multiple-account environments.
-
(Recommended) Repeat these steps in each Amazon Region to ensure
that GuardDuty is automatically enabled on any new account, in every
Region.
The auto-enable feature enables GuardDuty for all future members of your
organization. This allows your GuardDuty delegated administrator to manage any
new members that are created within or added to the organization. When the
number of member accounts reaches the limit of 5000, the Auto-enable feature
is automatically turned off. If an account is removed and the total number
of members decreases to fewer than 5000, the Auto-enable feature turns back
on.
- API
-
Designate a delegated administrator and add member
accounts (API)
-
Run the enableOrganizationAdminAccount API
operation using the credentials of the Amazon Web Services account of the Organizations
management account.
You can also use the Amazon Command Line to do this by running the
following CLI command. Make sure to specify the account ID of the
account you want to make a GuardDuty delegated administrator.
aws guardduty enable-organization-admin-account --admin-account-id 11111111111
This command sets the delegated administrator for your current Region only. If
GuardDuty is not already enabled for that account in the current Region,
it will be automatically enabled.
To set the delegated administrator for other Regions, you must specify the Region
you want your delegated administrator to manage. For more information, see GuardDuty endpoints and quotas. The following example
demonstrates how to enable a delegated administrator in US West (Oregon).
aws guardduty enable-organization-admin-account --admin-account-id 11111111111
--region us-west-2
-
Run the CreateMembers API operation using
the credentials of the Amazon Web Services account you designated as the delegated administrator
for GuardDuty in the previous step.
You must specify the regional detector ID of the delegated administrator Amazon
account and the account details, including the account IDs and email
addresses, of the accounts that you want to become GuardDuty members.
You can create one or more members with this API operation.
Accounts added as members will have GuardDuty enabled in that
Region, with the exception of the organization
management account, which must first enable GuardDuty before it can
be added as a member account.
You can also do this using Amazon Command Line Tools by running the
following CLI command. Make sure to use your own valid detector ID,
account ID, and email.
You can find your detectorId for your current Region
on the Settings page in the https://console.amazonaws.cn/guardduty/ console,
or by using the ListDetectors API.
aws guardduty create-members --detector-id 12abc34d567e8fa901bc2d34e56789f0
--account-details AccountId=123456789012
,Email=guarddutymember@amazon.com
You can view a list of all organization members using the ListAccounts API operation or by
running the following CLI command.
aws organizations list-accounts
-
Run the updateOrganizationConfiguration API
operation using the credentials of the GuardDuty delegated administrator account to
automatically enable GuardDuty in that Region for new member
accounts.
You must specify the detector ID of the delegated administrator Amazon
account.
You can also do this using Amazon Command Line Tools by running the
following CLI command. Make sure to use your own valid detector ID.
You can find your detectorId for your current Region
on the Settings page in the https://console.amazonaws.cn/guardduty/ console,
or by using the ListDetectors API.
aws guardduty update-organization-configuration --detector-id 12abc34d567e8fa901bc2d34e56789f0
--auto-enable
You can confirm that you have turned on the auto enable GuardDuty
feature in a Region by running the describeOrganizationConfiguration
API operation or by running the following CLI command using the
detector ID of the delegated administrator in the desired Region.
You can find your detectorId for your current Region
on the Settings page in the https://console.amazonaws.cn/guardduty/ console,
or by using the ListDetectors API.
aws guardduty describe-organization-configuration —-detector-id 12abc34d567e8fa901bc2d34e56789f0
-
(Recommended) Repeat these steps in each Region using your unique
detector ID for that Region to enable GuardDuty monitoring coverage for
all members in all Amazon Web Services Regions.
Consolidating GuardDuty administrator accounts under a single
organization delegated administrator
GuardDuty recommends using association through Amazon Organizations to manage member accounts under a
delegated administrator account. You can use the example process outlined below to consolidate administrator
and member associated by invitation in an organization under a single GuardDuty
delegated administrator.
Accounts already being managed by a GuardDuty delegated administrator or delegated administrator accounts with active
members cannot be added to a different GuardDuty delegated administrator account. Each organization can
have only one GuardDuty delegated administrator account per region, and each member account can have
only one delegated administrator.
-
Ensure all accounts you wish to manage GuardDuty for are part of your
organization. For information on adding an account to your organization, see
Inviting an Amazon Web Services account to join your organization.
-
Disassociate all member accounts from pre-existing administrator accounts, except
those under the account you wish to designate as the GuardDuty delegated
administrator for the organization.
-
Designate a GuardDuty delegated administrator for the organization from the
Settings page.
-
Log in to the designated delegated admin account.
-
Proceed to add members from the organization.
Remember that GuardDuty is a regional service. It is recommended that you
designate your delegated administrator account and add all your members in every region to
maximize the effectiveness of GuardDuty.
De-registering a GuardDuty delegated administrator
Only the Organizations management account can de-register a delegated administrator.
Select Console or API and follow the provided steps to de-register your delegated administrator. Once
de-registration is complete you can designate a new delegated administrator.
- Console
-
When you de-register a delegated administrator from the console, if your account is also
the Organizations management account you must repeat this process in each Region your
account was designated as delegated administrator in.
If you are the Organizations management account and have designated a different
account as delegated administrator they will be de-registered in every Region.
Open the GuardDuty console at
https://console.amazonaws.cn/guardduty/.
-
Select Settings.
-
From the Settings page, under Delegated
Administrator choose Remove.
-
Confirm the change by selecting Remove
Administrator.
- API
-
When you de-register a delegated administrator from the API you must do so in every region
before you can designate a new delegated administrator.
-
Run the DisableOrganizationAdminAccount API
operation using the credentials of the Organizations
management account.
aws guardduty disable-organization-admin-account --admin-account-id "123456789012
"
-
Repeat in each Region managed by that delegated administrator.