Skip to main content

Manual setup — AWS Organization

Use this path only if CloudFormation StackSets and Terraform aren't viable. For organizations with more than about five member accounts, use CloudFormation or Terraform — they roll out the role to every member automatically and keep it up-to-date as new accounts are added.

What you'll create​

Two kinds of IAM role:

  1. Management-account role — created once, in your AWS Organization's management account. Has the same permissions as the single-account role plus organizations:ListAccounts so Rivia can enumerate members.
  2. Member-account role — created once per member account you want Rivia to read from. Identical to the single-account role.

Prerequisites​

  • Log in to your AWS Organization's management account before starting. The management-account role must be created there.
  • Decide which member accounts Rivia should read from. You'll repeat the member-role steps for each one.

1. Copy the External ID​

From the Rivia wizard (Organization scope, Manual deployment). Copy the generated External ID — it's the same ID used in both the management-account role and every member-account role.

2. Create the management-account role​

Follow the single-account manual-setup flow once, in the management account, with these changes:

  • Same trust policy as single-account setup.
  • Attach ViewOnlyAccess and SecurityAudit.
  • Copy the Rivia feature policies from the CloudFormation template (see single-account doc for details).
  • Additionally, add an inline policy granting organizations:ListAccounts and organizations:DescribeOrganization:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "organizations:ListAccounts",
        "organizations:DescribeOrganization"
      ],
      "Resource": "*"
    }
  ]
}

Name it anything; RiviaAccess-Role matches the automated paths.

3. Paste the management-account Role ARN into Rivia​

Rivia will attempt an assume-role call against the management account, succeed, and then call organizations:ListAccounts to enumerate your member accounts. Each member account appears in the Rivia UI as pending — meaning Rivia knows the account exists but hasn't yet been able to assume a role there.

4. Create the role in each member account​

For each member account you want Rivia to read from:

  1. Sign into that member account (or use role-assume from the management account).
  2. Follow the single-account manual-setup flow using the same External ID from step 1. No Organizations permissions needed — that's only on the management role.
  3. Use the same role name across all member accounts so Rivia can assume them consistently (the automated CloudFormation StackSet does this; matching the name lets a future migration to StackSets be painless).

As each member role becomes assumable, Rivia flips its status from pending to verified on its next periodic scan.

Switching to automated later​

If you start with manual and later want to switch to CloudFormation or Terraform, deploy the automated stack from your management account. It will deploy roles to any member accounts that don't yet have one and will update existing ones. Roles you created manually with the same name are compatible — the automated stack will adopt them.

Troubleshooting​

  • Members stay pending forever — either the role doesn't exist in that member account yet, or the External ID in its trust policy doesn't match Rivia's. Verify both.
  • organizations:ListAccounts AccessDenied on verify — the management-account role is missing the additional inline policy from step 2. Attach it and retry.
  • Wrong role name across members — not fatal; Rivia reads each member's role ARN individually. But keeping names consistent simplifies future automation.