Skip to main content

Cloud

Onboard an AWS Cloud account

Onboard an AWS account to take advantage of Illumio Cloud security features and minimize an attacker's lateral movement.

  1. Review the prerequisites. Prerequisites for Onboarding AWS.

  2. Onboarding a subscription with the wizard automatically provides the required permissions. See Permissions for Onboarding AWS.

  3. Onboard your organization. See Onboard AWS by running a CloudFormation stack, Onboard AWS using a Stack Template, and Onboard AWS in concert with CodeDeploy.

Ways to onboard your AWS account

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 Cloud 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 Cloud to create and run the CloudFormation stack, Cloud 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 Cloud to run the stack.

If you wish, you can incorporate AWS CodeDeploy as described in the instructions when you onboard AWS accounts using any of the above methods. See Onboard AWS in concert with CodeDeploy.

Onboard AWS by running a 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 a 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 Cloud. The name should be descriptive so that you can easily identify it in Cloud.

    • The AWS account ID of the account you are onboarding into Cloud

    Note

    The page contains a toggle below the Account ID field to specify the type of access Cloud 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 Cloud to your AWS account, click Download Permissions.

    Note

    This page contains a CI/CD Integration toggle for enabling CodeDeploy. This is optional, but you will want to select Yes if you wish to make use of the AWS CodeDeploy feature as described in Onboard AWS in concert with CodeDeploy. The toggle position will default to whatever setting you pick in Settings > CI/CD Integration. You can also select multiple, onboarded AWS accounts in the Onboarding page and click CI/CD > Disable/Enable to disable or enable CodeDeploy.

    When done completing your 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 Cloud. Cloud 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. Cloud 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. Cloud 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 Cloud. 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 Cloud 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 Cloud and a temporary Lambda function named LambdaExecutionRoleIllumioCloudAPICall. The Lambda function passes back to Cloud two credentials:

      • The ARN of the role from the Trusted entities

      • The secret key that AWS uses for authentication when Cloud accesses account resources

      Now, Cloud 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 Cloud for your account, see Prerequisites for Onboarding AWS.

    5. Leave the AWS console and return to Cloud.

    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 a 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.

    Cloud 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 Illumio Cloud 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 Cloud 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 Cloud script will notify Cloud that the stack was successfully created and Cloud will detect that account was onboarded and begin synchronizing the account resources with Cloud. A new row for that account appears in the Onboarding page.

Onboard AWS in concert with CodeDeploy

Illumio Cloud uses your CodeDeploy configuration when onboarding an account. You can choose to opt-in to CodeDeploy auto-discovery at anytime.

AWS CodeDeploy is a deployment service that automates application deployments to Amazon services. The Illumio Cloud integration with CodeDeploy automatically onboards all the applications and deployments defined in AWS into Illumio Cloud. This allows you to onboard quickly in order to gain insights and visibility into the application and deployment traffic for analysis and segmentation.

Additionally, Illumio Cloud lets you use AWS to:

  • Auto-discover your AWS CodeDeploy applications that already exist, and include them as Illumio Cloud applications

  • Auto-discover your Illumio Cloud environments (development, staging, production, etc.)

  • Visualize application drift between your Illumio Cloud environments for security review

Keep in mind the following notes:

  • When new applications and deployments are pulled from CodeDeploy, Illumio Cloud auto-approves these definitions by default

  • Illumio Cloud uses CodeDeploy as the source of truth for the application and deployment definitions. Any changes made in CodeDeploy to an application or deployment are synced and updated into Illumio Cloud.

  • Illumio Cloud does not support bi-directional syncing. Illumio Cloud pulls from CodeDeploy to maintain a consistent state across all applications and deployments.

  • When the CodeDeploy integration is disabled, Illumio Cloud stops syncing with AWS but the applications and deployments are not removed from Illumio Cloud

Naming Conventions

When Illumio Cloud syncs the application and deployment names from AWS, it converts the names into the following string format:

{ApplicationName}-{AWS_Account_ID}-{Region}

For example:

CodeDeployAppName-0123456789101-US-West-2

You can create Illumio Cloud names for the applications and deployments that CodeDeploy creates. Once you create the Illumio Cloud-specific name, you can search for the application or deployment using this name moving forward.

Tag Display

Illumio Cloud displays AWS tags and group tags, including those associated with the CodeDeploy application or deployment. These are not editable through the Illumio CloudUI. You can edit these tags in the AWS console.

Use CodeDeploy

Refer to the steps above in Onboard AWS by Running CloudFormation Stack and Onboard AWS using a Stack Template.

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 Cloud and click Delete.

    Initially the stack deletion will fail. The CloudFormation template provided by Cloud 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. See the Amazon website.

    The Stack will be deleted, removing all the resources (Role, Lambda, Custom Resource) created when running the stack.

What's next after onboarding your AWS account?

For the next steps after onboarding an account, see Onboarding AWS Cloud and After onboarding your accounts.