Integration

Overview

This article outlines the steps to integrate your AWS Organization and its member accounts with Upwind.

Migrating from Legacy Onboarding

Already an Upwind customer using the legacy onboarding flow? If you're interested in migrating to the new organizational onboarding experience, you can skip ahead to the relevant article, Migration.

Integration steps

Summary

The integration of the AWS Organization consists of three steps:

• Step 1: Selecting the AWS Organization and an Orchestrator account.
• Step 2: Creating the Roles and permissions in selected accounts.
• Step 3: Defining which accounts you want Upwind to scan.

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, and from there Connect AWS Organization.

4. Follow the detailed steps corresponding to your chosen deployment method.

   AWS CloudFormation

   When using CloudFormation, you will deploy a CloudFormation Stack which uses a StackSet to create the necessary permissions in all of the accounts within the AWS Organization. Optionally, it will deploy the same stack in the management account if desired.

   Step 1: Onboard your AWS Organization and designate an Orchestrator Account

   In this step, you'll provide basic information to allow Upwind to identify and connect to your AWS Organization.

   Step 1.1: Provide the parameters to identify your AWS Organization

   • Sign in to the AWS Management Console of your management account.
   • Navigate to Organizations → Organize accounts.
   • Copy your Root ID – this is the unique identifier for your root organizational unit and typically begins with r-.
   • Paste the Root ID into the field labeled Enter AWS Root ID.

   Designate an Orchestrator Account

   • Enter the AWS Account ID you want to use as the Orchestrator Account. This account will be responsible for creating and managing the scanning resources on behalf of your organization. The orchestrator should have sufficient permissions to assume roles across your accounts and initiate scans.

     note

     The orchestrator account must belong to the same AWS Organization and have permissions to assume roles in the other accounts. This does not have to be the management account.

     Step 1.2: Generate Credentials for Upwind

   Once your organization and orchestrator account are defined, you will generate the credentials required for authentication.

   • Click Generate new client credentials to create a unique credential set for Upwind.
   • These credentials are used by the orchestrator account to interact with the Upwind Authorization Service and APIs securely.
   • You can optionally customize the name of the credentials under the AWSOrganizationConnectionCredentials label.

   These credentials will enable secure communication and reporting between your AWS environment and the Upwind platform.

   Step 2: Create the required IAM roles

   In this step, you will connect to your AWS management account to apply the CloudFormation which will create the roles. Upwind requires cross-account access to scan and protect all accounts under your AWS Organization. This step ensures that the correct IAM roles are provisioned.

   Step 2.1: Log in to your AWS Management Account

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

   info

   Make sure you are logged into the AWS Management Account of your organization and have selected the region where you intend to deploy the CloudFormation stacks.

   Step 2.2: Create cross-account IAM roles

   • Deploy the Upwind CloudFormation stack to automatically create the IAM roles needed for scanning and orchestration across your organization.

   • Use the toggle to choose whether to include your AWS Management Account in the onboarding process. When enabled, the CloudFormation template will deploy the necessary IAM roles to the management account, allowing Upwind to scan and monitor it as part of your organization.

     note

     All member accounts in your AWS Organization will be connected to Upwind by default. Including the management account is recommended for full visibility. If you prefer to exclude it, simply disable the toggle before proceeding.

   • Click the Run the AWS CloudFormation template link to open a pre-configured CloudFormation Quick Create Stack in a new browser tab. There is no need to manually fill in any of the parameters- all fields are automatically pre-populated based on the information you entered in the previous steps.

     If you'd like to override any of the default values, you may do so on the stack creation page. The following section provides a detailed explanation of each parameter.

     info

     Please review carefully and adjust as needed to fit your specific environment. Variables are explained under Glossary.

     • Check the Capabilities section and acknowledge that the template may create IAM resources.
     • Click Create stack and wait for the stack to complete. For an AWS Organization with a few hundred accounts, this can take several minutes to complete.

   Step 2.3: Enter the required Role ARN from your CloudFormation stack

   • Once complete, retrieve the ARN of the Organization discovery from from the AWS Console. It can either be retrieved from the resource or output tabs of the CloudFormation Stack just installed.
   • Enter the ARN in to the Upwind Management Console, and Click Validate to ensure that Upwind can securely access your AWS Organization.

   Step 3: Define Account Scope

   The final step of the onboarding process allows you to define the scope for each AWS account you've just connected — as well as for any new accounts that may be created in the future under your AWS Organization.

   • This view displays your AWS Organization structure and all linked accounts, allowing you to choose which accounts should be audited using Cloud APIs or scanned using Upwind Cloud Scanners.

     • Enable Cloud API to grant Upwind access to read metadata and perform auditing across the account.

     • Enable Cloud Scanner to deploy the Upwind Cloud Scanner within the selected account.

       Scope Dependency

       Cloud Scanner scopes are dependent on the Cloud API scope. If you enable the Cloud Scanner scope, the Cloud API scope must also be enabled.

   • Enable Auto-Connect for New Accounts – when enabled, all newly created accounts under the organization will be automatically connected to Upwind. These accounts will be granted Cloud API access and will be scanned by the Cloud Scanner by default, ensuring continuous protection without additional setup.

   • Finally, Click Save, before continuing to Explore the Upwind Management Console or navigating to the Onboarding Centre.

   You're now fully connected to Upwind and protected across the selected AWS accounts.

   Terraform

   The Upwind AWS Organization Terraform module can be used to connect multiple accounts within the same AWS Organization to Upwind.

   note

   The Terraform module does not attempt to manage or interact with multiple accounts within the AWS Organization, but instead instead takes a more simplistic approach of being a module which can be applied to multiple accounts creating the resources necessary for those accounts. It is assumed that the module will be used in other IaC tools capable of scaling more favorably across multiple accounts, and can be more readily integrated by your engineers.

   Step 1.1: Provide the parameters to identify your AWS Organization

   • Sign in to the AWS Management Console of your management account.
   • Navigate to Organizations → Organize accounts.
   • Copy your AWS Management Account ID and paste it into the field labeled Enter AWS Management Account ID.

   Designate an Orchestrator Account

   • Enter the AWS Account ID you want to use as the Orchestrator Account. This account will be responsible for creating and managing the scanning resources on behalf of your organization. The orchestrator should have sufficient permissions to assume roles across your accounts and initiate scans.

     note

     The orchestrator account must belong to the same AWS Organization and have permissions to assume roles in the other accounts. This does not have to be the management account.

   Step 1.2: Generate Credentials for Upwind

   In this step, you will generate the client credentials that allow the Upwind Orchestrator Account to authenticate with the Upwind Authorization Service and interact with Upwind APIs. These credentials are required to connect your AWS Organization to Upwind and enable secure reporting and scanning.

   
   

   You will generate two sets of credentials:

   • AWSOrgConnectionCredentials - used to authenticate and identify accounts within your AWS Organization. These credentials are essential for allowing Upwind to discover, connect, and onboard your AWS accounts.
   • AWSScannersReportingCredentials - used to securely report scan results from your AWS accounts back to Upwind. They enable continuous visibility by allowing Upwind to receive findings, metadata, and status updates from your scanned resources.

   Click Generate new client credentials to create both sets of credentials. Once generated, they will be used in later steps to complete the onboarding process.

   Step 2: Create the required IAM roles

   In this step, you'll use the provided Terraform module to provision the required IAM roles that enable Upwind to access and scan all accounts in your AWS Organization.

   
   

   By applying this module, you allow Upwind to automatically deploy the Cloud Scanner infrastructure — including necessary IAM roles and compute components — ensuring full and continuous visibility across your environment.

   note

   All required variables have already been injected into the Terraform module – no manual input is needed.

   Step 2.1: Assign the required AWS IAM roles

   • Before proceeding, review all configuration settings and parameters to ensure they are tailored to your AWS environment.

   • Create a new directory for your Terraform project and navigate to it in your terminal.

   • Inside the project directory, create a new file named main.tf to hold the Terraform configuration.

   • Copy the code snippet from the Terraform setup section and paste it into main.tf.

     main.tf

     provider "aws" {
       region = "us-east-1"
     }
     
     module "upwind_aws_org_onboarding" {
       source = "https://get.upwind.io/terraform/modules/aws-org-onboarding/aws-org-onboarding-1.1.0.tar.gz"
     
       # The external id - added to the trusted identity of the roles which can be assumed
       # by Upwind.
       external_id                           = "5C66DE9B-BC94-4163-8CAC-25F09559478E"
     
       upwind_org_register_auth_client_id    = "<CLIENT ID>"
       upwind_org_register_auth_secret_value = "<SECRET>"
       upwind_organization_id                = "org_abcdef123456"
     
       # The orchestrator account - extra privileges will be assigned to the roles in this account, which is the account in which
       # the Cloud Scanners shall be installed.
       # If this is not specific these CloudScanner related resources will not be created.
       orchestrator_account_id               = "111111111111"
     
       # The management account for the AWS org. The Org discovery role will be created in this account and optionally roles that allow for
       # resource auditing and scanning can be installed too.
       management_account_id                 = "222222222222"
       install_roles_in_management_account   = "true"
     
       # The role name suffix is a random set of characters that will be appended to each resource id to ensure uniqueness.
       role_name_suffix                      = "pxjtg8wo"
     
       # The credentials for Upwind service
       upwind_cloudscanner_auth_client_id    = "<SCANNER CLIENT ID>"
       upwind_cloudscanner_auth_secret_value = "<SCANNER SECRET>"
     
       # Output the ARN of the organization discovery role
       output "discovery_arn" {
           value = one(module.upwind_aws_org_onboarding.organization_discovery_role_arn[*])
       }
     
       output "org_registration_response_state" {
           description = "Org role registration response state"
           value       = one(module.upwind_aws_org_onboarding[*].org_registration_response_state)
       }
     }

   Step 2.2: Terraform apply

   The module can be run manually using terraform init && terraform apply, however, the module has been created with the intention of being integrated into an IaC tool, such as Terragrunt, that can be more readily used to deploy the module into multiple accounts within the AWS Organization. Internally the Terraform module conditionally creates the roles in resources as it is applied to each account.

   tip

   During an initial integration, deploying the Terraform in the management account first will allow the process of discovering the roles to begin. At this point it should be possible to view the accounts in the AWS Organization, and set their scopes. As the Terraform module is applied to each of these accounts, they will continue to connect.

   Step 3: Define Account Scope

   The final step of the onboarding process allows you to define the scope for each AWS account you've just connected — as well as for any new accounts that may be created in the future under your AWS Organization.

   • This view displays your AWS Organization structure and all linked accounts, allowing you to choose which accounts should be audited using Cloud APIs or scanned using Upwind Cloud Scanners.

     • Enable Cloud API to grant Upwind access to read metadata and perform auditing across the account.

     • Enable Cloud Scanner to deploy the Upwind Cloud Scanner within the selected account.

       Scope Dependency

       Cloud Scanner scopes are dependent on the Cloud API scope. If you enable the Cloud Scanner scope, the Cloud API scope must also be enabled.

   • Enable Auto-Connect for New Accounts – when enabled, all newly created accounts under the organization will be automatically connected to Upwind. These accounts will be granted Cloud API access and will be scanned by the Cloud Scanner by default, ensuring continuous protection without additional setup.

   • Finally, Click Save, before continuing to Explore the Upwind Management Console or navigating to the Onboarding Centre.

   You're now fully connected to Upwind and protected across the selected AWS accounts.

Need Help?​

For additional help with settings, please contact us through one of the following methods:

• Access 24/7 live chat support directly in the Upwind Management Console .
• Reach out to us anytime via email at support@upwind.io.
• Collaborate with us by starting a shared Slack channel.