Skip to main content

Deploy Management Role

The first step in multi-account onboarding is deploying a lightweight IAM role in your AWS management account. This role grants Guardian Pro read-only access to your AWS Organisations structure so it can discover your accounts and organisational units.

What the Management Role Does​

The management role provides read-only access to AWS Organisations. It does not grant access to any workloads, data, or resources within your accounts.

Specifically, the role allows Guardian Pro to:

  • List accounts in your organisation
  • Describe organisational units (OUs) and their hierarchy
  • Read organisation metadata (organisation ID, feature set, root ID)
info

The management role has no write permissions. It cannot create, modify, or delete any AWS resources. It exists solely to discover your account structure during onboarding.

Permissions Granted​

The role includes the following AWS permissions:

PermissionPurpose
organizations:ListAccountsEnumerate all accounts in the organisation
organizations:ListAccountsForParentMap accounts to their parent OUs
organizations:DescribeOrganizationRead organisation metadata
organizations:ListOrganizationalUnitsForParentDiscover OU hierarchy
organizations:DescribeOrganizationalUnitRead OU details
organizations:ListRootsIdentify the organisation root

Deploying the Role​

Step 1: Open the Deployment Page​

From the Guardian Pro onboarding wizard, click Deploy Management Role. This opens the deployment page with a pre-configured CloudFormation launch link.

Step 2: Launch the CloudFormation Stack​

Click the Launch Stack button. This opens the AWS CloudFormation console in a new tab with the Guardian Pro management role template pre-loaded.

Important

You must be signed into your AWS management account (the root account of your AWS Organisation) before clicking Launch Stack. Deploying this role in a member account will not work.

Step 3: Review and Create the Stack​

In the CloudFormation console:

  1. Review the stack name -- the default GuardianProManagementRole is recommended
  2. Verify the parameters -- the External ID is pre-filled and unique to your Guardian Pro organisation
  3. Acknowledge IAM resource creation -- check the box confirming CloudFormation will create IAM resources
  4. Click Create Stack

Stack creation typically completes in 60-90 seconds.

Step 4: Verify Deployment​

Return to the Guardian Pro onboarding wizard. Guardian Pro automatically detects when the stack creation completes and advances you to the next step.

If automatic detection does not trigger within 2 minutes, click Verify Deployment to manually check the stack status.

Security: Confused Deputy Protection​

The management role uses AWS's recommended External ID mechanism to prevent confused deputy attacks.

How External ID Works

The External ID is a unique identifier tied to your Guardian Pro organisation. When Guardian Pro assumes the management role, it must present this exact External ID. This ensures that only your Guardian Pro tenant can use the role -- even if another party somehow obtained the role ARN.

The External ID is:

  • Automatically generated during onboarding
  • Unique to your organisation -- no two Guardian Pro tenants share an External ID
  • Embedded in the CloudFormation template -- you do not need to configure it manually
  • Immutable -- it cannot be changed after role creation

For a detailed breakdown of all IAM permissions and security controls, see IAM Permissions Reference.

Troubleshooting​

Stack creation failed​

If the CloudFormation stack fails to create:

  1. Open the CloudFormation console in your AWS management account
  2. Select the failed stack and check the Events tab for error details
  3. Common causes:
    • Insufficient permissions: Ensure you have iam:CreateRole and cloudformation:CreateStack permissions
    • Stack name conflict: A stack with the name GuardianProManagementRole may already exist. Delete the previous stack first or use a different name
    • Service control policy (SCP): An SCP on your management account may restrict IAM role creation
note

If the stack fails, no resources are created in your account. CloudFormation automatically rolls back failed deployments.

Verification not detecting the role​

If Guardian Pro cannot detect the deployed role:

  1. Confirm the stack status is CREATE_COMPLETE in the CloudFormation console
  2. Verify you deployed in the management account, not a member account
  3. Check that the External ID in the stack parameters matches what Guardian Pro expected
  4. Click Verify Deployment to trigger a manual check

Role already exists​

If you previously deployed the management role (for example, during a prior onboarding attempt):

  1. You can reuse the existing role -- Guardian Pro will detect it automatically
  2. If the role has an outdated External ID, delete the existing CloudFormation stack and redeploy

What Happens Next​

Once the management role is verified, Guardian Pro uses it to discover your AWS Organisation structure in the next step. The management role remains in your account for ongoing organisation-level operations, such as detecting newly added accounts.