Skip to main content

​
Deploy Organization Inventory Roles

To enable WatchTower to discover and inventory your AWS Organization’s member accounts, deploy an IAM role in your management or delegated administrator account. Choose the deployment method that best fits your security requirements.

​
Deployment Options

WatchTower production account directly assumes a role in your management account. Simplest and most common deployment.

​
Chained Access

WatchTower assumes a role in an intermediate account you control, which then assumes the target role. Use when security policies require an additional layer.

​
Direct Access Deployment

Best for: Most organizations, quickest setup
1

Launch the CloudFormation Template

Important: Ensure you’re logged into the correct AWS account in your browser before clicking the launch button.
Click the button below to deploy the role in your AWS management account: Launch StackDeploy To: Management Account or Delegated Admin Account (in us-east-1)
2

Configure Parameters

  • Role Name: Leave default (WatchtowerDirectOrgInventory) or customize
  • Watchtower Account ID: Leave as 684035162433 (do not modify)
  • External ID: Leave empty for now (you’ll get this from WatchTower)
3

Create Stack

  1. Check the IAM capabilities acknowledgment box
  2. Click Create stack
  3. Wait for deployment to complete (typically 1-2 minutes)
4

Copy the Role ARN

  1. Navigate to Outputs tab
  2. Copy the TargetRoleArn value
  3. Save this for WatchTower configuration
5

Configure in WatchTower

  1. In WatchTower, navigate to Organizations > Add Organization
  2. Fill in organization details
  3. In the Inventory Role step:
    • Role Type: Select DIRECT
    • Target Role ARN: Paste the ARN from step 4
    • External ID: Enter the external ID provided by WatchTower
    • Session Name: (optional) Enter WatchTower for CloudTrail tracking
If you configured an External ID, you’ll need to update the CloudFormation stack with the External ID value provided by WatchTower.

​
Chained Access Deployment

Best for: Organizations requiring an additional security layer or compliance controls Chained access creates a two-step role assumption path:
  1. WatchTower → Your intermediate account → Management account

​
When to Use Chained Access

  • Security policies prohibit direct external account trust
  • Compliance requirements mandate intermediate controls
  • You want centralized audit of all access through a trusted account
  • You have existing intermediate role infrastructure

​
Prerequisites

  • An AWS account to serve as the intermediate/trusted account
  • IAM permissions to deploy CloudFormation in both accounts
1

Deploy Intermediate Role

Important: Log into your intermediate/trusted account in your browser before clicking the launch button.
Click to deploy the intermediate role in your trusted account: Launch StackParameters:
  • Role Name: Leave default or customize
  • Destination Account ID: Enter your management account ID
  • Destination Role Name: Leave default (WatchtowerChainedOrgInventoryDestination)
  • Watchtower Account ID: Leave as 684035162433
  • External ID: Leave empty for now
  • Assume Role Scope: Leave as any-role-any-account (recommended)
Copy the IntermediateRoleArn from the Outputs tab.
2

Deploy Destination Role

Important: Log into your management account in your browser before clicking the launch button.
Click to deploy the destination role in your management account: Launch StackParameters:
  • Role Name: Must match the name used in Step 1 (default is fine)
  • Trust Principals: Select Named (trusts specific role)
  • Intermediate Account ID: Enter your intermediate account ID
  • Intermediate Role Name: Must match role name from Step 1
  • External ID: Leave empty for now
Copy both TargetRoleArn and IntermediateRoleArn from Outputs.
3

Configure in WatchTower

In WatchTower, navigate to Organizations > Add Organization:Organization Info:
  • Fill in organization details as usual
Inventory Role:
  • Role Type: Select CHAINED
  • Target Role ARN: Paste destination role ARN
  • Target External ID: Enter external ID (if provided by WatchTower)
  • Target Session Name: (optional) WatchTower
  • Intermediate Role ARN: Paste intermediate role ARN
  • Intermediate External ID: Enter external ID (if using)
  • Intermediate Session Name: (optional) WatchTower-Chain
If using an existing intermediate role, deploy only the destination template and set Trust Principals to All to trust the entire intermediate account.

​
What Permissions Are Granted?

All inventory roles provide read-only access to: AWS Organizations:
  • Organization structure and hierarchy
  • Organizational units and accounts
  • Service Control Policies (SCPs)
  • Delegated administrator details
  • Account creation status
Account Information:
  • Account contact details
  • Available AWS regions
No write, modify, or delete permissions are granted.

​
Updating External IDs

If you need to add or update an External ID after initial deployment:
  1. Navigate to CloudFormation in the AWS Console
  2. Select the stack (watchtower-direct-org-inventory or watchtower-chained-org-inventory-*)
  3. Click Update
  4. Select Use current template
  5. Update the pExternalId parameter
  6. Complete the update
Then update the configuration in WatchTower.

​
Troubleshooting

Stack creation fails with IAM permissions error:
  • Ensure you have iam:CreateRole and iam:PutRolePolicy permissions
  • Deploy in the correct account (management or delegated admin)
WatchTower cannot assume the role:
  • Verify the role ARN is correct
  • Check External ID matches in both AWS and WatchTower
  • For chained access, ensure intermediate role can assume destination role
  • Verify Watchtower production account ID is 684035162433
Organization inventory not appearing:
  • Allow 5-10 minutes for initial inventory collection
  • Check inventory status shows “ACTIVE” in WatchTower
  • Verify the role has the required Organizations permissions

​
Security Best Practices

  • Use External IDs: Always configure an external ID for additional security
  • Use CloudTrail: Monitor role assumptions via CloudTrail logs
  • Least Privilege: Roles grant only read permissions required for inventory
  • Regular Review: Periodically review who has access and audit logs
  • Session Names: Use descriptive session names for easier CloudTrail analysis

​
Advanced Configuration

​
Service Catalog Deployment

For MSPs managing multiple customer organizations, consider deploying the Inventory Roles Portfolio via AWS Service Catalog. This enables customers to self-service deploy inventory roles. See Service Catalog Setup for details.

​
Multiple Organizations

To manage multiple organizations:
  1. Deploy the inventory role in each organization’s management account
  2. Add each organization separately in WatchTower
  3. Use consistent naming conventions (e.g., WatchtowerOrgInventory-CustomerName)

​
Next Steps

After deploying the inventory role and configuring the organization in WatchTower:
  1. Verify Inventory: Check that member accounts appear in Organizations > View > Associated Accounts
  2. Configure Access Roles: Set up account access roles for individual account access
  3. Monitor Status: Ensure inventory status remains “ACTIVE”

​
Support

For assistance with role deployment: