+
+
+## 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.
+
+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. | **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. | Via **CloudFormation StackSet** ([Step 2](#step-2-deploy-the-cloudformation-stackset)). Automated across all accounts. |
+
+
+ 
+
+
+
+
+
+2. Select **Amazon Web Services** as the provider.
+
+
+ 
+
+
+3. Choose **Add Multiple Accounts With AWS Organizations**.
+
+
+ 
+
+
+### Enter Organization Details
+
+- **Organization ID**: Your AWS Organization identifier, found in the [AWS Organizations Console](https://console.aws.amazon.com/organizations/). It follows the format `o-` followed by 10–32 lowercase alphanumeric characters (e.g., `o-abc123def4`). You can find it in the left sidebar of the AWS Organizations console:
+
+
+ 
+
+- **Name** (optional): A display name for the organization. If left blank, Prowler uses the name stored in AWS.
+
+
+ 
+
+
+Click **Next** to proceed to the authentication phase.
+
+## Step 4: Authenticate with Your Management Account
+
+### Copy the External ID
+
+The wizard displays a **Prowler External ID** — auto-generated and unique to your tenant. Click the copy icon to copy it. If you haven't already configured the trust policy on your management account role ([Step 1](#step-1-create-the-management-account-role)), do so now using this External ID.
+
+
+ 
+
+
+### Enter the Role ARN
+
+Paste the **Role ARN** of the management account role you created in [Step 1](#step-1-create-the-management-account-role) into the **Role ARN** field.
+
+The ARN follows this format:
+```
+arn:aws:iam::
+
+
+### Confirm and Discover
+
+1. Check the box: **"The StackSet has been successfully deployed in AWS"**.
+2. Click **Authenticate**.
+
+Here's what happens behind the scenes:
+- Prowler creates the organization resource and stores your credentials securely.
+- 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.
+
+{/* TODO: screenshot of the Authentication Details form with the spinner */}
+
+## Step 5: Select Accounts to Scan
+
+### Understanding the Tree View
+
+Once discovery completes, the wizard displays a **hierarchical tree view** of your Organization:
+
+
+ 
+
+
+- The tree supports up to **5 levels of nesting** (Root > OUs > Sub-OUs > Accounts).
+- **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.
+
+### Account Statuses
+
+Only **ACTIVE** accounts can be selected for scanning:
+
+| Status | Selectable? | Description |
+|--------|-------------|-------------|
+| **ACTIVE** | Yes | Account is active and operational. |
+| **SUSPENDED** | No | Account is suspended by AWS. |
+| **PENDING_CLOSURE** | No | Account is being closed. |
+| **CLOSED** | No | Account has been closed. |
+
+
+
+
+- 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
+
+If every account connects successfully, you automatically advance to the next step.
+
+### Some Tests Fail
+
+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.
+
+
+ 
+
+
+
+
+
+### What Happens Next
+
+- 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.
+
+{/* TODO: screenshot of the Launch Scan step */}
+
+## 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.
+- **Deleted providers**: if you later remove an account, the deleted provider no longer counts toward your subscription.
+
+For pricing details, see [Prowler Cloud Pricing](/getting-started/products/prowler-cloud-pricing).
+
+## Troubleshooting
+
+### Invalid AWS Organization ID
+
+*"Must be a valid AWS Organization ID"*
+
+- 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
+
+### Invalid IAM Role ARN
+
+*"Must be a valid IAM Role ARN"*
+
+- Verify the ARN format: `arn:aws:iam::<12-digit-account-id>:role/
+
+ );
+ }
-export function LaunchStep() {
return (
-
+
+ Launching scans...
+
-
diff --git a/ui/tests/providers/providers-page.ts b/ui/tests/providers/providers-page.ts
index b4948657b5..117590dc33 100644
--- a/ui/tests/providers/providers-page.ts
+++ b/ui/tests/providers/providers-page.ts
@@ -756,6 +756,9 @@ export class ProvidersPage extends BasePage {
});
if (await button.isVisible().catch(() => false)) {
await button.click();
+ if (actionName === "Check connection") {
+ await this.handleCheckConnectionCompletion();
+ }
if (actionName === "Launch scan") {
await this.handleLaunchScanCompletion();
}
@@ -768,9 +771,9 @@ export class ProvidersPage extends BasePage {
);
}
- private async handleLaunchScanCompletion(): PromiseProvider connected successfully
-- Continue with the action button to go to scans. +
+
);
}
diff --git a/ui/components/providers/wizard/steps/test-connection-step.test.tsx b/ui/components/providers/wizard/steps/test-connection-step.test.tsx
index cd4d2d725f..75d564aa54 100644
--- a/ui/components/providers/wizard/steps/test-connection-step.test.tsx
+++ b/ui/components/providers/wizard/steps/test-connection-step.test.tsx
@@ -1,4 +1,5 @@
import { render, screen, waitFor } from "@testing-library/react";
+import { useEffect } from "react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { useProviderWizardStore } from "@/store/provider-wizard/store";
@@ -6,8 +7,9 @@ import { PROVIDER_WIZARD_MODE } from "@/types/provider-wizard";
import { TestConnectionStep } from "./test-connection-step";
-const { getProviderMock } = vi.hoisted(() => ({
+const { getProviderMock, loadingFromFormMock } = vi.hoisted(() => ({
getProviderMock: vi.fn(),
+ loadingFromFormMock: { current: false },
}));
vi.mock("@/actions/providers", () => ({
@@ -15,7 +17,19 @@ vi.mock("@/actions/providers", () => ({
}));
vi.mock("../../workflow/forms/test-connection-form", () => ({
- TestConnectionForm: () => ,
+ TestConnectionForm: ({
+ onLoadingChange,
+ }: {
+ onLoadingChange?: (isLoading: boolean) => void;
+ }) => {
+ useEffect(() => {
+ if (loadingFromFormMock.current) {
+ onLoadingChange?.(true);
+ }
+ }, [onLoadingChange]);
+
+ return ;
+ },
}));
describe("TestConnectionStep", () => {
@@ -23,6 +37,7 @@ describe("TestConnectionStep", () => {
sessionStorage.clear();
localStorage.clear();
getProviderMock.mockReset();
+ loadingFromFormMock.current = false;
useProviderWizardStore.getState().reset();
});
@@ -64,4 +79,54 @@ describe("TestConnectionStep", () => {
});
expect(useProviderWizardStore.getState().secretId).toBe("secret-1");
});
+
+ it("updates footer action label to checking while connection test is in progress", async () => {
+ // Given
+ loadingFromFormMock.current = true;
+ useProviderWizardStore.setState({
+ providerId: "provider-1",
+ providerType: "gcp",
+ mode: PROVIDER_WIZARD_MODE.ADD,
+ });
+ getProviderMock.mockResolvedValue({
+ data: {
+ id: "provider-1",
+ attributes: {
+ uid: "project-123",
+ provider: "gcp",
+ alias: "Main",
+ connection: { connected: false, last_checked_at: null },
+ scanner_args: {},
+ },
+ relationships: {
+ secret: { data: { type: "provider-secrets", id: "secret-1" } },
+ },
+ },
+ });
+ const onFooterChange = vi.fn();
+
+ // When
+ render(
+
+
+
+ Connection validated!
++ Choose how you want to launch scans for this provider.
+ + {!providerId && ( ++ Provider data is missing. Go back and test the connection again. +
+ )} + +
+
Scan schedule
+ +
-
- );
- }
-
return (
-
-
-
-
-
- - Scan initiated successfully -
-- Redirecting to scans job details... -
-