How to Connect Your AWS Account

Printable — use Ctrl+P / Cmd+P to save as PDF.

Before you begin

You need the OpsBaseline Account ID — the 12-digit AWS account where OpsBaseline is hosted. Find it in Settings → AWS Accounts → Add Account.
You need the External ID — auto-generated per organization, visible in Settings → Organization. The same External ID is used for all AWS accounts in your organization.

Step 1 — Create an IAM Policy

Sign in to IAM Console.
Go to Policies → Create policy.
Click the JSON tab and paste one of the policies below.
Name the policy OpsBaselineReadOnlyPolicy.
Description: "Read-only permissions for OpsBaseline cloud monitoring and compliance."
Click Create policy.

Which policy should I use?

We recommend the full policy (Compliance Aid) for all plans. It is read-only and safe. If you upgrade your plan later, your role will already have the right permissions — no IAM changes needed.

If you prefer a minimal policy for your current plan, use the plan-specific version below.

Full Policy (Recommended for all plans)

Covers Inventory, Monitoring, Security, Cost, Drift, Backup, Compliance, and CloudTrail. Works with all plans including Enterprise.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ec2:Describe*",
      "rds:Describe*",
      "s3:ListAllMyBuckets",
      "s3:GetBucket*",
      "s3:GetObject",
      "sns:Publish",
      "ssm:DescribeInstanceInformation",
      "ssm:ListInventoryEntries",
      "elasticloadbalancing:Describe*",
      "ecs:List*",
      "ecs:Describe*",
      "lambda:List*",
      "lambda:GetFunction*",
      "cloudwatch:Get*",
      "cloudwatch:List*",
      "iam:List*",
      "iam:Get*",
      "iam:GenerateCredentialReport",
      "iam:GetCredentialReport",
      "tag:GetResources",
      "config:Describe*",
      "config:Get*",
      "config:List*",
      "backup:List*",
      "backup:Describe*",
      "backup:Get*",
      "cloudtrail:LookupEvents",
      "cloudtrail:GetTrailStatus",
      "cloudtrail:DescribeTrails",
      "logs:Describe*",
      "logs:Get*",
      "logs:FilterLogEvents",
      "kms:List*",
      "kms:Describe*",
      "kms:GetKeyPolicy",
      "kms:GetKeyRotationStatus",
      "securityhub:Get*",
      "securityhub:List*",
      "guardduty:List*",
      "guardduty:Get*",
      "access-analyzer:List*",
      "ce:GetCostAndUsage",
      "ce:GetCostForecast",
      "ce:GetReservationUtilization",
      "ce:GetSavingsPlansUtilization",
      "acm:ListCertificates",
      "acm:DescribeCertificate",
      "acm:ListTagsForCertificate"
    ],
    "Resource": "*"
  }]
}

Minimal policy for Base plan only

Covers Inventory, Monitoring, and Security scanning. Does not include Cost Explorer, Backup, Drift, Compliance, or CloudTrail permissions.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ec2:Describe*",
      "rds:Describe*",
      "s3:ListAllMyBuckets",
      "s3:GetBucket*",
      "elasticloadbalancing:Describe*",
      "ecs:List*",
      "ecs:Describe*",
      "lambda:List*",
      "lambda:GetFunction*",
      "cloudwatch:Get*",
      "cloudwatch:List*",
      "iam:List*",
      "iam:Get*",
      "tag:GetResources",
      "ssm:DescribeInstanceInformation",
      "ssm:ListInventoryEntries"
    ],
    "Resource": "*"
  }]
}

Minimal policy for Base+Drift+Backup plan

Adds Cost Explorer, AWS Backup, Config, and CloudWatch Logs to the Base policy. Does not include Compliance frameworks (IAM credential reports, ACM, KMS, SecurityHub, GuardDuty, Access Analyzer).

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ec2:Describe*",
      "rds:Describe*",
      "s3:ListAllMyBuckets",
      "s3:GetBucket*",
      "s3:GetObject",
      "sns:Publish",
      "ssm:DescribeInstanceInformation",
      "ssm:ListInventoryEntries",
      "elasticloadbalancing:Describe*",
      "ecs:List*",
      "ecs:Describe*",
      "lambda:List*",
      "lambda:GetFunction*",
      "cloudwatch:Get*",
      "cloudwatch:List*",
      "iam:List*",
      "iam:Get*",
      "tag:GetResources",
      "config:Describe*",
      "config:Get*",
      "config:List*",
      "backup:List*",
      "backup:Describe*",
      "backup:Get*",
      "logs:Describe*",
      "logs:Get*",
      "ce:GetCostAndUsage",
      "ce:GetCostForecast",
      "ce:GetReservationUtilization",
      "ce:GetSavingsPlansUtilization"
    ],
    "Resource": "*"
  }]
}

Step 2 — Create a Role with Trust Policy

In IAM, go to Roles → Create role.
Choose "Custom trust policy".
Paste the trust policy below, replacing the two placeholders.
Click Next.

Trust policy JSON:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::OPSBASELINE_ACCOUNT_ID:root"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID"
        }
      }
    }
  ]
}

Replace the placeholders:

OPSBASELINE_ACCOUNT_ID → the 12-digit OpsBaseline platform account ID (from Settings → Add Account).
YOUR_EXTERNAL_ID → your organization's External ID (from Settings → Organization). Use the same External ID for all your AWS accounts.

What is the External ID?

The External ID prevents the confused deputy problem. It is auto-generated when your organization is created and is the same for all AWS accounts you add. You can find it in Settings → Organization.

Step 3 — Attach the Policy to the Role

On the "Add permissions" page, search for OpsBaselineReadOnlyPolicy.
Select it and click Next.
Name the role OpsBaselineReadOnlyRole.
Description: "Read-only role for OpsBaseline cloud monitoring and compliance."
Click Create role.
Open the role and copy the Role ARN (e.g. arn:aws:iam::123456789012:role/OpsBaselineReadOnlyRole).

Step 4 — Add the Account in OpsBaseline

In OpsBaseline, go to Settings → AWS Accounts → Add Account.
Enter your 12-digit AWS Account ID and the Role ARN from Step 3.
The External ID is pre-filled with your organization's External ID.
Select the regions you want to scan (IAM is global — one role covers all regions).
Click Add Account.
Click the signal icon (Test Connection) to verify OpsBaseline can assume the role.
Run your first scan.

Multi-Account (Higher Plans)

On plans that support multiple AWS accounts (Base+Drift+Backup: up to 5, Compliance Aid: up to 10, Enterprise: configurable), repeat Steps 1–4 in each AWS account you want to connect. Use the same External ID for all accounts — it is tied to your organization, not to individual AWS accounts. Each AWS account gets its own IAM role with the same trust policy and permissions policy.

Multi-Region

IAM roles are global. You do not need to add the same account twice for different regions. When adding the account, select all regions to scan (e.g. us-east-1, eu-west-1). OpsBaseline iterates through each region using the same role.

Troubleshooting

"AccessDenied" on scan — Verify the trust policy has the correct OpsBaseline Account ID and External ID. Ensure the permissions policy is attached to the role.
"Role cannot be assumed" — Check the Role ARN is correct and the External ID matches exactly (case-sensitive).
Missing resources — Ensure the policy includes permissions for the services you want (e.g. Lambda, Backup). Use the Full Policy to cover everything.
Cost data shows $0 — The ce:* permissions are only in the Drift+Backup and Full policies. Upgrade your IAM policy if using the minimal Base policy.