AWS
Adding an AWS account gives Connect read access to it through an IAM role you create in the account, so Connect can discover its resources into Inventory and keep them current. The same setup can forward CloudTrail and Security Hub events to Connect, so changes show up in near real time instead of waiting for the daily discovery.
Everything is created by a CloudFormation stack (or the equivalent Terraform) whose parameters Connect fills in for you. You always own the role; it exists in your account and you can review or remove it at any time.
Before you start
| Prerequisite | Why it's needed | Where to check |
|---|---|---|
| The 12-digit AWS account ID | It identifies the account in Connect | AWS console, account menu (top right) |
| Permission to create a CloudFormation stack that creates IAM resources in that account | The stack creates the role and its policies | Your IAM permissions in the account |
For an AWS Organizations rollout, access to the organization's management account and the root ID (r-…) or the OU IDs (ou-…) to cover | The StackSet is created from the management account | AWS Organizations in the console |
Set up an AWS account
- In Connect, go to Integrations and click New Integration Account.
- Provider: AWS. Enter the AWS Account ID, a name, and a project.
- AWS Account ID must be the account's real 12-digit number, because Connect uses it to reach the account. Name is just the label shown throughout Connect.
- Connect Access decides what the stack creates. Read Only is what Connect needs: a role that can read the account's configuration. Read & Write adds permission to change resources, so Connect can apply remediations. Events Only skips the read role, so the account forwards events and Connect doesn't discover its resources; the stack still creates the small roles that register the account and deliver events. Not every level is offered to every organization; if only one is available it appears as a tag rather than a choice. Connect can't change this choice later, so to use a different level, create a new account.
- Click Continue to Provisioning. The Provision page offers three ways to create the role. Pick one:
- CloudFormation, for a single account. Sign in to that AWS account in the console, then open the Quick create stack link. The parameters are pre-filled from your account; leave them as they are, tick I acknowledge that AWS CloudFormation might create IAM resources, and create the stack.
- AWS Organizations CloudFormation, for many accounts at once. Sign in to the organization's management account, open the Quick create stack link, and enter the root ID or a comma-separated list of OU IDs to cover. Everything else is pre-filled. Keep us-east-1 in EventRegions: the StackSet creates the role and registers each account from that region.
- Terraform. Download the template from the link, copy the tfvars text, and apply the template with those variables. Terraform prompts for the region to create the stack in.
- Once the stack has finished creating, click Verify Account Access in Connect. It reports Access to this account has been successfully verified. when Connect can assume the role. Discovery starts on its own from there.
If you'd rather review what the stack does before creating it, open the template URL shown on the quick-create page, or choose Create change set so CloudFormation lists the resources first.
What the stack creates
| Resource | Purpose |
|---|---|
An IAM role under the path /CloudDefense/ | The role Connect assumes. Only Connect can assume it, and only with an external ID. It carries the AWS-managed SecurityAudit policy plus a custom policy with a few additional read-only permissions that SecurityAudit lacks |
| A small function that runs when the stack is created, updated, or deleted | Registers the role with Connect, and deregisters the account when the stack is deleted |
| A StackSet that adds two event rules in each selected region | One forwards CloudTrail write events and console sign-ins, the other Security Hub findings, to Connect for near-real-time updates. Not created on plans without event forwarding |
The EventRegions parameter is prefilled with the regions AWS enables by default. Opt-in regions, such as af-south-1 or me-central-1, are left out even when your account has enabled them; add any you use before creating the stack, or changes there wait for the daily discovery. A region that is not enabled in your account makes the StackSet fail.
Verify it landed
| What to check | Where to look |
|---|---|
| Connect can assume the role | The Provision page's Status card shows a Provisioned tag |
| The account is healthy | Integrations: the AWS row's Status stays clear |
| The resources themselves | Inventory > Resources, filtered by Vendor > AWS and, if you like, by account. Supported resources lists what discovery covers |
| Events are arriving | Make a change in the account (for example, tag an instance) and watch it appear in Inventory within a few minutes, rather than after the next daily discovery |
Keeping the stack current
The template is updated as discovery covers more services. Once the account is provisioned, the CloudFormation tab on the Provision page switches to showing an AWS CLI command that updates your existing stack to the latest template. You can run it from AWS CloudShell. To preview the changes first, download the template at the --template-url in the command, or update the stack with a change set.
Resource Errors on the Provision page whose message mentions Access Denied or not authorized usually mean the stack is behind the template; updating it adds the missing permissions.
Accounts added through AWS Organizations are updated from the management account instead: update that stack with the latest template from the AWS Organizations CloudFormation tab, and the StackSet rolls the change out to every member account. The CloudFormation tab shows no update command for member accounts. It does still show one for the management account's own Connect account, because that stack looks like any other. Never run it on the management stack: the single-account template drops the StackSet, and every member account's stack with it.
Details and edge cases
Deleting the stack deregisters the account. The stack reports its deletion to Connect, the account shows Not provisioned, and discovery stops. Delete the account in Connect as well if you no longer want it, or create the stack again to provision it again. Deleting an older stack the account no longer uses, after creating a new one for it, leaves the account provisioned.
Some plans rely on the daily discovery. On those, the stack skips the event StackSet, so Inventory refreshes once a day.
For common issues, see Troubleshooting.
AWS documentation
- Creating a stack from a quick-create link: what the Quick create stack page is
- Updating stacks using change sets: previewing a template update before applying it
- SecurityAudit managed policy: the bulk of what the role can read
- Working with StackSets: how the Organizations rollout and the per-region event rules are deployed