Skip to main content

Onboarding flow

This article walks through the SaaS onboarding flow for connecting AWS environments to Upwind. With SaaS, Upwind hosts and manages all Cloud Scanner infrastructure in its own AWS organization; you only provision the IAM resources that allow Upwind to access your accounts.

For a higher-level explanation of the SaaS model and how scans run end-to-end, see Overview and Architecture.

Before you start​

Review the Prerequisites and confirm your AWS Organization meets them.

Integration steps​

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

The SaaS onboarding flow is organized into four steps, all completed from the Onboarding center in the Upwind Management Console .

Step 1: Connect your environment​

Step 1.1: Connection setup​

Define your connection parameters and scope. First, choose how much of your AWS environment to connect:

  • Organization: connect the entire AWS Organization, covering every account under it.
  • Organizational Unit/s: connect only the accounts within the organizational units (OUs) you select.
  • Account/s: connect only the specific accounts you select.

Enter the identifiers that allow Upwind to locate your AWS Organization and map its structure during onboarding:

  • Organization ID: a unique identifier assigned by AWS to your organization, used by Upwind to associate connected accounts during onboarding. It can be found in the AWS Management Console under Organizations → Settings. Typically begins with o-.
  • Root ID: the unique identifier of the top-level parent node in your AWS organization's hierarchy, containing all organizational units (OUs) and accounts. Found in the AWS Management Console under Organization → AWS accounts. Typically begins with r-.
Cloud Scanners Setup​

Choose your deployment model. With SaaS Upwind manages the infrastructure on your behalf, while Outpost deploys scanners directly within your own environment. Select SaaS.

To learn more about the SaaS and Outpost models, see AWS deployment models.

  • Designate an Orchestrator Account: choose the account that Upwind will use to assume an IAM role and operate across your connected accounts. An elevated IAM role will be deployed in this account, allowing Upwind to authenticate and perform cross-account operations across your environment. Enter its AWS Account ID.

    warning

    The Orchestrator account must not be deleted. Removing it will disconnect Upwind from the environment.

Deployment method​

Defines how Upwind is deployed into your environment. Select the deployment method that matches your setup - CloudFormation or Terraform - then follow the steps in that tab.

Select CloudFormation, then click Next to continue.

Resumable onboarding

You can revisit Step 1 to change your connection choices and parameters at any point before you run the CloudFormation template and validate the role ARN in Step 3. Once those are complete, the connection is established and these choices can no longer be changed here.

Step 2: Readiness check​

Before starting onboarding, run the script below in your terminal to validate required AWS permissions and configuration. It will highlight missing access so you can resolve issues before proceeding.

The Upwind Management Console generates a snippet pre-populated for your environment. Choose Bash or PowerShell to match your terminal, then copy and run the snippet:

important

Log in to your AWS Management Account via your terminal before running this script.

curl -fsSL https://get.upwind.io/upwindctl.sh | bash
source "$HOME/.upwindctl/env"
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
aws sso login --profile <management-profile>
upwindctl aws onboarding preflight \
  --aws-profile <management-profile> \
  --aws-region us-east-1 \
  --is-saas

Review the script output. A successful run looks similar to the following:

upwindctl aws onboarding preflight --aws-profile <management-profile> --aws-region us-east-1 --is-saas
2026/06/04 12:50:21 Using AWS profile <management-profile>
2026/06/04 12:50:21 Using AWS region us-east-1
2026/06/04 12:50:24 Caller identity: arn:aws:sts::111122223333:assumed-role/AWSReservedSSO_AdministratorAccess/jane.doe@example.com
2026/06/04 12:50:24 Orchestrator account: 111122223333
2026/06/04 12:50:24 Discovering org topology and fetching SCP documents...
2026/06/04 12:50:26 Found 3 accounts across 2 distinct SCP configurations
2026/06/04 12:50:26 Simulating caller identity: arn:aws:iam::111122223333:role/AWSReservedSSO_AdministratorAccess
2026/06/04 12:50:27 Orchestrator simulation complete: 34 actions evaluated, 34 results returned
2026/06/04 12:50:27 Evaluating 2 unique SCP configuration(s) for 2 member account(s)
2026/06/04 12:50:27 Checking EC2 Allowed AMIs setting...
2026/06/04 12:50:27 Checking Allowed AMIs across 18 region(s)

Preflight check - Upwind permission verification

Orchestrator  ✓  111122223333 / arn:aws:iam::111122223333:role/AWSReservedSSO_AdministratorAccess

Member accounts (2/2 compliant):
  ✓ 444455556666     SCP evaluation
  ✓ 777788889999     SCP evaluation

Allowed AMIs  ✓  no blocking AMI restrictions found across 18 region(s)

Overall: PASS

If everything passes, click Next to continue. If the script reports missing access or configuration, resolve the issues and re-run it before proceeding.

tip

For full details on the prerequisites the script verifies, see Prerequisites.

Step 3: Grant permissions​

In this step you configure the scanner capabilities you want enabled and provision the cross-account IAM roles that allow Upwind to access and scan your AWS Organization.

Step 3.1: Set required permissions​

Expand your security coverage by enabling additional scanning capabilities:

  • Data scanning: scan buckets, databases, and file systems to detect sensitive data across your cloud environment.
  • Agentless Kubernetes Discovery & Scanning: discover and scan Kubernetes resources without deploying sensors.
    • Connectivity method: public endpoint access is enabled by default for scanning and discovery. Optionally enable Private access via SSM.
    • Authentication method: choose how Upwind connects to your environment to perform scanning and data collection. Select either EKS Access Setup (default) or Pre-provisioned entry.

Step 3.2: Create cross-account IAM roles​

Provision the IAM roles that enable Upwind Cloud Scanners, deployed and managed by Upwind, to access and scan your accounts. By assigning these roles you allow Upwind to automatically provision Cloud Scanner infrastructure, including essential components like IAM roles and Auto Scaling Groups, ensuring full and continuous scanning coverage across your cloud environment.

  • Use the Include AWS Management Account switch to choose whether the management account itself is onboarded alongside your member accounts. The management account is the root account that owns your AWS Organization, and it often runs its own workloads and stores sensitive configuration. Including it lets Upwind audit and scan those resources too, so enabling this switch is recommended for full visibility across the organization.

  • Click the link to log in to your AWS Management Account.

  • Click Run the AWS CloudFormation template to open a pre-configured CloudFormation Quick Create Stack in a new browser tab. All parameters are pre-populated based on the information you entered in Step 1 - there is no need to manually fill in any parameters.

    note

    The Upwind Client ID, Upwind Client Secret, and Upwind Auth Secret ARN parameters should remain empty in the SaaS deployment model.

  • Review the CloudFormation template, acknowledge that it may create IAM resources, then click Create stack. For large Organizations, this can take several minutes to complete.

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

Once the stack is complete, find the IAM role named OrganizationServiceRoleArn in the output of the CloudFormation stack you just created. Upwind uses this role to identify and list every member account for monitoring and protection.

note

This role is usually created by the UpwindCombinedOrg CloudFormation stack.

Paste the ARN into the Enter role ARN field, then click Validate. Upwind verifies that the role exists, can be assumed, and grants the permissions needed to securely access and list the accounts in your AWS Organization. If validation fails, follow the error shown on screen to resolve the issue, then click Validate again. For details on each validation check, see Role ARN Validation in the glossary.

Step 4: Define 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. Account scopes can be modified later in the organizations and accounts settings.

  • This view displays your AWS Organization structure and all linked accounts and OUs, 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 for the selected account. With SaaS, the scanner itself runs in the Upwind environment; enabling this scope authorizes Upwind to scan the 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 through the SaaS deployment model and protected across the selected AWS accounts.

Next steps​