Skip to main content

Integration

New Onboarding Experience

This article outlines the new onboarding experience that is being gradually rolled out. Note that the current process will soon be deprecated. For details, refer to the existing procedure documentation.

Overview​

This article provides instructions for integrating an AWS organization and its accounts with Upwind.

Prerequisites​

To successfully integrate your AWS organization with Upwind, ensure the following prerequisites are met:

  1. Existing AWS organization. Ensure you have an existing AWS environment with AWS Organizations enabled. If you need to create one, refer to the Getting started with AWS Organizations user guide.

  2. Access to the AWS management account. Ensure you have access to your AWS management account, as this is necessary for configuring and managing the integration with Upwind.

  3. AWS IAM sign-in permissions. Ensure the IAM principal entity (user, role, or group) you use to sign into the management account has the necessary permissions to deploy with AWS CloudFormation StackSets.

  4. AWS CloudFormation permissions. Ensure that the IAM principal entity (user, role, or group) you use to sign into the management account has the necessary permissions to create and manage resources with AWS CloudFormation, including deploying StackSets.

    info

    The integration involves executing a CloudFormation StackSet with service-managed permissions, enabling deployment to all existing and future accounts. This model allows you to deploy stack instances to accounts managed by AWS Organizations without the need to manually create the necessary IAM roles, as StackSets automatically creates them on your behalf.

  5. Non-restrictive Service Control Policies (SCPs). Ensure there are no actively applied Service Control Policies (SCPs) that prevent the creation of the necessary IAM roles for integrating with Upwind.

Integration steps​

Summary

The integration of the AWS organization consists of three steps:

  • Step 1: Enabling account discovery across your organization.
  • Step 2: Designating an administrator account for Upwind.
  • Step 3: Enabling secure read only access to all accounts.
  1. Log in to the Upwind Management Console .
  2. Select the + (plus) symbol at the top of the screen and select Connect cloud account.
  3. Choose Amazon Web Services.
  4. Follow the detailed steps corresponding to your chosen deployment method.

Step 1: Enabling account discovery across your organization​

  • Sign in to the AWS Management Console of your management account.

  • In the Upwind Management Console, click on the Run the AWS CloudFormation template quick-create link to open the Quick create stack in the AWS CloudFormation console, automatically populating the necessary parameters with the supplied values.

  • Before proceeding, ensure the configuration settings are tailored to your environment.

    Role Configuration
    External IDEnsure the parameter is set for secure cross-account role assumption. The external ID, generated by Upwind, is unique to each AWS organization to establish a secure trust relationship between Upwind and your AWS environment, providing distinct identification for cross-account access.
    Role NameEnsure the paramater is set to UpwindOrganizationServiceRole.
    warning
    Do not change the role name. Changing it is currently not supported and could disrupt the integration and lead to configuration issues.

  • Review all the settings and parameters.

  • Check the Capabilities section and acknowledge that the template may create IAM resources.

  • Click Create stack and wait for the stack to complete.

  • In the Upwind Management Console, provide the ARN of the role created. Click Validate to ensure that Upwind can securely access your AWS organization.

Step 2: Designating an administrator account for Upwind​

  • Under Select an administrator account for Upwind, choose an account from the list, or create a new one. This account requires elevated permissions to scan all member accounts for misconfigurations, vulnerabilities, malware, and exposed secrets. Granting these permissions enables Upwind to perform automatic infrastructure provisioning and schedule scanning tasks without installing any sensors.

    note

    Enabling cloud scanning operations is optional and can be configured at any time. It is recommended to create a dedicated AWS account and designate it for Upwind to manage scanning infrastructure and tasks efficiently. For more information, please refer to the Creating a member account in an organization with AWS Organizations user guide.

  • Click Generate to create a new client ID and client secret. Provide a name and click Generate again. If you already have Sensor credentials, you may skip this step and select existing credentials from the list.

    Important

    The credentials can be viewed only once; if you choose to use existing credentials from the list, you must provide the client secret.

Step 3: Enabling secure read only access to all accounts​

  • Sign in to the AWS Management Console of your management account.

    Step 3.1: Member accounts​

    • In the Upwind Management Console, under Create cross-account IAM roles, click on the Run the AWS CloudFormation template quick-create link to open the Quick create stack in the AWS CloudFormation console, automatically populating the necessary parameters with the supplied values.

    • Before proceeding, ensure the configuration settings are tailored to your environment.

      Role Configuration
      External IDEnsure the parameter is set for secure cross-account role assumption. The external ID, generated by Upwind, is unique to each AWS organization to establish a secure trust relationship between Upwind and your AWS environment, providing distinct identification for cross-account access.
      Administrator Account IDEnsure the parameter is set with the correct identifier for the account designated as the administrator account for Upwind.

      Leave empty if an administrator account was not selected.
      Account Service Role NameEnsure the paramater is set to UpwindAccountServiceRole.
      warning
      Do not change the role name. Changing it is currently not supported and could disrupt the integration and lead to configuration issues.
      Cloud Scanner Administration Role NameEnsure the paramater is set to UpwindCloudScannerAdministrationRole.
      warning
      Do not change the role name. Changing it is currently not supported and could disrupt the integration and lead to configuration issues.
      Cloud Scanner Execution Role NameEnsure the paramater is set to UpwindCloudScannerExecutionRole.
      warning
      Do not change the role name. Changing it is currently not supported and could disrupt the integration and lead to configuration issues.
      Credentials Configuration
      Upwind Client IDEnsure the parameter is set with the client ID generated in the previous step. Provide this if you are not providing the client credentials through an AWS Secrets Manager secret .

      Leave empty if an administrator account was not selected.
      note
      Must be used in conjunction with Upwind Client Secret.
      Upwind Client SecretEnsure the parameter is set with the client secret generated in the previous step. Provide this if you are not providing the client credentials through an AWS Secrets Manager secret .

      Leave empty if an administrator account was not selected.
      note
      Must be used in conjunction with Upwind Client ID.
      Credentials Secret ARNEnsure the parameter is set with the valid Amazon Resource Name (ARN) of an AWS Secrets Manager secret containing the client credentials generated in the previous step, formatted as a JSON string. Provide this if you are not providing the client credentials directly.

      Leave empty if an administrator account was not selected.
      note
      Must be used in conjunction with Credentials KMS Key ARN.
      Credentials KMS Key ARNEnsure the parameter is set with the valid Amazon Resource Name (ARN) of an AWS KMS key used to encrypt the AWS Secrets Manager secret. Provide this if you are not providing the client credentials directly.

      Leave empty if an administrator account was not selected.
      note
      Must be used in conjunction with Credentials Secret ARN.
      Deployment Configuration
      Organizational Unit IDsEnsure the parameter is set with either the unique identifier for the root (formatted as r- followed by 4 to 32 lowercase letters or digits), or a comma-separated list of organizational unit (OU) IDs to define deployment targets.

      Specifying the root identifier ensures the necessary IAM roles will be created on all member accounts, excluding the management account (see next step).

      Alternatively, switch to the self-managed permission model to target specific accounts by listing their identifiers. Please note that this model does not support automatic deployment and requires manual creation of the necessary IAM roles for AWS CloudFormation.

      For more information, please refer to the Grant self-managed permissions user guide.
      Auto Deployment EnabledEnsure the parameter is set to true to enable automatic deployment to accounts that will be added in the future.
      Permission ModelEnsure the parameter is set to SERVICE_MANAGED to allow AWS CloudFormation to automatically create the necessary IAM roles for StackSet execution on your behalf.

    • Review all the settings and parameters.

    • Check the Capabilities section and acknowledge that the template may create IAM resources.

    • Click Create stack and wait for the stack to complete.

    Step 3.1: Management account (optional)​

    note

    This step is optional but necessary for connecting the organization management account to Upwind because AWS CloudFormation StackSets with service-managed permissions do not deploy stack instances to this account, even if it is part of your organization or an OU within it. For more information, please refer to the DeploymentTargets API reference.

    • In the Upwind Management Console, under Create cross-account IAM role in the management account (optional), click on the Run the AWS CloudFormation template quick-create link to open the Quick create stack in the AWS CloudFormation console, automatically populating the necessary parameters with the supplied values.

    • Before proceeding, ensure the configuration settings are tailored to your environment.

      Role Configuration
      External IDEnsure the parameter is set for secure cross-account role assumption. The external ID, generated by Upwind, is unique to each AWS organization to establish a secure trust relationship between Upwind and your AWS environment, providing distinct identification for cross-account access.
      Administrator Account IDEnsure the parameter is set with the correct identifier for the account designated as the administrator account for Upwind.

      Leave empty if an administrator account was not selected.
      Account Service Role NameEnsure the paramater is set to UpwindAccountServiceRole.
      warning
      Do not change the role name. Changing it is currently not supported and could disrupt the integration and lead to configuration issues.
      Cloud Scanner Administration Role NameEnsure the paramater is set to UpwindCloudScannerAdministrationRole.
      warning
      Do not change the role name. Changing it is currently not supported and could disrupt the integration and lead to configuration issues.
      Cloud Scanner Execution Role NameEnsure the paramater is set to UpwindCloudScannerExecutionRole.
      warning
      Do not change the role name. Changing it is currently not supported and could disrupt the integration and lead to configuration issues.
      Credentials Configuration
      Upwind Client IDEnsure the parameter is set with the client ID generated in the previous step. Provide this if you are not providing the client credentials through an AWS Secrets Manager secret .

      Leave empty if an administrator account was not selected.
      note
      Must be used in conjunction with Upwind Client Secret.
      Upwind Client SecretEnsure the parameter is set with the client secret generated in the previous step. Provide this if you are not providing the client credentials through an AWS Secrets Manager secret .

      Leave empty if an administrator account was not selected.
      note
      Must be used in conjunction with Upwind Client ID.
      Credentials Secret ARNEnsure the parameter is set with the valid Amazon Resource Name (ARN) of an AWS Secrets Manager secret containing the client credentials generated in the previous step, formatted as a JSON string. Provide this if you are not providing the client credentials directly.

      Leave empty if an administrator account was not selected.
      note
      Must be used in conjunction with Credentials KMS Key ARN.
      Credentials KMS Key ARNEnsure the parameter is set with the valid Amazon Resource Name (ARN) of an AWS KMS key used to encrypt the AWS Secrets Manager secret. Provide this if you are not providing the client credentials directly.

      Leave empty if an administrator account was not selected.
      note
      Must be used in conjunction with Credentials Secret ARN.

    • Review all the settings and parameters.

    • Check the Capabilities section and acknowledge that the template may create IAM resources.

    • Click Create stack and wait for the stack to complete.

  • In the Upwind Management Console, after completing all previous steps, click the Test connectivity button to ensure the integration is functioning correctly.