Onboard an AWS Cloud Account

After InsightCloudSec is successfully installed, you're ready to start harvesting resources from your target accounts. This documentation provides details on configuring AWS to "talk" with InsightCloudSec securely for both admin and non-admin users and explains the different onboarding workflows you can expect for new and returning users.

Getting Started with Onboarding AWS

Before you can begin the onboarding process, you'll need to navigate to the Cloud Account Onboarding interface, which provides a different experience depending on the type of user you are:

UserDescriptionExperience
First-time UserInsightCloudSec is freshly deployed and this will be the first time a Cloud Service Provider (CSP) has been onboarded.Platform Users:
Onboarding wizard launched from Platform Home by clicking the InsightCloudSec tile.

InsightCloudSec Only Users:
The onboarding wizard appears automatically after logging in using your unique InsightCloudSec URL.
Returning UserInsightCloudSec has one or more CSPs already onboarded and you would like to add a new account.Launched from within InsightCloudSec. Not a wizard.
Admin UserYou can login to the cloud provider and have the appropriate access to grant InsightCloudSec access to your account(s).As an admin, you will need to complete some specific tasks within your Cloud Service Provider's (CSP) console to generate details needed for onboarding that either you or a non-admin user can input to InsightCloudSec.
Non-Admin UserYou can interact with InsightCloudSec and would like to onboard an account(s) but do not have the appropriate CSP access to grant InsightCloudSec access to your account(s).You will need to copy and send a message to the admin asking them to complete specific tasks and provide you with the information you need to complete onboarding.

For information about modifying an existing AWS account, check out the Cloud Account Setup & Management page.

Configuration Information for AWS

There are several steps that must be taken within the AWS console to enable InsightCloudSec to get access to an account, and this page provides those steps.

Additional Resources on AWS include:

CloudFormation Templates

All InsightCloudSec configuration parameters, users, roles, and policies are managed using CloudFormation Templates (CFTs). We use up to two CFTs in the onboarding process (depending on your selected AWS partition); links to view the CFTs can be found below while the policies are contained on AWS Commercial Policies.

InsightCloudSec offers some features that require additional permissions/roles within AWS. It is easiest to perform this configuration while onboarding an account/organization, so our provided CFT can automatically do so (optionally) during general account onboarding. Review the links below to determine which features you'd like to use and we'll provide a reminder to select the relevant options later.

Connect an Amazon Web Services (AWS) cloud account to allow InsightCloudSec harvest data and provide insights into your cloud environment.

Onboard an account as a non-admin user

As a non-admin user, you will need to copy and send a message to the admin asking them to complete specific tasks and provide you with the information needed to complete onboarding.

Ask an admin for required information

  1. In the Insight Platform, click InsightCloudSec to launch the onboarding wizard.
  2. On the Welcome screen, review key features and capabilities, then click Onboard a Cloud Account.
  3. On the Cloud Service Providers screen, select Amazon Web Services.
  4. On the Select your Role screen, select No, help me identify the details I need.
  5. Copy the details from the AWS Admin Instructions text box and share them with the admin.

Connect the account

When your admin has completed their steps and provided the information to you, complete the wizard to connect the account.

  1. In the Insight Platform, click InsightCloudSec. The last page you were on should open.
  2. Enter the values provided by the admin.
  3. Click Connect Account to begin harvesting.

Onboard a cloud account as an admin

All InsightCloudSec configuration parameters, users, roles, and policies are managed using CloudFormation Templates (CFTs).

Setup AWS for InsightCloudSec

Step 1: Generate the External ID

An External ID is generated for your specific InsightCloudSec organization when you initiate the process to add an AWS Organization within InsightCloudSec. The External ID will be the same for every individual cloud account or AWS Organization.

This process obeys AWS best practices and prevents the confused deputy problem from occurring. The confused deputy problem is a security issue where an entity that doesn't have permission to perform an action can coerce a more-privileged entity to perform the action.

Generate the External ID

  1. Login as an Admin to InsightCloudSec and go to Cloud > Clouds.
  2. On the Organizations tab, click Add Organization.
  3. For Cloud Type, select Amazon Web Services.
  4. Copy the External ID. The External ID is the same for both parts of the form (Organization data and Organization member accounts)/
Step 2: Create a CloudFormation Stack for Organization Data Harvesting

Your AWS cloud account needs a standard harvesting role and policy to ensure proper integration with InsightCloudSec. This requires creating another CloudFormation Stack using the provided Harvest-Role-Member CFT that will configure the account for the additional role and policy.

Create a CloudFormation Stack for Organization Data Harvesting

  1. Login as an Admin to the AWS account you want to harvest and access the CloudFormation service and click Stacks in the left-hand menu.
  2. In the top right corner of the Stacks table, click Create stack > With new resources (standard).
  3. On the Import overview page, click Next.
  4. Specify the Management Account Organization Role CFT URL.
    1. Click Template is ready.
    2. Click Amazon S3 URL.
    3. Input the Harvest Organization Role CFT URL: https://s3.amazonaws.com/get.divvycloud.com/prodserv/divvycloud-deployment-native/aws/cft/iam/DivvyCloud-AWS-IAM-Harvest-Role-Org-CFT.yaml
    4. Click Next.
  5. Specify stack details.
  1. Enter a name for the stack. For example InsightCloudSec-Org-Data-Harvester-Stack
  2. Select Yes to require an external ID to assume the Organization role, then enter the external ID.
  3. Optionally, update the default policy name. For example: InsightCloudSec-Org-ListDesc-Policy
  4. Enter the ARN for your InsightCloudSec instance. The ARN contains your unique AWS account ID and role name.
  5. Click Next.
  6. (Optional) Add tags, and click Next.
  1. Review and create the stack.
  1. Review the stack's configuration to ensure everything is accurate.
  2. Acknowledge the warning about IAM capabilities toward the bottom of the page.
  3. Click Create stack.
  4. Verify the stack is created successfully.
Step 3: Create a CloudFormation Stack for Organization Management Account Harvesting

Your AWS Organization Management account also needs a standard harvesting role and policy to ensure proper integration with InsightCloudSec. This requires creating another CloudFormation Stack using the provided Harvest-Role-Member CFT that will configure the Organization Management account for the additional role and policy

Note: Ensure you're logged into the Organization Management account so the StackSet can be run from there to access all the member accounts you wish to harvest.

Create a CloudFormation Stack for Organization Management Account Harvesting

  1. Login as an Admin to your Organization Management AWS account and access the CloudFormation service and click StackSets in the left-hand menu.
  2. In the top right corner of the Stacks table, click Create StackSet.
  3. Configure the template.
    1. (Optional) Provide an IAM admin role to perform all the operations in the StackSet within your account(s) and adjust the IAM execution role name as necessary.
    2. Click Template is ready.
    3. Click Amazon S3 URL.
    4. Input the Harvest Member Role CFT URL: https://s3.amazonaws.com/get.divvycloud.com/cft/Divvy-CFT-IAM-Harvest-Role-Member.yaml
    5. Click Next.
  4. Specify the StackSet details.
    1. Enter a name for the stack.
    2. Edit the parameters.
      1. For the Harvest role type, select Standard-Managed (read only, AWS managed). Review AWS-Managed Supplemental Policy for more information about this policy.
      2. (Optional) Update the default role and/or policy name. For example: InsightCloudSec-Org-Member-Role
      3. Enter the same ARN you used in the stack for your InsightCloudSec instance in the previous step.
    3. Select Yes to require an external ID to assume the harvesting role, then provide the InsightCloudSec external ID.
    4. Click Next.
    5. (Optional) Add tags, IAM roles, and set additional options.
    6. Click Next.
  5. Review and create the stack.
    1. Review the stack's configuration to ensure everything is accurate.
    2. Acknowledge the warning about IAM capabilities toward the bottom of the page.
    3. Click Create stack.
    4. Verify the stack is created successfully.
Step 4: Create a CloudFormation StackSet for Member Account Harvesting

Setting up proper harvesting of your accounts and their associated resources is straightforward: each account that contains resource data you want to harvest for InsightCloudSec will need access to the same harvesting role (Role ARN, external ID, etc.) with the same policy attached. The relevant CFT for this setup will configure all provided accounts accordingly.

Note: Ensure you're logged into the Organization Management account so the StackSet can be run from there to access all the member accounts you wish to harvest.

Create a CloudFormation StackSet for Member Account Harvesting

  1. Login as an Admin to your Organization Management AWS account and access the CloudFormation service and click StackSets in the left-hand menu.
  2. In the top right corner of the Stacks table, click Create StackSet.
  3. Configure the template.
    1. (Optional) Provide an IAM admin role to perform all the operations in the StackSet within your account(s) and adjust the IAM execution role name as necessary.
    2. Click Template is ready.
    3. Click Amazon S3 URL.
    4. Input the Harvest Member Role CFT URL: https://s3.amazonaws.com/get.divvycloud.com/cft/Divvy-CFT-IAM-Harvest-Role-Member.yaml
    5. Click Next.
  4. Specify the StackSet details.
    1. Enter a name for the stack.
    2. Edit the parameters. The values must match the parameters from the stack created in the previous step.
      1. For the Harvest role type, select Standard-Managed (read only, AWS managed). Review AWS-Managed Supplemental Policy for more information about this policy.
      2. (Optional) Update the default role and/or policy name. For example: InsightCloudSec-Org-Member-Role
      3. Enter the same ARN you used in the stack for your InsightCloudSec instance in the previous step.
    3. Select Yes to require an external ID to assume the harvesting role, then provide the InsightCloudSec external ID.
    4. Click Next.
    5. (Optional) Add tags, IAM roles, and set additional options.
    6. Click Next.
  5. Set deployment options.
    1. Click Deploy new stacks.
    2. Choose to either deploy to accounts or organizational units, then provide a comma-delimited list of accounts or organizational units (or upload a CSV file).
    3. Select us-east-1 to deploy the stack. Note: Currently only single-region role deployment is supported.
    4. Click Next.
  6. Review and create the stack.
    1. Review the StackSet's configuration to ensure everything is accurate.
    2. Acknowledge the warning about IAM capabilities toward the bottom of the page.
    3. Click Create Submit.
    4. Verify the StackSet is created successfully.

Connect the account in InsightCloudSec

  1. In the Insight Platform, click InsightCloudSec to launch the onboarding wizard.
  2. On the Welcome screen, review key features and capabilities, then click Onboard a Cloud Account.
  3. Identify the cloud service provider.
    1. On the Cloud Service Providers screen, select Amazon Web Services.
    2. On the Select your Role screen, select Yes - I have sufficient permissions.
    3. Select the AWS partition in which the account is located.
      • If the AWS partition is Commercial, copy the Authenticating Principal ID to a secure location.
      • If the AWS partition is Government or China, click Launch CFT to open the AWS CloudFormation Console and execute the CFT to create an IAM user.
    4. Click Next.
  4. Set the Roles and Permissions for either an individual account or organization, and then click Next.
    • Individual account
      1. Select the I acknowledge and accept the permissions outlined in the above CFT checkbox.
      2. Click Launch CFT to open the AWS CloudFormation Console and execute the CFT to onboard the account.
    • Organization
      1. Select the I acknowledge and accept the permissions outlined in the above CFT checkbox.
      2. Click Launch CFT to open the AWS CloudFormation Console (in a new browser tab) and execute the CFT to onboard the Management Account.
      3. Deploy the same CFT to all member Accounts using a CloudFormation StackSet.
  5. Finalize the connection.
    1. In the Role ARN field, verify that the value correctly populated.
    2. Enter a nickname for the account.
    3. If your authentication is IAM User via API Keys for China and Government partitions, enter the Access Key and Secret Key.
    4. Click Connect Account to begin harvesting.

Onboard an account as a returning user

  1. In InsightCloudSec, go to Cloud > Clouds.
  2. Click Add Cloud.
  3. Complete the wizard.

Post-onboarding information for Organization accounts

If you followed the instructions above and onboarded an AWS Organization, you should have at least your Organization account with full visibility in InsightCloudSec. Review the following sections for more information on augmenting your Organization onboarding experience or managing the Organization within InsightCloudSec.

Enable account discovery

Once an Organization is onboarded to InsightCloudSec, we automatically detect the Organization and prompt you to enable Account Discovery. If you clicked the "Enable Auto Discovery" button within the onboarding wizard, you'll be taken to the Edit Organization Config window for the new Organization.

  1. From the Edit Organization Config window, select Auto-Sync Accounts.
  2. Click UPDATE.

Once enabled, accounts are discovered via the API dynamically and configured with defaults you provide.

Modify an organization

After onboarding an AWS Organization, you can edit configuration information at any time.

  1. From InsightCloudSec, go to Cloud > Cloud Accounts > Organizations.
  2. Next to the desired Organization, click the options button (hamburger icon), then click Edit Organization.
  3. Adjust the nickname or credentials values as necessary.
  4. Adjust the scope/badging options as necessary:
    • Member Accounts to Skip: Enter details for member accounts (ID’s or Names) to be skipped (e.g., you have a group of development accounts you are not interested in tracking)
    • Auto-Sync Accounts: Select this box to add all accounts associated with the organization. If not checked, each account must be added manually.
    • Auto-remove suspended accounts: Select this box to automatically remove suspended AWS accounts from InsightCloudSec. As soon as this checkbox is enabled, a background process will begin running and remove the accounts automatically as they are found
    • Auto-Badge Accounts: Select this box to allow InsightCloudSec to automatically badge your incoming accounts based on AWS account tags
    • Limit import scope: Select this box and provide Organizational Unit (OU) ID(s) to only include nested accounts and OUs associated with a given ID (or set of IDs)
  5. Click UPDATE.

Associate badges with accounts

Accounts added via an AWS Organization will have a few Badges automatically associated to them:

  • cloud_org_path: shows the location of the account in the Organization tree
  • All tags associated with accounts are added as badges

Despite not being listed explicitly, the system.cloud_organization:<cloud_org_id> badge is associated with all accounts in an Organization.

Changes to Credential Management

Because all accounts within the AWS Organization use the same credential configuration, they are considered as "managed" by the organization. This is reflected on the cloud settings page where the option to edit credentials and delete the account are not available.

Auto-badging

As an enhancement to support for provider-based organizations InsightCloudSec includes auto badging capabilities. The purpose of auto-badging is to create a 1:1 map of AWS account-level tags to Badges in InsightCloudSec. This allows Clouds to be scoped to a badge that maps to the account tag.

After the tags and labels are harvested into InsightCloudSec as badges - you cannot delete them in InsightCloudSec - they must be deleted in AWS and the changes will propagate to InsightCloudSec.

Auto-badging takes place in two stages.

StageDescription
Retrieves tags and labels from each account and project and compares them with ResourceTags associated with the cloud account in the InsightCloudSec database.If there are any changes detected, the ResourceTags in the database are overwritten with the values from the account/project.

This means that Cloud Account tags should not be locally modified since any local changes will be overwritten the next time the process runs. Additionally, any local changes that are made to Cloud Account tags are not pushed back up to the cloud provider.
Retrieves all ResourceTags from the local database that are associated with the accounts managed by an organization.For each cloud the list of tags for that cloud is compared with the current list of Badges and for each Key/Value pair of tags:

  • Existing Badges with a Key prefix of system. are skipped.
  • If the corresponding Badge with the Key/Value pair for that cloud does not already exist, it is created.
  • If a tag Value changes, the Badge with the corresponding Key will be updated to that value.
  • If a Badge no longer has a tag with a corresponding Key, it will be deleted.
  • All Badges that have a corresponding tag will have their autogenerated column set to ‘true’ even if they were previously set to ‘false’.