Delegated Administrators

src/config/delegated-admins.ts declares which member accounts act as delegated administrators for AWS Organizations integrated services. Delegation moves day-to-day service management out of the management account: the security account owns GuardDuty, Security Hub, Inspector, Macie, CloudTrail, and IAM, and the landing zone account owns CloudFormation StackSets. The organization phase (LandingZoneOrganizationStack) reads this file and performs the registrations after each account exists and its trusted access is enabled.

A service can only be delegated once its trusted access is enabled in trusted-access.ts, so keep the two files aligned: every account you list here needs matching trusted access for the same service principal.

AWS exposes delegated administration through two different mechanisms, so the file keeps two lists. Which one a service belongs in is not a preference, it is dictated by the service's own API. Check the AWS Organizations integrated services table before adding a service: if its documentation points you at the generic Organizations API, it goes in the first list; if it tells you to call a service-specific API, it goes in the second. Keep each list to the services the landing zone configures rather than delegating every service that supports it.

genericOrganizationDelegatedAdministrators

Services that register through the generic Organizations RegisterDelegatedAdministrator API. Each entry is a DelegatedAdministratorProps mapping one account key to the service principals it administers.

The starter ships two entries: AWS Config (with its multi-account setup principal) and IAM delegated to the security account, and CloudFormation StackSets delegated to the landing zone account. IAM is delegated so the security account can manage centralized root access across member accounts after the Provision Management StackSet enables it from the management account.

export const genericOrganizationDelegatedAdministrators: DelegatedAdministratorProps[] = [
  {
    accountKey: 'SecurityAccount',
    servicePrincipals: ['config.amazonaws.com', 'config-multiaccountsetup.amazonaws.com', 'iam.amazonaws.com'],
  },
  {
    accountKey: 'LandingZoneAccount',
    servicePrincipals: ['member.org.stacksets.cloudformation.amazonaws.com'],
  },
];

serviceNativeDelegatedAdministrators

Services that register through their own admin API rather than the generic Organizations call. Each entry is a ServiceNativeDelegatedAdministratorProps that pairs the target account with that service's registration strategy: the SDK action names, the request parameter that carries the admin account ID, the Region scope, and the IAM actions the registration needs.

The starter ships one entry each for CloudTrail, GuardDuty, Inspector, Macie, and Security Hub, all delegated to the security account. GuardDuty, Inspector, and Macie use REGIONAL scope because they register per Region; CloudTrail and Security Hub use GLOBAL. Each entry follows the same shape:

export const serviceNativeDelegatedAdministrators: ServiceNativeDelegatedAdministratorProps[] = [
  {
    accountKey: 'SecurityAccount',
    servicePrincipal: '<service>.amazonaws.com',
    sdkService: '<SdkServiceName>',
    registerAction: '<sdkRegisterAction>',
    deregisterAction: '<sdkDeregisterAction>',
    registerParameterName: '<RequestParamOnRegister>',
    deregisterParameterName: '<RequestParamOnDeregister>',
    scope: DelegatedAdministratorRegistrationScope.GLOBAL,
    iamActions: [
      // organizations:* plus the service-specific register/deregister actions
    ],
  },
  // ...one entry per delegated service.
];

Fill in each field from the service's own AWS Organizations integration page. Some services name the account parameter differently on register versus deregister, so check both, as noted under Things to know.

How it's used

LandingZoneOrganizationStack passes both lists into OrganizationConstruct as its delegatedAdministrators prop, wiring in secondaryRegions as the additionalRegions where REGIONAL services register. The construct validates the combined set at synth time and fails the build on any of these:

• Delegating the same service principal to two different accounts
• Listing the same principal in both the generic and the service-native list
• Repeating a service-native principal

Because delegation is owned by the organization phase, it completes before any landing-zone StackSet that relies on a delegated account runs, which is why the Security Hub V2 StackSet and Organization Trail StackSet can assume the security account is already the delegated administrator.

Things to know

• Verify the API before adding a service. Confirm the service supports delegated administrators in the integrated services table, then check its docs to decide which list it belongs in. For a service-native entry, verify the SDK action names, parameter names, and IAM actions against that service's Organizations integration page.
• accountKey must exist in your organization structure. The key is resolved to a real account ID at deploy time, so a typo or a renamed account key fails the build rather than silently skipping registration.
• Removing an entry deregisters the administrator on the next deploy. Deregistering a security service's delegated admin has service-level side effects (for example, it can disrupt org-wide GuardDuty or Security Hub), so treat removals with the same care as the Security Hub V2 StackSet teardown.