docs(aws): deploying prowler iam roles across aws organizations (#8427)

Co-authored-by: Andoni A. <14891798+andoniaf@users.noreply.github.com>

docs/tutorials/aws/organizations.md

@@ -1,5 +1,13 @@
 # AWS Organizations in Prowler
 
+Prowler can integrate with AWS Organizations to manage the visibility and onboarding of accounts centrally.
+
+When trusted access is enabled with the Organization, Prowler can discover accounts as they are created and even automate deployment of the Prowler Scan IAM Role.
+
+> ℹ️ Trusted access can be enabled in the Management Account from the AWS Console under **AWS Organizations → Settings → Trusted access for AWS CloudFormation StackSets**.
+
+When not using StackSets or Prowler and only needing to scan AWS Organization accounts using the CLI, it is possible to assume a role in each account manually or automate that logic with custom scripts.
+
 ## Retrieving AWS Account Details
 
 If AWS Organizations is enabled, Prowler can fetch detailed account information during scans, including:
@@ -33,7 +41,7 @@ Prowler will scan the AWS account and get the account details from AWS Organizat
 
 ### Handling JSON Output
 
-In Prowler’s JSON output, tags are encoded in Base64 to prevent formatting errors in CSV or JSON outputs. This ensures compatibility when exporting findings.
+In Prowler's JSON output, tags are encoded in Base64 to prevent formatting errors in CSV or JSON outputs. This ensures compatibility when exporting findings.
 
 ```json
   "Account Email": "my-prod-account@domain.com",
@@ -51,6 +59,67 @@ The additional fields in CSV header output are as follows:
 - ACCOUNT\_DETAILS\_ORG
 - ACCOUNT\_DETAILS\_TAGS
 
+## Deploying Prowler IAM Roles Across AWS Organizations
+
+When onboarding multiple AWS accounts into Prowler Cloud, it is important to deploy the Prowler Scan IAM Role in each account. The most efficient way to do this across an AWS Organization is by leveraging AWS CloudFormation StackSets, which rolls out infrastructure—like IAM roles—to all accounts centrally from the Management or Delegated Admin account.
+
+When using Infrastructure as Code (IaC), Terraform is recommended to manage this deployment systematically.
+
+### Recommended Approach
+
+- **Use StackSets** from the **Management Account** (or a Delegated Admin/Security Account).
+- **Use Terraform** to orchestrate the deployment.
+- **Use the official CloudFormation template** provided by Prowler.
+- Target specific Organizational Units (OUs) or the entire Organization.
+
+???+ note
+    A detailed community article this implementation is based on is available here:
+    [Deploy IAM Roles Across an AWS Organization as Code (Unicrons)](https://unicrons.cloud/en/2024/10/14/deploy-iam-roles-across-an-aws-organization-as-code/)
+    This guide has been adapted with permission and aligned with Prowler’s IAM role requirements.
+
+---
+
+### Step-by-Step Guide Using Terraform
+
+Below is a ready Terraform snippet that deploys the [Prowler Scan IAM Role CloudFormation template](https://github.com/prowler-cloud/prowler/blob/master/permissions/templates/cloudformation/prowler-scan-role.yml) across the AWS Organization using StackSets:
+
+```hcl title="main.tf"
+data "aws_caller_identity" "this" {}
+
+data "aws_organizations_organization" "this" {}
+
+module "prowler-scan-role" {
+  source = "unicrons/organization-iam-role/aws"
+
+  stack_set_name        = "prowler-scan-role"
+  stack_set_description = "Deploy Prowler Scan IAM Role across all organization accounts"
+  template_path         = "${path.root}/prowler-scan-role.yaml"
+
+  template_parameters = {
+    ExternalId = "<< external ID >>"  # Replace with the External ID provided by Prowler Cloud
+  }
+
+  # Specific OU IDs can be specified instead of root
+  organizational_unit_ids = [data.aws_organizations_organization.this.roots[0].id]
+}
+```
+
+#### `prowler-scan-role.yaml`
+
+Download or reference the official CloudFormation template directly from GitHub:
+
+- [prowler-scan-role.yml](https://github.com/prowler-cloud/prowler/blob/master/permissions/templates/cloudformation/prowler-scan-role.yml)
+
+---
+
+### IAM Role: External ID Support
+
+Include the `ExternalId` parameter in the StackSet if required by the organization's Prowler Cloud setup. This ensures secure cross-account access for scanning.
+
+---
+
+When encountering issues during deployment or needing to target specific OUs or environments (e.g., dev/staging/prod), reach out to the Prowler team via [Slack Community](https://prowler.com/slack) or [Support](mailto:support@prowler.com).
+
 ## Extra: Run Prowler across all accounts in AWS Organizations by assuming roles
 
 ### Running Prowler Across All AWS Organization Accounts