-## 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. |
-
-
- 
+
+
-
-
### 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`
+
-- 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.
-
- 
-
-
**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.
-
-### 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/
+
+
+### 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
diff --git a/ui/components/providers/organizations/org-setup-form.test.tsx b/ui/components/providers/organizations/org-setup-form.test.tsx
index 329d6fe05c..151abfec33 100644
--- a/ui/components/providers/organizations/org-setup-form.test.tsx
+++ b/ui/components/providers/organizations/org-setup-form.test.tsx
@@ -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();
});
});
diff --git a/ui/components/providers/organizations/org-setup-form.tsx b/ui/components/providers/organizations/org-setup-form.tsx
index 35fb13c938..8b2870e998 100644
--- a/ui/components/providers/organizations/org-setup-form.tsx
+++ b/ui/components/providers/organizations/org-setup-form.tsx
@@ -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({
1) Choose the AWS Organizational Unit (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.
@@ -422,7 +422,7 @@ export function OrgSetupForm({ to the whole organization, or an OU ID (starts withou-) to target a specific unit.
-
+
field.onChange(Boolean(checked))
@@ -438,10 +438,10 @@ export function OrgSetupForm({
/>
)}
@@ -454,12 +454,12 @@ export function OrgSetupForm({
-
2) Create the CloudFormation Stack in your{" "} {deploymentAccountName}. 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.
{orgQuickLink ? (
+
field.onChange(Boolean(checked))