AWS Cloud Operations & Migrations Blog
AWS Organizations, moving an organization member account to another organization: Part 1
AWS customers use AWS Organizations as the basis of a multi-account AWS environment as defined by the Organizing Your AWS Environment Using Multiple Accounts AWS Whitepaper. Organizations is an AWS service that enables you to centrally manage and govern multiple accounts. Often there is a scenario when you must move an AWS account from one organization to a different, new, or an existing organization. For example, in the case of mergers and acquisitions, companies must consolidate one or more AWS accounts from multiple organizations into one organization.
This three-part post series steps you through the different features of AWS Organizations, providing you guidance and consideration when you are using AWS Organizations and move an AWS account from one organization to another organization. Moving an account between organizations requires you to remove the account from an organization, making the account standalone, and then you accepting an invite to join another organization. During and after the account transition you will want to ensure any workloads and services continue to operate.
In part one (this post), we identify different features of Organizations requiring guidance and consideration when you move an account from one organization in Organizations to another. We focus on Organizations Polices, AWS Resource Access Manager (AWS RAM) shares, and AWS global condition context keys. In part two of the series, we identify behavior and actions when you want to move an account registered as an Organizations delegated administrator for one or more compatible AWS services. In part three, we identify behavior and actions when you move an account with one of more AWS services enabled for Organizations trusted access in your organization.
Before moving an AWS account between organizations part of the Organizations service
- Review the content regarding what you must know before removing a member account from your organization in the AWS Organizations User Guide section Before removing an account from an organization.
- Consider the Organizations feature set enabled for the account current and target organization using guidance in this post.
- Review the guidance in this post for Organizations Policies, authorization, or management policies applicable to the account.
- Review the guidance in this post for AWS Resource Access Manager (AWS RAM) resource shares, owned or shared with the account.
- Review the guidance in this post for Amazon CloudWatch Events configuration for events received between accounts.
- Review the guidance in this post for AWS global condition context keys applicable to the account.
- Review the guidance in this post for the AWS Organizations quotas for the target organization.
- Review the guidance in this post for the organization management account.
- Review the guidance in part two of this post series about AWS services that support Organizations Delegated Administrator.
- Review the guidance in part three of this post series about AWS services that support Organizations Trusted Access.
- Review the indirect effects that occur to your account in the Organizations User Guide section Effects of removing an account from an organization under Before removing an account from an organization.
- Removing a member account from your organization and Leaving an organization as a member account in the Organizations User Guide.
- Inviting an AWS account to join your organization in the Organizations User Guide.
This post uses AWS Command Line Interface (AWS CLI) examples. To utilize these, you must first install and configure the AWS CLI. For more information, see Installing the AWS CLI.
Organizations feature sets
Before you move an account between organizations, determine the feature set enabled for each organization. Organizations has two available feature sets which level the control inside of your organization. If the organization feature set is ‘consolidated billing,’ then it provides shared billing functionality for your accounts. If the organization feature set is ‘all features,’ then it includes all of the functionality of consolidated billing, plus advanced features that provide more control over your accounts. Knowing the enabled feature set focuses your consideration when moving an account. If you’re moving an account from a ‘consolidating billing’ organization to an ‘all feature’ organization and vice versa, then the level of control you have over the account will change. You can determine the functionality that currently is available to the organization using the AWS CLI describe-organization command.
The following AWS CLI example retrieves information about the organization, including the feature set of the organization.
If the output organization object string “FeatureSet” is set to “ALL”, then all of the features are enabled. And if it is set to “CONSOLIDATED_BILLING”, then only consolidated billing functionality is available.
Organizations policies
Policies in Organizations enable you to apply additional types of management to the AWS accounts in your organization. You can use policies when ‘all features’ are enabled in your organization.
When you remove an account from an organization, principals in the account are no longer affected by any authorization or management policies applied in the organization. To apply the same account restrictions imposed by the source organization policies to an account, then identify these policies, check in the target organization, and apply if required before moving from the current organization.
Authorization policies
Service control policies (SCPs) are categorized as authorization policies, which help you to centrally manage the security of the AWS accounts in your organization. Inheritance for SCPs means permissions can be applied at the organization root, organizational unit (OU), and account level. To identity SCPs applied to an account, you can use the AWS CLI list-policies-for-target command with the SERVICE_CONTROL_POLICY filter, and then list any policies applied at each level.
To include the same restrictions imposed by the SCPs that you have identified for an account, enable service control policies using the policy type SERVICE_CONTROL_POLICY in the target organization. Create the SCP, if it doesn’t exist, then you can view the contents of a policy using the AWS CLI describe-policy command. Attach the SCP to the organization level that you identified for the SCP, either the root, OU, or the account.
Consider that SCPs may already exist in the target organization. You should identify any SCPs that may be applied to the account that you’re moving, and the effect of any permissions applied.
Management policies
Artificial Intelligence (AI) services opt-out policies, Backup policies, and Tag policies are categorized as management policies. These help you centrally configure and manage AWS services and their features in your organization. Policy inheritance behaves differently for management policy types than it does for service control policies. Before you move an account, determine the effective policy, which is the aggregation of any policies that the account inherits, plus any policy that is directly attached to the account.
Determine management policies applied to an account, using the AWS CLI describe-effective-policy command. Run the command for each of the three management policy types.
The following AWS CLI example returns contents of the effective policy for the policy type and account. Replace <policy-type> with either AISERVICES_OPT_OUT_POLICY, BACKUP_POLICY or TAG_POLICY and <account-id> with your own information.
If the command response “PolicyContent” isn’t empty for any of the policy types, then determine where one or more policies are applied in the organization using the AWS CLI list-policies-for-target command.
When you remove a member account from the organization, existing AI services opt-out, backup, and tagging policies are detached from the account.
To include any of the management policies that you have identified for an account, first enable the policy type in the target organization. You can view the contents of a policy you found in the source organization using the AWS CLI describe-policy command. You can create the policy in the target organization using the AWS CLI create-policy command, specifying the type of policy to create. Attach the policy that you created to the organization level you identified for the policy using the AWS CLI attach-policy command, specifying the management policy type.
Determine authorization or management policies applied to an account
The following example uses AWS CLI commands to determine the authorization or management policies applied to an account, checking the organization root, the account OU parent, and the account for the given policy type.
- The following AWS CLI example retrieves a list of the policies for the specified policy type directly attached to the specified account. Replace <
policy-type> with either AISERVICES_OPT_OUT_POLICY, BACKUP_POLICY, SERVICE_CONTROL_POLICY, or TAG_POLICY, and <account-id> with your own information. - The following AWS CLI example retrieves the parent OUs for an account. Replace <
account-id> with your own information. - The following AWS CLI example retrieves a list of the policies for the specified policy type directly attached to the OU. Replace <
policy-type> with either AISERVICES_OPT_OUT_POLICY, BACKUP_POLICY, SERVICE_CONTROL_POLICY, or TAG_POLICY, and <organization-id> with each “Id” value of type “ORGANIZATIONAL_UNIT” found in the previous step, repeating the command to iterate through the list of OU IDs - The AWS CLI example retrieves a list of roots defined for the organization.
- The following AWS CLI example retrieves a list of the policies for the specified policy type directly attached to the organization root. Replace <
policy-type> with either AISERVICES_OPT_OUT_POLICY, BACKUP_POLICY, SERVICE_CONTROL_POLICY, or TAG_POLICY, and <root-id> with the “Id” value found in the previous step.
AWS RAM resource shares
If you’ve enabled AWS Resource Access Manager and AWS Organizations and shared specified AWS resources, then your account may be an owner, consumer, or both for shared resources. The service principal for AWS RAM is ram.amazonaws.com.
Before moving an account to the target organization, check if there are any AWS RAM resource shares owned by account, or any resources shared with the account. If the account shares resources, then this an owner account. If resources are shared with the account, then this is a consumer – an account can be both owner and consumer.
The following AWS CLI example retrieves details about the resource shares that you own and share with others.
If the AWS CLI get-resource-shares command response includes any resource shares, then you can use the AWS CLI get-resource-share-associations command to retrieve a list of principal associations for resource share. A principal can be one or more of the following: an account ID, an organization ID, an organizational unit ID, or the Amazon Resource Name (ARN) of an individual AWS Identity and Access Management (IAM) user or role.
The following AWS CLI example lists principal associations for one or more resource shares owned by the account
If any resource shares listed have associated principals, then the account is a resource owner and one or more accounts can be consumers of the shared resource. If the principal listed is an organization or OU, then you may have one or more consumer accounts. To continue to share the resource with the consumer account in the target organization, either move the owner account or the shared resource to the same organization.
If your account isn’t a resource owner, then it may be a resource consumer account. You can check if the account has any resources that are shared with the account using the AWS CLI get-resource-shares command. The command output includes the account ID (owningAccountId) of the resource share owner.
The following AWS CLI example retrieves details about the resource shares owned by others and shared with you:
Once you’ve identified the owner and consumer accounts inside of the organization and the types of resource shares, then you can plan your strategy for the transition to the target organization.
If both the owner account and the consumer account are moving to the target organization, first move the consumer account, and then move the owner account. If the owner account isn’t moving to the target organization, and your organization wasn’t created with all of the features functionality, then your resource shares were created with ‘Allow sharing with external principals’. You can move the consumer account to the target organization without modification of the resource share.
If your organization was created with all of the features functionality and you configured the resource share principal as ‘Allow sharing with principals in your organization only’, then modify the resource share to ‘Allow sharing with external principals’ and include one or more account IDs to share the resource. If you’ve shared AWS resources that don’t support ‘Allow sharing with external principals’, then either move the owner account or the resource to the target organization.
Resource shares that don’t allow sharing with externals principles include: AWS Outposts, Amazon Simple Storage Service (Amazon S3) on Outposts, Amazon Transit Gateway, and Amazon Virtual Private Cloud (Amazon VPC) subnet. If you try to create a resource share with the option ‘Allow sharing with external principals’, then you’ll receive the message, ‘Cannot create ResourceShare: OperationNotPermittedException: Principal <account -id> is not in your AWS organization. You do not have permission to add external AWS accounts to a resource share.’.
When your consumer account leaves the source organization and the resource share is configured to ‘Allow sharing with principals in your organization only’, then the consumer account ID principal is removed from the owner account resource share automatically. Once you’ve moved the consumer account and the resource share owner account, or resource to the target organization, re-establish any resource shares that you discovered in the source organization.
When a consumer account is removed from an AWS RAM resource share, the account no longer has permissions for the resource share. However, AWS services already launched using the shared resource persist. For example, when removing an account from a ‘Subnet’ resource share, you can continue to restart and stop already launched Amazon Elastic Compute Cloud (Amazon EC2) instances.
CloudWatch Events
If you’ve configured CloudWatch Events for sending and receiving events between your account and other accounts, then adjust the permissions to reflect any organization change for both the sender and receiver accounts.
AWS global condition context keys
AWS Identity and Access Management (IAM) allows you to control access to your AWS resources using keys to compare the identifier of the organization in AWS Organizations. You can check which organization the principal or resource belongs, or the AWS Organizations path for the principal or accessed resource
For some services, you grant permissions using resource-based policies to specify the accounts and principals that can access the resource and which actions they can perform on it.
When a principal makes a request to AWS, AWS gathers the request information into a request context. You can use the condition element of a JSON policy to compare keys in the request context with key values that you specify in your policy. You can use the Organizations related condition keys, aws:PrincipalOrgID, aws:PrincipalOrgPaths, aws:ResourceOrgID, and aws:ResourceOrgPaths in these policies to validate with the requesting principal context. A condition is an optional IAM policy element that you can use to specify special circumstances under which the policy grants or denies permission. A condition includes a condition key, operator, and value for the condition.
You should review, and possibly update, IAM policies with these condition keys before removing the member account. If you don’t update the policies, then users and roles in the account could lose access to the resources when the account leaves the organization. The aws:PrincipalOrgID condition key supports single value, so update this to the target organization ID after moved the account from the source organization.
The aws:PrincipalOrgPaths, aws:ResourceOrgID and aws:ResourceOrgPaths condition keys support multi values, so you could update this to include both the source and target organization.
Management account of an organization
If you’re moving the management account of an organization, then you must delete the organization and make the management account a standalone account. When you’ve removed all of the member accounts, follow the approach for deleting the organization from the Organizations User Guide.
Before you remove the management account, capture any cost allocation tags that you may have configured to track your AWS costs on a detailed level. In the target organization, apply and activate any AWS generated and user-defined cost allocation tags. Consider that all tags can take up to 24 hours to appear in the Billing and Cost Management console.
Quotas for Organizations
Consider the Organizations quotas for the target organization. For the quota, Number of AWS accounts in an organization, make sure that you’ve increased to allow for the additional accounts you’re moving into the organization.
Conclusion
In this post, we’ve walked you through the different features of Organizations, providing you guidance and consideration you’re need to move an AWS account from one organization to another. You’ve learned about considerations for moving an account when using Organizations features, including Authorization and management policies, AWS global condition context keys (aws:PrincipalOrgID, aws:PrincipalOrgPaths, aws:ResourceOrgID, and aws:ResourceOrgPaths), and resource sharing with AWS RAM. Using the AWS CLI, you’ve seen examples for discovering Organizations features in use, determining effective management policies, and discovering AWS RAM resource shares.
This post series walks you through the different features of Organizations, providing guidance and consideration for when you’re using Organizations and moving an AWS account from one organization to another.
In part two of the series, we help you determine any Organizations delegated administrators, and identify behavior and actions when you want to move an account registered as a delegated administrator for one or more compatible AWS services. In part three, we help you determine AWS services with trusted access in the organization, and identify actions and behaviors before you move an AWS account.
About the authors: