Set up for customization

The next sections give steps to set up Account Factory for the customization process. We recommend that you set up delegated admin for the hub account, before you begin these steps.

Step 1. Create the required role

Before you begin to customize accounts, you must set up a role that contains a trust relationship between AWS Control Tower and your hub account. When assumed, the role grants AWS Control Tower access to administer the hub account. The role must be named AWSControlTowerBlueprintAccess.

AWS Control Tower assumes this role to create a Portfolio resource on your behalf in AWS Service Catalog, then to add your blueprint as a Service Catalog Product to this Portfolio, and then to share this Portfolio, and your blueprint, with your member account during account provisioning.

You'll create the AWSControlTowerBlueprintAccess role, as explained in the following sections.

If your blueprint hub account isn't enrolled in AWS Control Tower, the AWSControlTowerExecution role won't exist in the account, and there's no need to assume it before you continue with setting up the AWSControlTowerBlueprintAccess role.

The AWSControlTowerBlueprintAccess role must be set up to grant trust to two principals:

Here's an example trust policy, similar to one you will need to include for your role. This policy demonstrates the best practice of granting least-privilege access. When you make your own policy, replace the term YourManagementAccountId with the actual acccount ID of your AWS Control Tower management account, and replace the term YourControlTowerUserRole with the identifier of the IAM role for your management account.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                "arn:aws:iam::YourManagementAccountId:role/service-role/AWSControlTowerAdmin", 
                "arn:aws:iam::YourManagementAccountId:role/YourControlTowerUserRole"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Required permissions policy

AWS Control Tower requires that the managed policy named AWSServiceCatalogAdminFullAccess must be attached to the AWSControlTowerBlueprintAccess role. This policy provides permissions that AWS Service Catalog looks for when it allows AWS Control Tower to administer your portfolio and AWS Service Catalog Product resources. You can attach this policy when you're creating the role in the IAM console.

Step 2. Create the AWS Service Catalog product

To create an AWS Service Catalog product, follow the steps at Creating products in the AWS Service Catalog Administrator Guide. You'll add your account blueprint as a template when you create the AWS Service Catalog product.

You can download an AWS CloudFormation template from the AWS Service Catalog reference architecture repository. One example from that repository helps set up a backup plan for your resources.

Here's an example template, for a fictitious company called Best Pets. It helps set up a connection to their pet database.

Resources:
  ConnectionStringGeneratorLambdaRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service:
                - lambda.amazonaws.com
            Action:
              - "sts:AssumeRole"
  ConnectionStringGeneratorLambda:
    Type: AWS::Lambda::Function
    Properties:
      FunctionName: !Join ['-', ['ConnectionStringGenerator', !Select [4, !Split ['-', !Select [2, !Split ['/', !Ref AWS::StackId]]]]]]
      Description: Retrieves the connection string for this account to access the Pet Database
      Role: !GetAtt ConnectionStringGeneratorLambdaRole.Arn
      Runtime: nodejs16.x
      Handler: index.handler
      Timeout: 5
      Code:
        ZipFile: >
          const response = require("cfn-response");
          exports.handler = function (event, context) {
            const awsAccountId = context.invokedFunctionArn.split(":")[4]
            const connectionString= "fake connection string that's specific to account " + awsAccountId;
            const responseData = {
              Value: connectionString,
            }
            response.send(event, context, response.SUCCESS, responseData);
            return connectionString;
          };

  ConnectionString:
    Type: Custom::ConnectionStringGenerator
    Properties:
      ServiceToken: !GetAtt ConnectionStringGeneratorLambda.Arn

  PetDatabaseConnectionString:
    DependsOn: ConnectionString
    # For example purposes we're using SSM parameter store.
    # In your template, use secure alternatives to store
    # sensitive values such as connection strings.
    Type: AWS::SSM::Parameter
    Properties: 
      Name: pet-database-connection-string
      Description: Connection information for the BestPets pet database
      Type: String
      Value: !GetAtt ConnectionString.Value

Step 3. Review your custom blueprint

You can view your blueprint in the AWS Service Catalog console. For more information, see Managing products in the Service Catalog Adminstrator Guide.

Step 4. Call your blueprint to create a customized account

When you follow the Create account workflow in the AWS Control Tower console, you'll see an optional section where you can enter information about the blueprint you'd like to use for customizing accounts.

For more details, see Create a customized account from a blueprint.