Integration

Overview

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

Prerequisites

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

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.
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.
AWS IAM sign-in permissions. If using CloudFormation, 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.
AWS CloudFormation permissions. If using CloudFormation, 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
When using AWS CloudFormation, 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.
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.
Terraform Installation. If using Terraform, ensure it is installed on your local machine. You can download the latest version of Terraform from the official website. Follow the installation instructions specific to your operating system.

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.

Log in to the Upwind Management Console .
Select the + (plus) symbol at the top of the screen and select Connect cloud account.
Choose Amazon Web Services, and from there Connect AWS Organization.

Follow the detailed steps corresponding to your chosen deployment method.

AWS CloudFormation
Terraform

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

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.

Org Wide Configuration
Organizational Role Name	Ensure the parameter is set. The base name which shall be given to the Organization discover role in the management account. This defaults to `UpwindOrganizationServiceRole`.
External ID	Ensure 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.
Account Service Role Name	Ensure the parameter is set. The base name which shall be given to the Account Service Role. This defaults to `UpwindAccountServiceRole`.
Install Account Service Role in Management account	A boolean flag which indicates whether the Account Service Role should be included in the management account. Ensure this option is set as expected.
Role Name Suffix	A short set of random characters, which shall be appended to the end of role names to help reduce collision against previous installs.
CloudScanner Configuration
Orchestrator Account ID	The orchestrator account ID as defined in the Upwind Management Console. Ensure this is set as expected.
Cloud Scanner Administration Role Name	The base name which shall be given to the CloudScanner Administration role in the orchestrator account. This defaults to `UpwindCloudScannerAdministrationRole` and must be provided.
Cloud Scanner Execution Role Name	The base name which shall be given to the Account Service Role. This defaults to `UpwindCloudScannerExecutionRole`.
Upwind Client ID	Ensure the parameter is set with the client ID generated in the previous step. Omit if an administrator account was not selected. note Must be used in conjunction with Upwind Client Secret.
Upwind Client Secret	Ensure the parameter is set with the client secret generated in the previous step. Omit if an administrator account was not selected. note Must be used in conjunction with Upwind Client ID.
Credentials Secret Name Prefix	A prefix given to the name of the secret used to store the Upwind Client ID and Secret. Ensure this is set.
Organizational Unit IDs	Ensure 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 Enabled	Ensure the parameter is set to `true` to enable automatic deployment to accounts that will be added in the future.
Permission Model	Ensure the parameter is set to `SERVICE_MANAGED` to allow AWS CloudFormation to automatically create the necessary IAM roles for StackSet execution on your behalf.
Stack Set Name	Ensure the parameter is set. This is the name that will be given to the Cloudformation StackSet.
Template URL	Ensure the parameter is set. This is URL of the Cloudformation stack which shall be applied to each account. It should not need to be altered from that provided.
Rollback resources on failure	A boolean flag which indicates that upon failure the stack will attempt to rollback all resources including the StackSet. This is off by default, as allows for partial installs in the event of a failure in some accounts, and permits diagnosis of the cause.

info

Please review carefully and adjust as needed to fit your specific environment.

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.

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 CloudScanners 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)
  }
}

Default Module Parameters
`external_id`	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. Ensure the parameter is set for secure cross-account role assumption.
`upwind_org_register_auth_client_id`	Ensure the parameter is set with the `AWSOrganizationConnectionCredentials` client ID generated in the previous step.
`upwind_org_register_auth_secret_value`	Ensure the parameter is set with the `AWSOrganizationConnectionCredentials` client secret generated in the previous step.
`upwind_organization_id`	Ensure the parameter is set to your Upwind Organization ID - begin "`org_`".
`orchestrator_account_id`	Ensure the parameter is set to the account ID that you wish to use as the orchestrator account.
`management_account_id`	Ensure the parameter is set to your AWS Organization management account ID.
`install_roles_in_management_account`	A boolean flag which indicates whether the Account Service Role should be included in the management account. Ensure this option is set as expected.
`role_name_suffix`	A short set of random characters, which shall be appended to the end of role names to help reduce collision against previous installs.
`upwind_cloudscanner_auth_client_id`	Ensure the parameter is set with the `AWSScannersReportingCredentials` client ID generated in the previous step. Provide this if you are not providing the client credentials through an AWS Secrets Manager secret . Omit if an administrator account was not selected. note Must be used in conjunction with Upwind Client Secret.
`upwind_cloudscanner_auth_secret_value`	Ensure the parameter is set with the `AWSScannersReportingCredentials` client secret generated in the previous step. Provide this if you are not providing the client credentials through an AWS Secrets Manager secret . Omit if an administrator account was not selected. note Must be used in conjunction with Upwind Client ID.

tip

A number of additional parameters can be set on the module, including those which allow the default role names etc. to be altered, and for the AWSScannersReportingCredentials to be injected using a Secret Manager ARN. Please refer to the Terraform module for more details.

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.

Resource
Organization Discovery role	This role grants Upwind permissions to discover the accounts in the AWS Organization, and is created in the management account. Once this role is created, the Terraform module automatically registers the ARN for this role initiating the Organization and account discovery process within the Upwind SaaS.
Account Service role	This role grants Upwind permissions to perform auditing in each account and is created in all accounts - except for the management account if the option not to install the roles has been set. If an Orchestrator account ID has been set, in that account the Account Service role will be created so that Upwind can auto-provision CloudScanners.
CloudScanner Administration role	This role is created in the Orchestrator account if configured. It grants the permissions needed by the CloudScanner to perform its necessary tasks.
CloudScanner Execution role	This role is created in the same accounts as the Account Service role, if an Orchestrator account is configured. It grants permissions to allow the CloudScanner to access scannable targets in the remaining accounts. It is not necessary in the Orchestrator account.
CloudScanner secret	Created in the Orchestrator account, if configured, this secret stores the CloudScanner authentication credentials.

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

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.

Overview​

Prerequisites​

Integration steps​

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

Step 1.1: Provide the parameters to identify your AWS Organization​

Designate an Orchestrator Account​

Step 1.2: Generate Credentials for Upwind​

Step 2: Create the required IAM roles​

Step 2.1: Log in to your AWS Management Account​

Step 2.2: Create cross-account IAM roles​

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

Step 3: Define Account Scope​

Step 1.1: Provide the parameters to identify your AWS Organization​

Designate an Orchestrator Account​

Step 1.2: Generate Credentials for Upwind​

Step 2: Create the required IAM roles​

Step 2.1: Assign the required AWS IAM roles​

Step 2.2: Terraform apply​

Step 3: Define Account Scope​

Overview

Prerequisites

Integration steps

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

Step 1.1: Provide the parameters to identify your AWS Organization

Designate an Orchestrator Account

Step 1.2: Generate Credentials for Upwind

Step 2: Create the required IAM roles

Step 2.1: Log in to your AWS Management Account

Step 2.2: Create cross-account IAM roles

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

Step 3: Define Account Scope

Step 1.1: Provide the parameters to identify your AWS Organization

Designate an Orchestrator Account

Step 1.2: Generate Credentials for Upwind

Step 2: Create the required IAM roles

Step 2.1: Assign the required AWS IAM roles

Step 2.2: Terraform apply

Step 3: Define Account Scope