# Automate account creation by using the Landing Zone Accelerator on AWS *Justin Kuskowski, Joe Behrens, and Nathan Scott, Amazon Web Services* ## Summary This pattern explains how to use the [Landing Zone Accelerator on AWS](https://aws.amazon.com/solutions/implementations/landing-zone-accelerator-on-aws/) solution to automatically deploy a new AWS account when an authorized user submits a request. It uses AWS Step Functions to orchestrate a number of AWS Lambda functions. The Lambda functions add the account information to a Git repository, initiate an AWS CodePipeline pipeline, and validate that the necessary AWS resources are provisioned. When the process is complete, the user receives a notification that the account has been created. Optionally, you can integrate Microsoft Entra ID groups and assign AWS IAM Identity Center permission sets during the account creation process. If your organization is using Microsoft Entra ID as an identity source, this optional feature helps you automatically manage and configure access to the new account. ## Prerequisites and limitations **Prerequisites** + Access to the management account in AWS Organizations + AWS Cloud Development Kit (AWS CDK) version 2.118.0 or later, [installed](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_install) and [configured](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_configure) + Python version 3.9 or later, [installed](https://www.python.org/downloads/) + AWS Command Line Interface (AWS CLI) version 2.13.19 or later, [installed](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) + Docker version 24.0.6 or later, [installed](https://docs.docker.com/get-started/get-docker/) + Landing Zone Accelerator on AWS solution, [deployed](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/deploy-the-solution.html) in the management account + (Optional) Microsoft Entra ID and IAM Identity Center, [integrated](https://docs.aws.amazon.com/singlesignon/latest/userguide/idp-microsoft-entra.html) **Limitations** The account creation workflow supports sequential executions to deploy a single AWS account. This limitation makes sure that the account creation workflow has successfully completed without having to compete for resources during a parallel run. ## Architecture **Target architecture** The following image shows the high-level architecture of automating creation of a new AWS account by using the Landing Zone Accelerator on AWS. AWS Step Functions orchestrates the automation. Each task in the Step Functions workflow is performed by one or more AWS Lambda functions. ![\[Workflow to automate the creation of a new account by using the Landing Zone Accelerator on AWS.\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/images/pattern-img/d31abfaa-6854-4923-b896-3b817de9f4d9/images/dfd6503d-a4ed-43df-82d4-082f8153d473.png) The diagram shows the following workflow: 1. The user requests an account by either running a Python script or by using Amazon API Gateway. 1. The Account Creation Orchestrator workflow starts in AWS Step Functions. 1. The workflow updates the `account-config.yaml` file in the source code repository. It also initiates the Landing Zone Accelerator on AWS pipeline and checks the status of the pipeline. This pipeline creates and sets up the new account. For more information about how this works, see the [Architecture overview](https://docs.aws.amazon.com/solutions/latest/landing-zone-accelerator-on-aws/architecture-overview.html) for the Landing Zone Accelerator on AWS. 1. (Optional) When the pipeline is complete, the workflow checks whether the group exists in Microsoft Entra ID. If the group doesn’t exist in Microsoft Entra ID, the workflow adds the group to Microsoft Entra ID. 1. The workflow performs additional steps that the Landing Zone Accelerator on AWS solution can't do. The default steps include: + Creating an [account alias](https://docs.aws.amazon.com/IAM/latest/UserGuide/console-account-alias.html) in AWS Identity and Access Management (IAM) + Attaching [tags](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_tagging.html) to the account in AWS Organizations + Creating parameters in [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) based on the tags assigned to the account 1. (Optional) The workflow assigns one or more [permission sets](https://docs.aws.amazon.com/singlesignon/latest/userguide/permissionsetsconcept.html) to the Microsoft Entra ID group that you previously specified. The permission sets allow users in the group to access the new account and allow them to perform the actions you configure. 1. An AWS Lambda function runs QA and validation tests. It validates resource creation, checks that tags have been created, and validates that security resources have been deployed. 1. The workflow releases the account and uses Amazon Simple Email Service (Amazon SES) to notify the user that the process has completed successfully. For more information about the Step Functions workflow, see *Step Functions workflow diagram* in the [Additional information](#automate-account-creation-lza-additional) section of this pattern. **Microsoft Entra ID applications** If you choose to integrate with Microsoft Entra ID, you create the following two applications when you deploy this pattern: + An application that is linked to IAM Identity Center and makes sure that Microsoft Entra ID groups are available in IAM Identity Center. In this example, this Microsoft Entra ID application is named `LZA2`. + An application that allows a Lambda function to communicate with Microsoft Entra ID and call the [Microsoft Graph APIs](https://learn.microsoft.com/en-us/graph/identity-network-access-overview). In this pattern, this application is named `create_aws_account`. These applications collect data that is used to sync the Microsoft Entra ID group and assign permission sets. ## Tools **AWS services** + [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) helps you create, publish, maintain, monitor, and secure REST, HTTP, and WebSocket APIs at any scale. In this pattern, you use API Gateway to check the availability of AWS account names, initiate the AWS Step Functions workflow, and check the status of the Step Functions execution. + [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html) is a software development framework that helps you define and provision AWS Cloud infrastructure in code. + [AWS Control Tower](https://docs.aws.amazon.com/controltower/latest/userguide/what-is-control-tower.html) helps you set up and govern an AWS multi-account environment, following prescriptive best practices. + [Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) is a serverless event bus service that helps you connect your applications with real-time data from a variety of sources. For example, AWS Lambda functions, HTTP invocation endpoints using API destinations, or event buses in other AWS accounts. This solution uses an [EventBridge rule](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-rules.html) that starts a Lambda function if the Step Functions workflow state changes to `Failed`, `Timed-out`, or `Aborted`. + [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them. + [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) helps you centrally manage single sign-on (SSO) access to all of your AWS accounts and cloud applications. + [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) helps you create and control cryptographic keys to help protect your data. In this pattern, AWS KMS keys are used to encrypt data, such as data stored in Amazon Simple Storage Service (Amazon S3), Lambda environment variables, and data in Step Functions. + [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) is a compute service that helps you run code without needing to provision or manage servers. It runs your code only when needed and scales automatically, so you pay only for the compute time that you use. + [AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html) is an account management service that helps you consolidate multiple AWS accounts into an organization that you create and centrally manage. + [Amazon Simple Email Service (Amazon SES)](https://docs.aws.amazon.com/ses/latest/dg/Welcome.html) helps you send and receive emails by using your own email addresses and domains. After a new account is successfully created, you receive a notification through Amazon SES. + [Amazon Simple Notification Service (Amazon SNS)](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) helps you coordinate and manage the exchange of messages between publishers and clients, including web servers and email addresses. If an error occurs during the account creation process, Amazon SNS sends a notification to the email addresses that you configure. + [AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html) is a serverless orchestration service that helps you combine AWS Lambda functions and other AWS services to build business-critical applications. + [AWS Systems Manager Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) provides secure, hierarchical storage for configuration data management and secrets management. **Other tools** + [awscurl](https://pypi.org/project/awscurl/0.6/) automates the process of signing AWS API requests and helps you make requests as a standard curl command. + [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/whatis), formerly known as *Azure Active Directory*, is a cloud-based identity and access management service. + [Microsoft Graph APIs](https://learn.microsoft.com/en-us/graph/graph-explorer/graph-explorer-overview) help you access data and intelligence in Microsoft cloud services, such as Microsoft Entra and Microsoft 365. **Code repository** The code for this pattern is available in the GitHub [lza-account-creation-workflow](https://github.com/aws-samples/lza-account-creation-workflow) repository. The [lambda\$1layer](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_layer) directory contains the following layers, which are referenced in more than one Lambda function: + [account\$1creation\$1helper](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_layer/account_creation_helper) – This layer includes the modules for assuming roles and checking the progress in AWS Service Catalog. + [boto3](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_layer/boto3) – This layer includes the [AWS SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) module to make sure that AWS Lambda has the latest version. + [identity\$1center\$1helper](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_layer/identity_center_helper) – This layer supports calls to IAM Identity Center. The [lambda\$1src](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src) directory contains the following Lambda functions: + [AccountTagToSsmParameter](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/event/AccountTagToSsmParameter) – This function uses the tags attached to the account in AWS Organizations in order to create parameters in Parameter Store. Each parameter starts with an `/account/tags/` prefix. + [AttachPermissionSet](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/AttachPermissionSet) – This function adds a permission set to an IAM Identity Center group. + [AzureADGroupSync](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/AzureADGroupSync) – This function syncs the target Microsoft Entra ID group to IAM Identity Center. + [CheckForRunningProcesses](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/CheckForRunningProcesses) – This function checks whether the `AWSAccelerator-Pipeline` pipeline is currently running. If the pipeline is running, the function delays the AWS Step Functions workflow. + [CreateAccount](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/CreateAccount) – This function uses AWS Service Catalog and AWS Control Tower to create the new AWS account. + [CreateAdditionalResources](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/CreateAdditionalResources) – This function creates the AWS resources that aren't managed by Landing Zone Accelerator or AWS CloudFormation, such as the account alias and AWS Service Catalog tags. + [GetAccountStatus](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/GetAccountStatus) – This function scans for the provisioned product in AWS Service Catalog to determine if the account creation process has completed. + [GetExecutionStatus](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/api/GetExecutionStatus) – This function retrieves the status of a running or completed AWS Step Functions execution. + [NameAvailability](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/api/NameAvailability) – This function checks if an AWS account name already exists in AWS Organizations. + [ReturnResponse](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/ReturnResponse) – If the account creation was successful, this function returns the ID of the new account. If the account creation was not successful, it returns an error message. + [RunStepFunction](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/api/RunStepFunction) – This function runs the AWS Step Functions workflow that creates the account. + [SendEmailWithSES](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/SendEmailWithSES) – This function sends emails to the users who are waiting for the account creation to finish. + [ValidateADGroupSyncToSSO](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/ValidateAdGroupSyncToSSO) – This function checks if the specified Microsoft Entra ID groups are synced with IAM Identity Center. + [ValidateResources](https://github.com/aws-samples/lza-account-creation-workflow/tree/main/app/lambda_src/stepfunction/ValidateResources) – This function validates that all AWS Control Tower customizations have run successfully. ## Best practices We recommend the following naming conventions for the AWS CDK:  + Start all parameters with a `p` prefix. + Start all conditions with a `c` prefix. + Start all resources with an `r` prefix. + Start all outputs with an `o` prefix. ## Epics ### Deploy the IAM roles for validation and tagging | Task | Description | Skills required | | --- | --- | --- | | Prepare the Landing Zone Accelerator on AWS for customization. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | AWS DevOps | | Prepare to deploy the `lza-account-creation-validation` role. | Now, you customize the solution to deploy the `lza-account-creation-validation` IAM role in all accounts other than the management account. This role provides the `ValidateResources` Lambda function with read-only access to the new accounts.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | AWS DevOps | | Prepare to deploy the `account-tagging-to-ssm-parameter-role` role. | Now, you customize the solution to deploy the `account-tagging-to-ssm-parameter-role` IAM role in all accounts other than the management account. This role is used to create the parameters in AWS Systems Manager Parameter Store.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | AWS DevOps | | Prepare to deploy the `config-log-validation-role` role. | Now, you customize the solution to deploy the `config-log-validation-role` IAM role in the log archive account. This role allows the `ValidateResources` Lambda function to access the Amazon S3 bucket for logging and access AWS Config rules.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | AWS DevOps | ### (Optional) Get data from Microsoft Entra ID | Task | Description | Skills required | | --- | --- | --- | | Create the application that that allows a Lambda function to communicate with Microsoft Entra ID. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | Microsoft Entra ID | | Retrieve values for the `create_aws_account` application. | Now, you retrieve the values that you need for the `create_aws_account` application.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | Microsoft Entra ID | | Create the application that integrates Microsoft Entra ID with IAM Identity Center. | In the Microsoft Entra ID admin center, register the `LZA2` application. For instructions, see [Register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) in the Microsoft documentation. | Microsoft Entra ID | | Retrieve values for the `LZA2` application. | Now, you retrieve the values that you need for the `LZA2` application.[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | Microsoft Entra ID | | Create a secret. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | AWS DevOps | ### Deploy the solution | Task | Description | Skills required | | --- | --- | --- | | Clone the source code. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | DevOps engineer | | Update the `deploy-config.yaml` file. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | AWS DevOps | | Deploy the solution in your AWS environment. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html)This solution uses an Amazon S3 bucket to store the source code for this solution. You can use the [upload\$1to\$1source\$1bucket.py](https://github.com/aws-samples/gen-ai-trivia/blob/main/scripts/upload_to_source_bucket.py) script to create an archive of the source code and upload an updated version. | AWS DevOps | ### Option 1 – Create an account using Python | Task | Description | Skills required | | --- | --- | --- | | Identify which arguments to use. | Choose which arguments to use when you run the Python script that initiates the Step Functions workflow. For a complete list of arguments, see the [Additional information](#automate-account-creation-lza-additional) section of this pattern. | AWS DevOps, Python | | Start the Python script. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | DevOps engineer, Python | ### Option 2 – Create an account using API Gateway and awscurl | Task | Description | Skills required | | --- | --- | --- | | Set up the variables for awscurl. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | AWS DevOps | | Check name availability. | Enter the following command to verify that the name is available for the AWS account. Replace `` with the name of the target account:
awscurl --service execute-api \
    --region ${AWS_REGION} \
    --access_key ${AWS_ACCESS_KEY_ID} \
    --secret_key ${AWS_SECRET_ACCESS_KEY} \
    --security_token ${AWS_SESSION_TOKEN} \
    -X POST ${API_GATEWAY_ENDPOINT}check_name?account_name=
| AWS DevOps | | Run the account creation workflow. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | AWS DevOps | ### (Optional) Clean up the solution | Task | Description | Skills required | | --- | --- | --- | | Remove objects from the Amazon S3 buckets. | Remove any objects in the following Amazon S3 buckets:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/automate-account-creation-lza.html) | AWS DevOps | | Delete the CloudFormation stack. | Enter the following command to delete the CloudFormation stack:
aws cloudformation delete-stack \
  --stack-name lza-account-creation-workflow-application
aws cloudformation wait stack-delete-complete \
  --stack-name lza-account-creation-workflow-application
| AWS DevOps | | Delete the pipeline. | Enter the following command to delete the `lza-account-creation-workflow-pipeline` pipeline:
cdk destroy lza-account-creation-workflow-pipeline --force
| AWS DevOps | ## Related resources + [Landing Zone Accelerator on AWS](https://aws.amazon.com/solutions/implementations/landing-zone-accelerator-on-aws/) (AWS Solutions Library) + [Troubleshooting common AWS CDK issues](https://docs.aws.amazon.com/cdk/v2/guide/troubleshooting.html) (AWS CDK documentation) ## Additional information **Step Functions workflow diagram** The following image shows the states in the Step Functions workflow. ![\[States in the Step Functions workflow.\]](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/images/pattern-img/d31abfaa-6854-4923-b896-3b817de9f4d9/images/d93aa7bf-1144-4f25-9488-aacc534a7813.png) **Arguments** The following are the arguments that you can use when you run the Python script that initiates the Step Functions workflow. The following arguments are required: + `account-name (-a)` (string) – The name of the new AWS account. + `support-dl (-s)` (string) – The email address that receives notification when the account creation process is complete. + `managed-org-unit (-m)` (string) – The managed [organizational unit (OU)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_getting-started_concepts.html#organizationalunit) that will contain the new account. The following arguments are optional: + `ad-integration (-ad)` (string dictionary) – The Microsoft Entra ID group and assigned permission set. The following is an example of how to use this argument: ``` --ad-integration "{\"\": \"\"}" ``` + `account-email (-e)`** **(string) – The email address for the root user of the new AWS account. **Note** If this argument isn't used, an email address will be generated by using the values `rootEmailPrefix` and `rootEmailDomain` from the `configs/deploy-config.yaml` file. If an email address isn't provided, an email address is generated by using the following format: `rootEmailPrefix+accountName@rootEmailDomain`. + `region (-r)` (string) – The AWS Region where the Step Functions workflow was deployed. The default value is `us-east-1`. + `force-update (-f)` (string Boolean) – Enter `true` to force AWS Service Catalog to update the provisioned product. + `bypass-creation (-b)` (string Boolean) – Enter `true` to bypass adding the account to the `accounts-config.yaml` file and bypass running the `AWSAccelerator-Pipeline` pipeline. This argument is typically used to test the account creation workflow process or to run the rest of the Step Functions steps if an error occurs in the `Landing Zone Accelerator` pipeline. + `tags (-t)` (string) – Additional tags that you want to add to the AWS account. By default, the following tags are added: `account-name`, `support-dl`, and `purpose`. The following is an example of how to use this argument: ``` --tags TEST1=VALUE1 TEST2=VALUE2 ```