Onboard an AWS Cloud Account

This topic explains how to onboard an AWS account.

Prerequisites

  • Before onboarding an AWS account, copy the account ID for the account you want to onboard so that you can specify it in the first step of the onboarding wizard
  • Determine the method to use for onboarding the account — either by using CloudSecure to run the CloudFormation stack or by using an Illumio provided YAML file as a template to manually create the stack
  • Prior to onboarding an AWS account, ensure that CloudSecure has the required AWS permissions. See Prerequisites for Onboarding AWS for information.

  • You need to login to the account in which you will run the stack, so that account will need at least administrator permissions

Ways to Onboard AWS

IMPORTANT:

The wizard for onboarding an AWS account contains the option to onboard a single AWS account or an AWS organization (which is a collection of accounts).

When onboarding an AWS account, you have the option to use CloudSecure to create the stack in the AWS console or by downloading a YAML file and completing the settings outside of the AWS console.

When you use CloudSecure to create and run the CloudFormation stack, CloudSecure populates the required data in AWS to run the stack. When you choose to download and use a YAML file, you must complete the file with the required data.

Illumio recommends that you use the first option to onboard an AWS account and allow CloudSecure to run the stack.

Onboard AWS by Running CloudFormation Stack

This procedure describes the Illumio recommended method for creating the stack. For information about creating the stack by downloading a YAML file, see Onboard AWS using Stack Template.

  1. If this is the first time you are logging in, click + AWS to onboard your first account.

    If you've already onboarded other accounts, choose Onboarding from the left navigation. The Onboarding page appears. Click +Add AWS at the top of the page.

    The Add AWS Cloud Account wizard starts and displays the first step: Connect to AWS

  2. Provide the following information about your AWS account:

    • Name for the account

      This name is what will appear in CloudSecure. The name should be descriptive so that you can easily identify it in CloudSecure.

    • The AWS account ID of the account you are onboarding into CloudSecure
    NOTE:

    The page contains a toggle below the Account ID field to specify the type of access CloudSecure will have to your AWS account. Choosing Yes grants the Illumio Cross Account Role permission to view your AWS account resources and to apply policy to them. Choosing No provides the Illumio Cross Account Role read-only access. To view the permissions you are granting CloudSecure to your AWS account, click Download Permissions.

    When done completing these settings, click Next.

    The wizard advances to step two: Set up Access

  3. Select or create a service account.

    NOTE:

    During onboarding, you configure a service account for CloudSecure. CloudSecure uses this digital identity to interact with your AWS account. The service account has read/write access, which you granted in the first step of the wizard.

    If you haven't onboarded any accounts yet, click Add a new Service Account in the Service Account drop-down list and specify a name and description (optional) and click Create.

    A pop-up dialog box appears displaying information about the credentials created for the service account. You cannot copy information from the dialog box. Click Download Credentials to save this information locally, then click Close.

    IMPORTANT:

    Open the downloaded credentials file (Service-Account-<name>.txt) for the service account and copy the value in the serviceAccountToken field. You will need this value when creating the CloudFormation stack in AWS. CloudSecure only provides these credentials for download during this step of the onboarding wizard.

    NOTE:

    Alternatively, you can select an existing service account from a previous onboarding. When you use an existing service account, you must still have access to the downloaded credentials file and service account secret. If you do not have access to that file, you must create a new service account.

  4. Under Type of Integration, select Create Cloud Formation Stack. The button Create IAM Roles on AWS becomes enabled.

    1. To create a new stack, click Create IAM Roles on AWS. CloudSecure opens the AWS Sign in page in a new browser window. Sign into AWS as a Root or Administrator user. The Quick create stack page appears.

      The page is pre-populated with the required values, such as the URL for the YAML file, the stack name, the key for the service account you specified, and more. The field for the service account secret is not populated.

      NOTE:

      The stack name needs to be unique for CloudSecure. If you already have a stack in AWS with the pre-populated name, modify the name so that it is unique.

    2. In the Quick create stack page, paste the credential secret that you copied from the downloaded credentials file.
    3. Select the check box to acknowledge that CloudSecure will create IAM resources in AWS.

    4. Click Create stack.

      The script to create the stack runs. When it finishes, your AWS account includes custom IAM roles required by CloudSecure and a temporary Lambda function named LambdaExecutionRoleIllumioCloudAPICall. The Lambda function passes back to CloudSecure two credentials:

      • The ARN of the role from the Trusted entities
      • The secret key that AWS uses for authentication when CloudSecure accesses account resources

      Now, CloudSecure has the required credentials to access your AWS account so that you don't have to repeatedly provide them.

      For the complete list of permissions granted to CloudSecure for your account, see Prerequisites for Onboarding AWS.

    5. Leave the AWS console and return to CloudSecure.

    6. Click Next. The final step of the wizard appears.

      The wizard displays a summary of the account information you just specified.

  5. Review the account information and if everything looks correct, click Save and Confirm. If you see issues you need to correct, click Back and return to that wizard step.

You account is successfully onboarded and a row for that account appears in the Onboarding page.

Onboard AWS using Stack Template

NOTE:

Choose this option when you don't have the required permissions in AWS to create a CloudFormation stack or you want to create the CloudFormation stack manually.

  1. Launch the onboarding wizard in either of the following ways:

    • Click + AWS in the Onboarding page to onboard your first account when you sign in for the first time
    • From the left navigation, choose Onboarding and click + AWS at the top of the page.
  2. Follow steps 2 and 3 from the procedure above

  3. In step two (Set up Access) of the onboarding wizard, select Download Cloud Formation Stack and click Download.

    CloudSecure downloads an AWS Integration YAML file to your local system. This YAML file contains sections for the data required to create and run the CloudFormation stack in AWS. Some sections of the YAML file are pre-populated with default values. In other sections, the default value is empty.

    NOTE:
    If you wish to share the CloudFormation stack with others so that they can run it, you will need the CloudSecure ID. It will display in the Add AWS Account dialog.
  4. Complete the missing values as required and save the file.
  5. Log into your AWS console with the required permissions to run a CloudFormation stack or provide the file to members of your organization who have the required AWS account access.

  6. Use the completed AWS Integration file as an AWS CloudFormation template to run the stack. The CloudSecure YAML file provided by Illumio is a valid stack template file.

    For information, see “Creating a stack” in the Amazon AWS online documentation.

  7. Click Next. The final step of the wizard appears.
  8. Review the account information and if everything looks correct, click Save and Confirm. If you see issues you need to correct, click Back and return to that wizard step.

When the stack command finishes running in AWS and you've successfully created the stack, a CloudSecure script will notify CloudSecure that the stack was successfully created and CloudSecure will detect that account was onboarded and begin synchronizing the account resources with CloudSecure. A new row for that account appears in the Onboarding page.

Remove the Integration

You can delete the integration for a given account by selecting the account and clicking Remove > Remove. However, you will need to then manually delete the CloudFormation Stack in AWS.

  1. Login to the AWS Console and choose Services > CloudFormation.

  2. Select Stacks, and, in the list of stacks, choose the stack name you used while onboarding Cloudsecure and click Delete.

    Initially the stack deletion will fail. The CloudFormation template provided by CloudSecure creates Lambda-backed custom resources, which AWS does not automatically clear.

  3. If it fails, select the stack and click Delete again.

    A pop-up window appears with the option to retain the resources that are failing to delete.

  4. Choose that checkbox option and click Delete.

    Note: Although you selected the option to retain resources, custom resources are specific to CloudFormation and they will be cleared upon the deletion of the stack. Ref: https://repost.aws/knowledge-center/cloudformation-lambda-resource-delete.
    The Stack will be deleted, removing all the resources (Role, Lambda, Custom Resource) created when running the stack.

What's Next?

For the next steps after onboarding an account, see After Onboarding Cloud Accounts and What to Do Next.