Register multiple AWS accounts with a single email address by using Amazon SES - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsTroubleshootingRelated resourcesAdditional information

Register multiple AWS accounts with a single email address by using Amazon SES

Created by Joe Wozniak (AWS) and Shubhangi Vishwakarma (AWS)

Code repository: GitHub aws-account-factory-email

Environment: PoC or pilot

Technologies: Infrastructure; Management & governance; Messaging & communications

AWS services: AWS Lambda; Amazon SES; Amazon DynamoDB

Summary

This pattern describes how you can decouple real email addresses from the email address that’s associated with an AWS account. AWS accounts require a unique email address to be provided at the time of account creation. In some organizations, the team that manages AWS accounts must take on the burden of managing many unique email addresses with their messaging team. This can be difficult for large organizations that manage many AWS accounts. Additionally, if your email system doesn’t allow plus addressing or sub-addressing as defined in Sieve Email Filtering: Subaddress Extension (RFC 5233)—by adding a plus sign (+) and an identifier to the end of the local part of the email address, such as admin+123456789123@example.com—this pattern can help overcome this limitation.

This pattern provides a unique email address vending solution that enables AWS account owners to associate one email address with multiple AWS accounts. The real email addresses of AWS account owners are then associated with these generated email addresses in a table. The solution handles all incoming email for the unique email accounts, looks up the owner of each account, and then forwards any received messages to the owner.  

Prerequisites and limitations

Prerequisites 

  • Administrative access to an AWS account.

  • Access to a development environment.

  • (Optional) Familiarity with AWS Cloud Development Kit (AWS CDK) workflows and the Python programming language will help you troubleshoot any issues or make modifications.

Limitations 

  • Overall vended email address length of 64 characters. For details, see CreateAccount in the AWS Organizations API reference.

Product versions

  • Node.js version 12.7.0 or later

  • Python 3.9 or later

  • Python packages pip and virtualenv

  • AWS CDK version 2.23.0 or later

  • Docker 20.10.x or later

Architecture

Target technology stack  

  • AWS CloudFormation stack

  • AWS Lambda functions

  • Amazon Simple Email Service (Amazon SES) rule and rule set

  • AWS Identity and Access Management (IAM) roles and policies

  • Amazon Simple Storage Service (Amazon S3) bucket and bucket policy

  • AWS Key Management Service (AWS KMS) key and key policy

  • Amazon Simple Notification Service (Amazon SNS) topic and topic policy

  • Amazon DynamoDB table

Target architecture 

Target architecture for registering multiple AWS accounts with a single email address

This diagram shows two flows:

  • Email address vending flow: In the diagram, the email address vending flow (lower section) begins typically with an account vending solution or outside automation, or is invoked manually. In the request, a Lambda function is called with a payload that contains the needed metadata. The function uses this information to generate a unique account name and email address, stores it in a DynamoDB database, and returns the values to the caller. These values can then be used to create a new AWS account (typically by using AWS Organizations).

  • Email forwarding flow: This flow is illustrated in the upper section of the previous diagram. When an AWS account is created by using the account email generated from the email address vending flow, AWS sends various emails, such as account registration confirmation and periodic notifications, to that email address. By following the steps in this pattern, you configure your AWS account with Amazon SES to receive emails for the entire domain. This solution configures forwarding rules that allow Lambda to process all incoming emails, check to see if the TO address is in the DynamoDB table, and forward the message to the account owner's email address instead. Using this process gives account owners the ability to associate multiple accounts with one email address.

Automation and scale

This pattern uses the AWS CDK to fully automate the deployment. The solution uses AWS managed services that will (or can be configured to) scale automatically to meet your needs. The Lambda functions might require additional configuration to meet your scaling needs. For more information, see Understanding Lambda function scaling in the Lambda documentation.

Tools

AWS services

Tools needed for deployment

Code 

The code for this pattern is available in the GitHub AWS account factory email repository.

Epics

TaskDescriptionSkills required

Identify or create an AWS account.

Identify an existing or new AWS account to which you have full administrative access, to deploy the email solution.

AWS administrator, Cloud administrator

Set up a deployment environment.

Configure an easy to use deployment environment and set up dependencies by following these steps:

  1. Set up your development environment with the tools listed in the Tools section.

  2. Clone the GitHub AWS account factory email repository code base to your development environment by using the command:

    git clone https://github.com/aws-samples/aws-account-factory-email

  3. In the requirements.txt file (in the root of the repository), update the line that starts with aws-cdk-lib==  to match the version of the AWS CDK that’s running in your environment. To identify the version, use the cdk --version command.

AWS DevOps, App developer
TaskDescriptionSkills required

Identify and allocate a domain.

The email forwarding functionality requires a dedicated domain. Identify and allocate a domain or subdomain that you can verify with Amazon SES. This domain should be available to receive incoming email within the AWS account where the email forwarding solution is deployed.

Domain requirements:

  • The domain should be a standard domain or subdomain.

  • The domain should be externally DNS resolvable, because it will be used to receive emails from outside the organization.

Cloud administrator, Network administrator, DNS administrator

Verify the domain.

Verify that the identified domain can be used to accept incoming email.

Complete the instructions in Verifying your domain for Amazon SES email receiving in the Amazon SES documentation. This will require coordination with the person or team who is responsible for the domain's DNS records.

App developer, AWS DevOps

Set up MX records.

Set up your domain with MX records that point to the Amazon SES endpoints in your AWS account and Region. For more information, see Publishing an MX record for Amazon SES email receiving in the Amazon SES documentation.

Cloud administrator, Network administrator, DNS administrator
TaskDescriptionSkills required

Modify the default values in cdk.json.

Edit some of the default values in the cdk.json file (in the root of the repository) so that the solution will operate correctly after it is deployed.

  1. Modify the SES_DOMAIN_NAME value to match the domain name you verified previously.

  2. Modify the ADDRESS_FROM value to include the same domain that is in SES_DOMAIN_NAME. The local part of the address should be determined by your cloud team. This address becomes the FROM address for every email that’s forwarded through the solution.

  3. Modify the ADDRESS_ADMIN value to match the email address that any non-matching incoming messages will be forwarded to. This value must be a valid and operating email address.

App developer, AWS DevOps

Deploy the email vending and forwarding solution.

  1. Create a Python virtual environment:

    python -m venv .venv

  2. Activate the Python virtual environment:

    source .venv/bin/activate

    Or, on the Windows platform, use:

    % .venv\Scripts\activate.bat

  3. Install all Python requirements with no errors:

    pip install -r requirements.txt

  4. Synthesize the CloudFormation template:

    cdk synth

    Confirm that there are no errors and that the full CloudFormation template contains the expected output.

  5. (Optional) If you are deploying the AWS CDK code into the current AWS account or Region for the first time, bootstrap the environment. For more information, see AWS CDK Bootstrapping in the AWS CDK documentation.

    cdk bootstrap aws://AWS-ACCOUNT-NUMBER/REGION

    Replace AWS-ACCOUNT-NUMBER and REGION with actual values.

  6. Deploy the solution:

    cdk bootstrap
cdk deploy

    The commands should complete without errors.

App developer, AWS DevOps

Verify that the solution has been deployed.

Verify that the solution deployed successfully before you begin testing:

  1. Open the AWS CloudFormation console and look for a CloudFormation stack that contains the name AwsMailFwdStack.

  2. Confirm that this AwsMailFwdStack stack has the following resources:

    • Lambda functions

    • Amazon SES rule and rule set

    • IAM roles and policies

    • Amazon S3 bucket and bucket policy

    • AWS KMS key and key policy

    • Amazon SNS topic and topic policy

    • DynamoDB table

App developer, AWS DevOps
TaskDescriptionSkills required

Verify that the API is working.

In this step, you submit test data to the solution's API and confirm that the solution produces the expected output and that backend operations have been performed as expected.

Manually run the Vend Email Lambda function by using test input. (For an example, see the sample_vend_request.json file.) For OwnerAddress, use a valid email address. The API should return an account name and account email with values as expected.

App developer, AWS DevOps

Verify that email is being forwarded.

In this step, you send a test email through the system and verify that the email is forwarded to the expected recipient.

  1. Obtain the account email from the last step.

  2. Send an email to this address with a test subject and body text.

  3. Confirm that you received the email at the account owner's email address.

  4. Confirm that the email you received has a FROM address that matches the ADDRESS_FROM setting in cdk.json.

  5. Confirm that the received email's subject and body are the same as the original sent message.

App developer, AWS DevOps

Troubleshooting

IssueSolution

The system doesn’t forward email as expected.

Verify that your setup is correct:

  1. You should have completed the Amazon SES verification process for your domain.

  2. Your domain should be set up properly with MX records pointing to the Amazon SES endpoints in your AWS account and Region. For more information, see Publishing an MX record for Amazon SES email receiving in the Amazon SES documentation.

After you verify your domain setup, follow these steps:

  1. Open the Amazon CloudWatch console for the account and Region where you deployed the solution, and navigate to CloudWatch log groups in the navigation pane.

  2. Search the list of log groups for SesMailForwardLogGroup.

  3. Investigate the logs in this group to see if any errors are generated during the email vending and forwarding process.

When you try to deploy the AWS CDK stack, you receive an error similar to:

“Template format error: Unrecognized resource types”

In most instances, this error message means that the Region you’re targeting doesn’t have all the available AWS services. If you’re using an Amazon EC2 instance to deploy the solution, you might be targeting a Region that is different from the Region where the instance is running.

Note: By default, the AWS CDK deploys to the Region and account that you configured in the AWS CLI.

Possible solutions:

  1. Investigate if all the services needed for this solution (see the Target technology stack section earlier in this pattern) are in the AWS Region you are targeting by reviewing AWS Services by Region.

  2. If you are using an EC2 instance and targeting a Region that’s different from the Region where your instance is running, make sure to set the AWS_DEFAULT_REGION environment variable, or set a Region with the AWS CLI before you deploy the solution. For more information, see the Configuring environment variables for the AWS CLI in the AWS CLI documentation. Alternatively, you can modify the app.py file in the root of the repository to include a hard-coded account ID and Region by following the instructions in the AWS CDK documentation for environments.

When you deploy the solution, you receive the error message:

“Deployment failed: Error: AwsMailFwdStack: SSM parameter /cdk-bootstrap/hnb659fds/version not found. Has the environment been bootstrapped? Please run 'cdk bootstrap'”

If you have never deployed any AWS CDK resources to the AWS account and Region you’re targeting, you will have to first run the cdk bootstrap command as the error indicates. If you continue to receive this error after you run the bootstrapping command, you might be trying to deploy the solution to a Region that’s different from the Region where your development environment is running.

To solve this problem, set the AWS_DEFAULT_REGION environment variable or set a Region with the AWS CLI before you deploy the solution. Alternatively, you can modify the app.py file in the root of the repository to include a hard-coded account ID and Region by following the instructions in the AWS CDK documentation for environments.

Related resources

Additional information

Costs

When you deploy this solution, the AWS account holder might incur costs that are associated with the use of the following services.  It is important for you to understand how these services are billed so you are aware of any potential charges. For pricing information, see the following pages: