ben.carrasco/prowler
1
0
Fork 0
mirror of https://github.com/prowler-cloud/prowler.git synced 2026-07-23 20:42:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(ui): improve AWS Organizations wizard and docs (#12034)

Browse Source
This commit is contained in:
Daniel Barranquero
2026-07-17 10:22:12 +02:00
committed by GitHub
parent f5ea116763
commit ccec96ac5f
4 changed files with 210 additions and 345 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/images/organizations/authentication-details.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 330 KiB

After

Width:  |  Height:  |  Size: 432 KiB

docs/user-guide/tutorials/prowler-cloud-aws-organizations.mdx
+193 -328
View File
@@ -8,12 +8,14 @@ import { SubscriptionBanner } from "/snippets/subscription-banner.mdx"
<VersionBadge version="5.19.0" />
Prowler Cloud enables you to onboard all AWS accounts in your Organization through a single guided wizard. Instead of connecting accounts one by one, you can discover every account in your AWS Organization, select the ones you want to monitor, test connectivity, and launch scans — all from the Prowler Cloud UI.
Prowler Cloud onboards every AWS account in your Organization through a single guided wizard. Instead of connecting accounts one by one, you can discover every account in your AWS Organization, select the ones you want to monitor, test connectivity, and launch scans — all from the Prowler Cloud UI.
<SubscriptionBanner>
For CLI-based multi-account scanning, see [AWS Organizations in Prowler CLI](/user-guide/providers/aws/organizations).
</SubscriptionBanner>
To follow this guide you need an active [Prowler Cloud](https://cloud.prowler.com) account and access to your AWS Organization [management account](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html) (or a registered delegated administrator account).
## Overview
### Individual Accounts vs Organizations
@@ -25,225 +27,17 @@ For CLI-based multi-account scanning, see [AWS Organizations in Prowler CLI](/us
### How It Works
Onboarding deploys the **ProwlerScan Identity and Access Management (IAM) role** in your management account and in every member account. The wizard can deploy both from a **single CloudFormation stack** ([Step 4](#step-4-authenticate-with-your-management-account)), or you can deploy them yourself beforehand using Steps 1–2. The onboarding follows this sequence:
<VersionBadge version="5.35.0" />
Onboarding deploys the **ProwlerScan Identity and Access Management (IAM) role** in your management account and in every member account. A **single CloudFormation stack** — launched from the wizard's **Create Stack in Management Account** button ([Step 2](#step-2-authenticate-with-your-management-account)) — creates the management account role **and** a service-managed StackSet that rolls the role out to your member accounts in one operation. Prefer to deploy the roles yourself? See [Deploy the Roles Manually](#deploy-the-roles-manually).
<Frame>
<img src="/images/organizations/onboarding-flow.svg" alt="Onboarding flow: 1. Start the Wizard, 2. Deploy the Roles (single CloudFormation stack), 3. Discover and Connect, 4. Launch Scans" />
</Frame>
## Key Concepts
## Step 1: Start the Organization Wizard
### What Is an External ID?
An **External ID** is a security token that Prowler generates unique to your tenant. When Prowler assumes the IAM role in your AWS account, it presents this External ID to prove its identity.
This prevents the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) — a scenario where an unauthorized party could trick AWS into granting access to your account. By requiring the External ID, only your specific Prowler tenant can assume the role.
You don't need to create the External ID yourself — Prowler generates it automatically and displays it in the wizard for you to copy.
### Two Roles Architecture
Prowler requires **two separate IAM roles** deployed in different places, each with a distinct purpose:
| Role | Where it lives | What it does | How to deploy it |
|------|---------------|--------------|------------------|
| **ProwlerScan** (management account) | Your management (root) account only | Discovers the Organization structure **and** scans the management account. Has additional Organizations discovery permissions. | By the wizard's **single stack** ([Step 4](#step-4-authenticate-with-your-management-account)), or on its own via **Quick Create** link or **manually** in the IAM Console ([Step 1](#step-1-create-the-management-account-role)). Cannot be deployed via StackSet. |
| **ProwlerScan** (member accounts) | Every member account | Scans the account for security findings. | By the wizard's **single stack** ([Step 4](#step-4-authenticate-with-your-management-account)), or on its own via a **CloudFormation StackSet** ([Step 2](#step-2-deploy-the-cloudformation-stackset)). Automated across all accounts. |
<Frame caption="Both roles share the same name `ProwlerScan`. The management account role includes additional Organization discovery permissions.">
<img src="/images/organizations/two-roles-architecture.svg" alt="Two Roles Architecture: ProwlerScan in management account (Quick Create or Manual, discovery + scanning) and ProwlerScan in member accounts (via StackSet, scanning only)" />
</Frame>
<Note>
**Same name, different permissions.** Both roles are named `ProwlerScan` — Prowler expects a consistent role name across all accounts. The management account role has the same scanning permissions as member accounts, plus additional Organizations discovery permissions (see [Step 1](#step-1-create-the-management-account-role) for the full list).
</Note>
### What Is a CloudFormation StackSet?
A [CloudFormation StackSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html) lets you deploy the same CloudFormation template across multiple AWS accounts in a single operation. Prowler uses a StackSet to deploy the **ProwlerScan** IAM role into every member account of your organization, so you don't have to create the role manually in each account.
## Prerequisites
### Prowler Cloud Account
You need an active [Prowler Cloud](https://cloud.prowler.com) account. Each AWS account you connect will count as a provider in your subscription. See [Billing Impact](#billing-impact) for details.
### AWS Organization Enabled
Your AWS environment must have [AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html) enabled. You will need access to the **management account** (or a delegated administrator account) to provide the Organization ID and IAM Role ARN.
## Step 1: Create the Management Account Role
The first role you need to create is the **management account role**. This role allows Prowler to discover your Organization structure — listing accounts, OUs, and hierarchy.
<Warning>
**StackSets do not deploy to the management account.** Organizational CloudFormation StackSets with service-managed permissions only target member accounts — this is an AWS limitation, not a Prowler one. The Prowler wizard works around this by having the **same** stack create the management account role (`DeployLocalRole=true`) alongside the StackSet, so a single deployment covers both. You can also create the management account role on its own via the Quick Create link ([Option A](#option-a-quick-create-link-fastest)) or manually ([Option B](#option-b-create-the-role-manually)).
</Warning>
<Note>
**The role must be named `ProwlerScan`** — the same name as the role deployed to member accounts via StackSet. Prowler expects a consistent role name across all accounts in the Organization. If you use a different name, connection tests and scans will fail for the management account.
</Note>
### Option A: Quick Create Link (Fastest)
The Prowler wizard provides a one-click link that opens the AWS Console with the CloudFormation template pre-configured. This creates a **CloudFormation Stack** (not a StackSet) that deploys the ProwlerScan role with Organizations permissions enabled in your management account.
<Tip>
**[Open Quick Create Stack in AWS Console →](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https%3A%2F%2Fprowler-cloud-public.s3.eu-west-1.amazonaws.com%2Fpermissions%2Ftemplates%2Faws%2Fcloudformation%2Fprowler-scan-role.yml&stackName=Prowler&param_EnableOrganizations=true)**
Opens the CloudFormation Console with the Prowler scan role template and `EnableOrganizations=true` pre-filled. You will need to enter the **ExternalId** parameter manually — copy it from the Prowler wizard ([Step 4](#step-4-authenticate-with-your-management-account)).
</Tip>
1. Click **[Open Quick Create Stack in AWS Console →](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?templateURL=https%3A%2F%2Fprowler-cloud-public.s3.eu-west-1.amazonaws.com%2Fpermissions%2Ftemplates%2Faws%2Fcloudformation%2Fprowler-scan-role.yml&stackName=Prowler&param_EnableOrganizations=true)** or use the **Create Stack in Management Account** button in the Prowler wizard (which also pre-fills the ExternalId).
2. Enter the **ExternalId** parameter if not pre-filled.
3. Check **"I acknowledge that AWS CloudFormation might create IAM resources with custom names"** and click **Create stack**.
4. Wait for the stack to reach **CREATE_COMPLETE** status.
Take note of the **Role ARN** from the stack's **Outputs** tab — you will need it in the wizard.
### Option B: Create the Role Manually
1. Sign in to the [AWS IAM Console](https://console.aws.amazon.com/iam/) in your **management account**.
2. Go to **Roles > Create role** and select **Custom trust policy**.
3. Paste the following trust policy. This allows Prowler Cloud to assume the role using your tenant's External ID (you will get this from the Prowler wizard in [Step 3](#step-3-start-the-organization-wizard)):
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::232136659152:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "<YOUR_EXTERNAL_ID>"
},
"StringLike": {
"aws:PrincipalArn": "arn:aws:iam::232136659152:role/prowler*"
}
}
}
]
}
```
Replace `<YOUR_EXTERNAL_ID>` with the External ID shown in the Prowler wizard.
4. Attach the following AWS managed policies:
- **SecurityAudit**
- **ViewOnlyAccess**
This allows Prowler to also scan the management account for security findings, just like any other account.
5. Create an additional inline policy with the following permissions. These are specific to the management account and allow Prowler to discover your Organization structure:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ProwlerOrganizationDiscovery",
"Effect": "Allow",
"Action": [
"organizations:DescribeAccount",
"organizations:DescribeOrganization",
"organizations:ListAccounts",
"organizations:ListAccountsForParent",
"organizations:ListOrganizationalUnitsForParent",
"organizations:ListRoots",
"organizations:ListTagsForResource"
],
"Resource": "*"
},
{
"Sid": "ProwlerStackSetManagement",
"Effect": "Allow",
"Action": [
"organizations:RegisterDelegatedAdministrator",
"iam:CreateServiceLinkedRole"
],
"Resource": "*"
}
]
}
```
<Tip>
You can optionally restrict the `Resource` field to your specific Organization ARN (e.g., `arn:aws:organizations::123456789012:organization/o-abc123def4`) instead of `"*"` to minimize the blast radius.
</Tip>
6. Name the role **`ProwlerScan`** and click **Create role**. Take note of the **Role ARN** — you will need it in the Prowler wizard.
The ARN follows this format: `arn:aws:iam::<account-id>:role/ProwlerScan`
<Warning>
The role **must** be named `ProwlerScan`. Do not use a different name.
</Warning>
<Note>
If you just created the role, it may take up to **60 seconds** for AWS to propagate it. If you get an error in the Prowler wizard, wait a moment and try again.
</Note>
## Step 2: Deploy the CloudFormation StackSet
This step deploys the **ProwlerScan** role to your member accounts using a CloudFormation StackSet. It is the **manual alternative** to letting the wizard's single stack create the StackSet for you ([Step 4](#step-4-authenticate-with-your-management-account)) — use it if you prefer to create and manage the StackSet yourself.
The StackSet uses **service-managed permissions**, which means AWS Organizations handles the cross-account deployment automatically — you don't need to create execution roles manually in each account. The StackSet deploys the ProwlerScan IAM role in every target member account, enabling Prowler to assume that role for cross-account scanning.
<Note>
**Trusted access required:** CloudFormation StackSets must have trusted access enabled in your management account. Verify this in the AWS Console under **AWS Organizations > Settings > Trusted access for AWS CloudFormation StackSets**.
</Note>
<Note>
**The Prowler wizard now deploys this StackSet for you.** The **Create Stack in Management Account** button ([Step 4](#step-4-authenticate-with-your-management-account)) launches a single CloudFormation Stack that creates the management account role **and** a service-managed StackSet for your member accounts (`DeployStackSet=true`). Use the manual console steps below only if you prefer to create the StackSet yourself.
</Note>
<Tip>
**[Open StackSets Console →](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacksets/create)**
Opens the CloudFormation StackSets creation page directly. You will need to paste the template URL and ExternalId manually.
</Tip>
1. Click the link above or navigate to **CloudFormation > StackSets > Create StackSet** in your management account.
2. Choose **Service-managed permissions**.
3. Select **Amazon S3 URL** as the template source and paste the following URL:
```
https://prowler-cloud-public.s3.eu-west-1.amazonaws.com/permissions/templates/aws/cloudformation/prowler-scan-role.yml
```
4. Set the **ExternalId** parameter to the External ID shown in the Prowler wizard.
5. Choose your deployment targets (entire organization or specific OUs).
6. Select the AWS regions where you want the role deployed.
7. Click **Create StackSet**.
### Verify StackSet Deployment
After deploying, verify that all stack instances completed successfully:
1. In the CloudFormation Console, go to **StackSets** and select your Prowler StackSet.
2. Click the **Stack instances** tab.
3. Confirm that all instances show **Status: CURRENT** and **Stack status: CREATE_COMPLETE**.
Deployment typically takes **2–5 minutes** for medium-sized organizations. Large organizations (500+ accounts) may take longer.
<Note>
**Prefer Terraform?** You can deploy the ProwlerScan role using Terraform instead. See the [StackSets deployment guide](/user-guide/providers/aws/organizations#deploying-prowler-iam-roles-across-aws-organizations) for the Terraform module.
</Note>
### Key Considerations
- **Service-managed permissions**: Always select **Service-managed permissions** when creating the StackSet. This lets AWS Organizations manage the deployment automatically across current and future member accounts.
- **Least privilege**: The ProwlerScan role deployed by the StackSet uses `SecurityAudit` and `ViewOnlyAccess` — AWS managed policies that grant read-only access — plus a small set of additional read-only permissions for services not covered by those policies. See the [CloudFormation template](https://prowler-cloud-public.s3.eu-west-1.amazonaws.com/permissions/templates/aws/cloudformation/prowler-scan-role.yml) for the full list. Prowler does not make any changes to your accounts.
- **New accounts**: When you add new accounts to your AWS Organization, the StackSet automatically deploys the ProwlerScan role to them if you targeted the organization root or the relevant OU. Combined with Prowler's 6-hour automatic sync, new accounts are onboarded end-to-end without manual intervention.
- **Management account**: Organizational StackSets **do not deploy to the management account itself**. If you want to scan the management account, you need to create the ProwlerScan role there separately using a regular CloudFormation Stack.
## Step 3: Start the Organization Wizard
Start the Prowler wizard. It walks you through deploying both roles — the management account role and the ProwlerScan role in member accounts — from a single CloudFormation stack ([Step 4](#step-4-authenticate-with-your-management-account)). If you already deployed them beforehand via Steps 1–2, the wizard simply picks up where you left off.
The Prowler wizard walks you through the entire flow: deploying both roles from a single CloudFormation stack, discovering your accounts, testing connectivity, and launching scans.
### Open the Wizard
@@ -280,13 +74,13 @@ Start the Prowler wizard. It walks you through deploying both roles — the mana
Click **Next** to proceed to the authentication phase.
## Step 4: Authenticate with Your Management Account
## Step 2: Authenticate with Your Management Account
The wizard's **Authentication Details** page guides you through three actions: deploying the roles in AWS, entering the deployment account Role ARN, and confirming the deployment. The deployment account is either the management account or, when delegated administrator mode is selected, the delegated administrator account.
The **Authentication Details** page guides you through three actions: deploying the roles in AWS, entering the deployment account Role ARN, and confirming the deployment. The deployment account is either the management account or, when delegated administrator mode is selected, the delegated administrator account.
### External ID
The wizard displays a **Prowler External ID** at the top — auto-generated and unique to your tenant. Click the copy icon to copy it. The External ID is pre-filled into the deployment link, and the single stack applies it to both the management account role and the member-account StackSet.
The wizard displays a **Prowler External ID** at the top — auto-generated and unique to your tenant. Click the copy icon to copy it. The External ID is pre-filled into the deployment link, and the single stack applies it to both the management account role and the member-account StackSet. Learn more in [What Is an External ID?](#what-is-an-external-id).
### Deploy the Roles
@@ -294,12 +88,20 @@ The wizard displays a **Prowler External ID** at the top — auto-generated and
The wizard deploys the deployment account role and the member-account StackSet in a **single** CloudFormation Stack:
<Note>
**Prefer to use your own role?** You do not have to use the Quick Create template. Create the ProwlerScan role yourself — through the IAM Console, Terraform, or your own CloudFormation [(Following this guide)](#deploy-the-roles-manually) — and paste its ARN into the Role ARN field below. The role must use the external ID from the earlier step and include the trust policy and permissions described in [Deploy the Roles Manually](#deploy-the-roles-manually).
</Note>
1. **Organizational Unit or Root ID** — enter the AWS OU (`ou-xxxx-yyyyyyyy`) or organization root (`r-xxxx`) you want to onboard. Prowler rolls the ProwlerScan role out to every member account under this target. Find it in the [AWS Organizations Console](https://console.aws.amazon.com/organizations/); use the **root ID** (`r-`) to cover the entire organization or an **OU ID** (`ou-`) to target a specific unit.
2. *(Optional)* Check **"I'm deploying from a delegated administrator account"** if you launch the stack from a delegated administrator account instead of the management account.
3. **Create Stack in Management Account** — or **Create Stack in Delegated Administrator Account** when delegated administrator mode is selected — opens a Quick Create link that deploys, in a single stack: the ProwlerScan role in the account where you launch the stack (`DeployLocalRole`, with `EnableOrganizations=true`) **and** a service-managed StackSet (`DeployStackSet`) that rolls the role out to your member accounts. The External ID, OU/Root ID, and deployment options are pre-filled.
<Frame>
<img src="/images/organizations/authentication-details.png" alt="Authentication Details form showing External ID, Organizational Unit or Root ID field, delegated administrator checkbox, deployment account stack button, deployment account Role ARN field, and deployment confirmation checkbox" />
</Frame>
<Tip>
**Finding your Organizational Unit or Root ID.** In the [AWS Organizations Console](https://console.aws.amazon.com/organizations/) the root (`r-…`) and OU (`ou-…`) IDs appear in the account tree, or run these from your management account:
@@ -311,17 +113,11 @@ aws organizations list-roots --query 'Roots[0].Id' --output text
aws organizations list-organizational-units-for-parent --parent-id r-xxxx \
--query 'OrganizationalUnits[].{Name:Name,Id:Id}' --output table
```
If you deploy the CloudFormation template manually (instead of via the wizard link), set **`DeployStackSet=true`**, **`DeployLocalRole=true`**, and **`EnableOrganizations=true`**, then put the root/OU ID above into **`AWSOrganizationalUnitId`** (required whenever `DeployStackSet=true`). Leave **`DeployFromDelegatedAdmin=false`** unless you launch the stack from a delegated administrator account.
</Tip>
<Frame>
<img src="/images/organizations/authentication-details.png" alt="Authentication Details form showing External ID, Organizational Unit or Root ID field, delegated administrator checkbox, deployment account stack button, deployment account Role ARN field, and deployment confirmation checkbox" />
</Frame>
### Enter the Deployment Account Role ARN
Paste the **Role ARN** created by the single stack above into the **Management Account Role ARN** field or, when delegated administrator mode is selected, the **Delegated Administrator Account Role ARN** field. If you deployed the management account role beforehand, use the role created in [Step 1](#step-1-create-the-management-account-role).
Paste the **Role ARN** created by the stack above into the **Management Account Role ARN** field or, when delegated administrator mode is selected, the **Delegated Administrator Account Role ARN** field.
The ARN follows this format:
```
@@ -334,6 +130,10 @@ For example: `arn:aws:iam::123456789012:role/ProwlerScan`
<img src="/images/organizations/role-arn-field.png" alt="Deployment account Role ARN field in the Authentication Details form" />
</Frame>
<Note>
It may take up to **60 seconds** for AWS to generate the IAM Role ARN after the stack completes. If the wizard reports an error, wait a moment and try again.
</Note>
### Confirm and Discover
1. Check the box: **"The Stack has been successfully deployed in AWS"**.
@@ -344,7 +144,7 @@ Here's what happens behind the scenes:
- An asynchronous discovery is triggered to query your AWS Organization structure.
- You will see a **"Gathering AWS Accounts..."** spinner — this typically takes **30 seconds to 2 minutes** depending on your organization size.
## Step 5: Select Accounts to Scan
## Step 3: Select Accounts to Scan
### Understanding the Tree View
@@ -355,6 +155,7 @@ Once discovery completes, the wizard displays a **hierarchical tree view** of yo
</Frame>
- The tree supports up to **5 levels of nesting** (Root > OUs > Sub-OUs > Accounts).
- If you deployed the stack for just one OU, that OU will be preselected in the tree.
- **Selecting an OU** automatically selects all accounts within it.
- **Individual overrides**: deselect specific accounts even if the parent OU is selected.
- The header shows **"X of Y accounts selected"** to track your selection.
@@ -371,14 +172,12 @@ Only **ACTIVE** accounts can be selected for scanning:
| **CLOSED** | No | Account has been closed. |
<Note>
**Your existing data is safe.** If an AWS account is already connected to Prowler as an individual provider, it will appear in the tree with a checkmark indicator.
**Your existing data is safe.** If an AWS account is already connected to Prowler as an individual provider, it appears in the tree with a checkmark indicator.
When you proceed:
- The existing provider is **linked** to the organization — it is **not** duplicated.
- All your **historical scan data and findings are preserved** — nothing is overwritten.
- There is **no additional billing** — the existing provider is reused.
This is completely safe. You are simply associating the account with the organization for easier management.
</Note>
### Custom Aliases
@@ -387,14 +186,9 @@ You can edit the display name for each account before connecting. This alias is
### Blocked Accounts
Some accounts may appear as **blocked** (grayed out, not selectable). This happens when:
- The account is **already linked to a different organization** in Prowler (`linked_to_other_organization`).
Some accounts may appear as **blocked** (grayed out, not selectable) when the account is **already linked to a different organization** in Prowler (`linked_to_other_organization`). Hover over the blocked account to see the specific reason.
Hover over the blocked account to see the specific reason.
## Step 6: Test Connections
### How Connection Testing Works
## Step 4: Test Connections
Click **Test Connections** to verify that Prowler can assume the **ProwlerScan** role in each selected member account.
@@ -402,154 +196,225 @@ Click **Test Connections** to verify that Prowler can assume the **ProwlerScan**
<img src="/images/organizations/test-connections.png" alt="Connection testing in progress with spinners on each account" />
</Frame>
- Each account shows a real-time status indicator:
- **Spinner** — test in progress
- **Green checkmark (✓)** — connection successful
- **Red icon (✗)** — connection failed (hover to see the error)
### All Tests Pass
Each account shows a real-time status indicator:
- **Spinner** — test in progress
- **Green checkmark (✓)** — connection successful
- **Red icon (✗)** — connection failed (hover to see the error)
If every account connects successfully, you automatically advance to the next step.
### Some Tests Fail
### When Some Tests Fail
An error banner appears: **"There was a problem connecting to some accounts."**
You have two options:
An error banner appears: **"There was a problem connecting to some accounts."** You have two options:
**a) Fix and retry:**
1. Go to the AWS Console and verify the StackSet deployed to the failing accounts.
2. Check that the External ID in the StackSet matches the one shown in Prowler.
3. Return to Prowler and click **Test Connections** — only the **failed accounts are re-tested** (smart retry). Accounts that already passed are not tested again.
<Frame>
<img src="/images/organizations/test-connections-button.png" alt="Test Connections button" />
</Frame>
**b) Skip and continue:**
Click **Skip Connection Validation** to proceed with only the accounts that connected successfully. The failed accounts will not be scanned.
Click **Skip Connection Validation** to proceed with only the accounts that connected successfully. The failed accounts will not be scanned. This option is only available when at least one account connected successfully.
<Frame>
<img src="/images/organizations/connection-failures-skip.png" alt="Connection test results showing failed accounts with error banner and Skip Connection Validation button" />
</Frame>
<Note>
**Skip Connection Validation** is only available when at least one account connected successfully.
</Note>
If **no accounts** connected successfully, you cannot proceed. Fix the underlying connection issues — see [Troubleshooting](#troubleshooting) — and retry before launching scans.
### All Tests Fail
If **no accounts** connected successfully, you cannot proceed:
> *"No accounts connected successfully. Fix the connection errors and retry before launching scans."*
You must fix the underlying connection issues before continuing. See [Updating Credentials](#updating-credentials) below.
### Updating Credentials
If connection tests fail, here's how to fix common issues:
1. Open the [CloudFormation Console](https://console.aws.amazon.com/cloudformation/) and check that your StackSet instances show **CREATE_COMPLETE** for the failing accounts. If not, update the StackSet to include the missing OUs.
2. Compare the **ExternalId** parameter in your StackSet with the External ID displayed in the Prowler wizard. They must match exactly.
3. After fixing the issue in AWS, return to Prowler and click **Test Connections**. Only the previously failed accounts will be re-tested.
## Step 7: Launch Scans
### Choose Scan Schedule
## Step 5: Launch Scans
The Organizations wizard uses the same schedule controls described in [Scan Scheduling](/user-guide/tutorials/prowler-scan-scheduling#schedule-options).
### Launch
Click **Save**, **Save and launch scan**, or **Launch scan**, depending on the selected schedule option. A toast notification confirms whether the schedule was saved, scans were launched, or both. The toast includes a link to the **Scans** page. Prowler redirects to the **Providers** page.
Scans are only launched for accounts that are accessible (passed connection testing) and were selected.
Click **Save**, **Save and launch scan**, or **Launch scan**, depending on the selected schedule option. A toast notification confirms whether the schedule was saved, scans were launched, or both, and includes a link to the **Scans** page. Prowler then redirects to the **Providers** page. Scans launch only for accounts that passed connection testing and were selected.
<Frame>
<img src="/images/organizations/launch-scan.png" alt="Launch Scan step showing Accounts Connected confirmation, scan schedule selector, and Launch scan button" />
</Frame>
### What Happens Next
After launching:
- Scans appear in the **Scans** page as they start and complete.
- Results populate the **Overview** and **Findings** pages.
- Prowler runs an **automatic sync every 6 hours** to detect new accounts added to your Organization or accounts that have been removed. New accounts are onboarded automatically based on the parent OU configuration.
- Prowler runs an **automatic sync every 6 hours** to detect accounts added to or removed from your Organization. New accounts under the targeted OU or root are onboarded automatically.
## Billing Impact
Each AWS account you connect through the Organizations wizard counts as one **provider** in your Prowler Cloud subscription.
- **Already-connected accounts**: if an account was already linked as a provider, adding it to the organization does **not** incur additional billing. The existing provider is reused.
- **Large organizations**: connecting a 500-account organization will result in up to 500 providers on your subscription. Review your plan limits before proceeding.
- **Large organizations**: connecting a 500-account organization results in up to 500 providers on your subscription. Review your plan limits before proceeding.
- **Deleted providers**: if you later remove an account, the deleted provider no longer counts toward your subscription.
For pricing details, see [Prowler Cloud Pricing](https://prowler.com/pricing).
## Troubleshooting
### Invalid AWS Organization ID
### Only Some Accounts Connect
*"Must be a valid AWS Organization ID"*
Discovery succeeds and the tree view appears, but only one account — or a handful — passes the connection test. This almost always means the ProwlerScan role reached the deployment account but not every member account.
- Verify the Organization ID format: `o-` followed by 10–32 lowercase alphanumeric characters (e.g., `o-abc123def4`)
- Copy it directly from the [AWS Organizations Console](https://console.aws.amazon.com/organizations/) to avoid typos
- **Confirm the StackSet deployed.** Open the [CloudFormation Console](https://console.aws.amazon.com/cloudformation/) in the deployment account, select your Prowler StackSet, open the **Stack instances** tab, and confirm every instance shows **Status: CURRENT** and **Stack status: CREATE_COMPLETE**. Instances still in progress or in a failed state explain the missing accounts.
- **Check the targeted OU or root.** The single stack only rolls the role out to accounts under the **Organizational Unit or Root ID** you entered in [Step 2](#step-2-authenticate-with-your-management-account). Accounts in other OUs are not covered — redeploy targeting the organization root (`r-`) or add the missing OUs.
- **Verify the deployment account.** The role is created only in the account where you launched the stack. If you deployed from a **delegated administrator account**, confirm that account is a **registered delegated administrator** for CloudFormation StackSets (registered through AWS Organizations), not just a regular member account. A regular member account cannot create a service-managed StackSet, so only its own role is created — leaving every other account without the role.
- **Suspended accounts** cannot be scanned. Deselect them and proceed.
### Invalid IAM Role ARN
### No Accounts Connect
*"Must be a valid IAM Role ARN"*
No account passes the connection test.
- Verify the ARN format: `arn:aws:iam::<12-digit-account-id>:role/<role-name>`
- Copy the ARN directly from the [IAM Console](https://console.aws.amazon.com/iam/) in your management account
- **External ID mismatch.** Compare the **ExternalId** parameter in your StackSet with the External ID shown in the Prowler wizard. They must match exactly.
- **StackSet not deployed.** Confirm the StackSet exists and its instances reached **CREATE_COMPLETE**. If you deployed the roles manually, verify [trusted access for CloudFormation StackSets](#member-account-role-stackset) is enabled.
- **IP-based policies.** If your accounts restrict access by IP, allow the [Prowler Cloud egress IPs](/security/networking).
### Authentication Failed
### Authentication Fails or Times Out
*"Authentication failed. Please verify the StackSet deployment and Role ARN"*
*"Authentication failed. Please verify the StackSet deployment and Role ARN"* or *"Authentication timed out"*
- Verify the management account role exists and was created in [Step 1](#step-1-create-the-management-account-role)
- Confirm the trust policy includes the correct External ID from the wizard
- Check the role has all Organizations discovery permissions listed in [Step 1](#step-1-create-the-management-account-role)
- Double-check the Role ARN format and account ID for typos
- Verify the deployment account role exists and is named exactly `ProwlerScan`.
- Confirm the trust policy includes the correct External ID from the wizard.
- Check the role has the Organizations discovery permissions listed in [Deploy the Roles Manually](#management-account-role).
- Double-check the Role ARN format and account ID for typos.
- Retry — the role can take up to **60 seconds** to propagate, and a second attempt often succeeds. For very large organizations (500+ accounts), allow extra time for discovery.
### Authentication Timed Out
### Invalid Organization ID or Role ARN
*"Authentication timed out"*
*"Must be a valid AWS Organization ID"* or *"Must be a valid IAM Role ARN"*
- Retry the authentication step — the second attempt often succeeds
- Check for AWS API rate limiting on the Organizations service
- For very large organizations (500+ accounts), allow extra time for discovery
### Connection Test Fails for All Accounts
No accounts pass the connection test.
- Verify the CloudFormation StackSet was deployed — complete [Step 2](#step-2-deploy-the-cloudformation-stackset) and wait for stack instances to reach **CREATE_COMPLETE**
- Check that the **ExternalId** parameter in the StackSet matches the External ID shown in the Prowler wizard
- If your accounts use IP-based IAM policies, allow [Prowler Cloud egress IPs](/security/networking)
### Connection Test Fails for Some Accounts
Some accounts show a red icon while others pass.
- Expand the StackSet deployment to include the OUs containing the failing accounts
- Suspended accounts cannot be scanned — deselect them and proceed
- Ensure the [STS regional endpoint](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html) is enabled in the account's region
- After fixing, click **Test Connections** — only the failed accounts will be re-tested
### No Accounts Connected Successfully
*"No accounts connected successfully. Fix the connection errors and retry before launching scans."*
- Hover over the red icon on each account to see the specific error
- Fix the underlying issues using the guidance above
- Click **Test Connections** to retry
- Organization ID format: `o-` followed by 10–32 lowercase alphanumeric characters (e.g., `o-abc123def4`).
- Role ARN format: `arn:aws:iam::<12-digit-account-id>:role/ProwlerScan`.
- Copy both directly from the AWS Console to avoid typos.
### Failed to Apply Discovery
*"Failed to apply discovery"*
- Check the `blocked_reasons` field for any blocked accounts
- Retry the operation
- If the error persists, contact [Prowler Support](mailto:support@prowler.com)
- Check the `blocked_reasons` field for any blocked accounts and retry the operation.
- If the error persists, contact [Prowler Support](mailto:support@prowler.com).
## Deploy the Roles Manually
The wizard's **Create Stack** button is the fastest path, but you can create both roles yourself — for example with Terraform or your own CloudFormation — and paste the management account Role ARN into [Step 2](#step-2-authenticate-with-your-management-account). Both roles must be named `ProwlerScan`, since Prowler expects a consistent role name across all accounts.
<Note>
**Prefer Terraform?** You can deploy the ProwlerScan role across the organization with Terraform instead of CloudFormation. See the [StackSets deployment guide](/user-guide/providers/aws/organizations#deploying-prowler-iam-roles-across-aws-organizations) for the module.
</Note>
### Management Account Role
The management account role lets Prowler discover your Organization structure — listing accounts, OUs, and hierarchy — and scan the management account itself. StackSets with service-managed permissions do not deploy to the management account, so this role is always created separately from the member-account StackSet.
1. Sign in to the [AWS IAM Console](https://console.aws.amazon.com/iam/) in your **management account** (or delegated administrator account).
2. Go to **Roles > Create role** and select **Custom trust policy**.
3. Paste the following trust policy, replacing `<YOUR_EXTERNAL_ID>` with the External ID shown in the Prowler wizard:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::232136659152:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "<YOUR_EXTERNAL_ID>"
},
"StringLike": {
"aws:PrincipalArn": "arn:aws:iam::232136659152:role/prowler*"
}
}
}
]
}
```
4. Attach the AWS managed policies **SecurityAudit** and **ViewOnlyAccess** so Prowler can scan the management account for security findings.
5. Add an inline policy with the Organizations discovery permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ProwlerOrganizationDiscovery",
"Effect": "Allow",
"Action": [
"organizations:DescribeAccount",
"organizations:DescribeOrganization",
"organizations:ListAccounts",
"organizations:ListAccountsForParent",
"organizations:ListOrganizationalUnitsForParent",
"organizations:ListRoots",
"organizations:ListTagsForResource"
],
"Resource": "*"
},
{
"Sid": "ProwlerStackSetManagement",
"Effect": "Allow",
"Action": [
"organizations:RegisterDelegatedAdministrator",
"iam:CreateServiceLinkedRole"
],
"Resource": "*"
}
]
}
```
<Tip>
You can restrict the `Resource` field to your specific Organization ARN (e.g., `arn:aws:organizations::123456789012:organization/o-abc123def4`) instead of `"*"` to minimize the blast radius.
</Tip>
6. Name the role **`ProwlerScan`** and click **Create role**. The ARN follows the format `arn:aws:iam::<account-id>:role/ProwlerScan` — paste it into the wizard.
### Member Account Role (StackSet)
Deploy the ProwlerScan role to every member account with a [CloudFormation StackSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html), so you don't create the role manually in each account.
<Note>
**Trusted access required.** CloudFormation StackSets must have trusted access enabled in your management account. Verify this under **AWS Organizations > Settings > Trusted access for AWS CloudFormation StackSets**.
</Note>
1. In your management account, navigate to **CloudFormation > StackSets > Create StackSet** ([open directly](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacksets/create)).
2. Choose **Service-managed permissions** so AWS Organizations deploys the role automatically across current and future member accounts.
3. Select **Amazon S3 URL** as the template source and paste:
```
https://prowler-cloud-public.s3.eu-west-1.amazonaws.com/permissions/templates/aws/cloudformation/prowler-scan-role.yml
```
4. Set the **ExternalId** parameter to the External ID shown in the Prowler wizard.
5. Choose your deployment targets (entire organization or specific OUs) and regions, then click **Create StackSet**.
6. Open the **Stack instances** tab and confirm every instance shows **Status: CURRENT** and **Stack status: CREATE_COMPLETE**. Deployment typically takes **2–5 minutes**; large organizations (500+ accounts) may take longer.
The StackSet role uses read-only access only (`SecurityAudit`, `ViewOnlyAccess`, plus a small set of additional read-only permissions). Prowler makes no changes to your accounts. See the [CloudFormation template](https://prowler-cloud-public.s3.eu-west-1.amazonaws.com/permissions/templates/aws/cloudformation/prowler-scan-role.yml) for the full list. When you add new accounts under the targeted OU or root, the StackSet deploys the role automatically, and Prowler's 6-hour sync onboards them end-to-end.
## Key Concepts
### What Is an External ID?
An **External ID** is a security token that Prowler generates unique to your tenant. When Prowler assumes the IAM role in your AWS account, it presents this External ID to prove its identity.
This prevents the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html) — a scenario where an unauthorized party could trick AWS into granting access to your account. By requiring the External ID, only your specific Prowler tenant can assume the role. Prowler generates it automatically and displays it in the wizard for you to copy.
### Two Roles Architecture
Prowler uses **two IAM roles**, both named `ProwlerScan` but deployed in different places:
| Role | Where it lives | What it does |
|------|---------------|--------------|
| **ProwlerScan** (management account) | Your management (or delegated administrator) account | Discovers the Organization structure **and** scans that account. Includes additional Organizations discovery permissions. |
| **ProwlerScan** (member accounts) | Every member account | Scans the account for security findings. |
Both roles share the name `ProwlerScan` because Prowler expects a consistent role name across all accounts. The single CloudFormation stack in [Step 2](#step-2-authenticate-with-your-management-account) deploys both at once.
<Frame caption="Both roles share the same name `ProwlerScan`. The management account role includes additional Organization discovery permissions.">
<img src="/images/organizations/two-roles-architecture.svg" alt="Two Roles Architecture: ProwlerScan in management account (discovery + scanning) and ProwlerScan in member accounts (via StackSet, scanning only)" />
</Frame>
### What Is a CloudFormation StackSet?
A [CloudFormation StackSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html) deploys the same CloudFormation template across multiple AWS accounts in a single operation. Prowler uses a service-managed StackSet to deploy the **ProwlerScan** IAM role into every member account of your organization, so you don't create the role manually in each account. StackSets do not deploy to the management account, which is why that role is created separately.
## What's Next
ui/components/providers/organizations/org-setup-form.test.tsx
+1 -1
View File
@@ -115,7 +115,7 @@ describe("OrgSetupForm", () => {
expect(params.get("param_DeployFromDelegatedAdmin")).toBe("true");
expect(
screen.getByLabelText("Delegated Administrator Account Role ARN"),
screen.getByLabelText("Delegated Administrator Account IAM Role ARN"),
).toBeInTheDocument();
});
});
ui/components/providers/organizations/org-setup-form.tsx
+16 -16
View File
@@ -41,7 +41,7 @@ const orgSetupSchema = z.object({
roleArn: z
.string()
.trim()
.min(1, "Role ARN is required")
.min(1, "IAM Role ARN is required")
.regex(
/^arn:aws:iam::\d{12}:role\//,
"Must be a valid IAM Role ARN (e.g., arn:aws:iam::123456789012:role/ProwlerScan)",
@@ -400,7 +400,7 @@ export function OrgSetupForm({
<div className="flex flex-col gap-4">
<p className="text-text-neutral-primary text-sm leading-7 font-normal">
1) Choose the AWS <strong>Organizational Unit</strong> (or root)
to deploy to. Prowler creates the role in your deployment
to deploy to. Prowler creates the IAM Role in your deployment
account and rolls it out to every member account under this
target.
</p>
@@ -422,7 +422,7 @@ export function OrgSetupForm({
to the whole organization, or an <strong>OU ID</strong> (starts
with <code>ou-</code>) to target a specific unit.
</p>
<div className="flex items-start gap-4">
<div className="flex items-center gap-3">
<Controller
name="deployFromDelegatedAdmin"
control={control}
@@ -430,7 +430,7 @@ export function OrgSetupForm({
<>
<Checkbox
id="deployFromDelegatedAdmin"
className="mt-0.5"
size="sm"
checked={field.value}
onCheckedChange={(checked) =>
field.onChange(Boolean(checked))
@@ -438,10 +438,10 @@ export function OrgSetupForm({
/>
<label
htmlFor="deployFromDelegatedAdmin"
className="text-text-neutral-tertiary text-xs leading-5 font-normal"
className="text-text-neutral-secondary text-sm leading-5 font-medium"
>
I&apos;m deploying from a delegated administrator
account (not the Organization management account)
I&apos;m deploying from a Delegated Administrator
Account (not the Management Account)
</label>
</>
)}
@@ -454,12 +454,12 @@ export function OrgSetupForm({
<p className="text-text-neutral-primary text-sm leading-7 font-normal">
2) Create the CloudFormation Stack in your{" "}
<strong>{deploymentAccountName}</strong>. It deploys the
ProwlerScan role and a service-managed StackSet that rolls the
role out to your member accounts in one step.
ProwlerScan IAM Role and a service-managed StackSet that rolls
the IAM Role out to your member accounts in one step.
</p>
{orgQuickLink ? (
<Button
variant="outline"
variant="default"
size="xl"
className="w-full justify-start"
asChild
@@ -476,7 +476,7 @@ export function OrgSetupForm({
) : (
<Button
type="button"
variant="outline"
variant="default"
size="xl"
className="w-full justify-start"
disabled
@@ -496,15 +496,15 @@ export function OrgSetupForm({
{/* Step 3: Role ARN + confirm */}
<div className="flex flex-col gap-4">
<p className="text-text-neutral-primary text-sm leading-7 font-normal">
3) Paste the {deploymentAccountName} Role ARN and confirm the
deployment is complete.
3) Paste the {deploymentAccountName} IAM Role ARN and confirm
the deployment is complete.
</p>
</div>
<WizardInputField
control={control}
name="roleArn"
label={`${deploymentAccountLabel} Role ARN`}
label={`${deploymentAccountLabel} IAM Role ARN`}
labelPlacement="outside"
placeholder="e.g. arn:aws:iam::123456789012:role/ProwlerScan"
isRequired={false}
@@ -516,7 +516,7 @@ export function OrgSetupForm({
ARN
</p>
<div className="flex items-start gap-4">
<div className="flex items-center gap-3">
<Controller
name="stackSetDeployed"
control={control}
@@ -524,7 +524,7 @@ export function OrgSetupForm({
<>
<Checkbox
id="stackSetDeployed"
className="mt-0.5"
size="sm"
checked={field.value}
onCheckedChange={(checked) =>
field.onChange(Boolean(checked))