Connect AWS

Reference for the Connect AWS step in the onboarding wizard. Escher uses AWS IAM Identity Center (SSO) by default; access keys are available as an alternate method.

What Escher needs

Read access to the resources you'd expect: EC2 instances, S3 buckets, IAM roles and policies, RDS databases, VPCs, and (when enabled) Cost Explorer. The exact minimum permissions are listed at the bottom of this page.

Escher does not need write permissions for normal use. Write operations only happen via the Playbook flow, which requires explicit human approval per step.

Default method: SSO (recommended)

If your AWS Organization uses IAM Identity Center (formerly AWS SSO), this is the safest path — no long-lived access keys, session length governed by your security team's policy, and credential rotation happens automatically.

The onboarding wizard gives you three commands. Click >_ Open Terminal in the wizard to launch macOS Terminal, then paste each one in turn:

bash

# 1. Wizard prompts for SSO Start URL, region, and profile name.
aws configure sso

# 2. Opens a browser to complete sign-in via your IdP (Okta, Entra ID, etc.).
aws sso login --profile my-sso-profile

# 3. Confirms the SSO session is active.
aws sts get-caller-identity --profile my-sso-profile

When get-caller-identity returns your AWS principal, click Re-check in the wizard. The check passes and Continue to Azure unlocks.

TIP

The profile name (my-sso-profile above) is a label you choose. Use something descriptive like prod-admin or audit-readonly.

Alternate method: access keys

If your org doesn't use SSO, click Change method at the bottom-right of the Connect AWS panel. Two commands:

bash

# Prompts for Access Key ID, Secret, default region (e.g. us-east-1), and output format.
aws configure --profile dev

# Verify the credentials work.
aws s3 ls --profile dev

Same Re-check flow.

WARNING

Access keys are long-lived credentials stored in ~/.aws/credentials. Prefer SSO when possible. If you must use access keys, attach the minimum read-only policy below — not AdministratorAccess.

Minimum IAM policy (read-only)

Whichever method you use, the principal Escher signs in as needs read access across the services you want to query. The simplest option is the AWS-managed ReadOnlyAccess policy — broader than Escher strictly needs, but zero write permissions.

For a tighter custom policy, this is the minimum set Escher uses today:

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EscherReadOnly",
      "Effect": "Allow",
      "Action": [
        "ec2:Describe*",
        "s3:List*",
        "s3:Get*",
        "iam:List*",
        "iam:Get*",
        "rds:Describe*",
        "cloudtrail:LookupEvents",
        "cloudtrail:Describe*",
        "cloudwatch:Describe*",
        "cloudwatch:Get*",
        "ce:GetCostAndUsage",
        "ce:GetReservation*",
        "ce:GetSavingsPlans*",
        "tag:GetResources",
        "tag:GetTagKeys"
      ],
      "Resource": "*"
    }
  ]
}

INFO

Cost Explorer: enable it once in the AWS Billing console (Billing → Cost Explorer → Enable). There's a 24-hour activation lag before the API returns data.

Multiple AWS accounts

Add each account as a separate profile in the same wizard step (or later via Settings → Profiles → Add Profile → AWS). You can mix:

Multiple member accounts in the same Organization
Profiles across separate Organizations
A mix of SSO-backed and access-key-backed profiles

After onboarding, every connected profile shows up in Settings → Profiles as a toggle switch — flip on the ones you want Escher to use right now, flip off the rest. See Switching Profiles.

Troubleshooting

Error	Fix
`aws configure sso` fails	Confirm your SSO Start URL with your team's AWS admin. URL pattern: `https://<your-org>.awsapps.com/start/`.
`aws sso login` opens browser but returns no token	Make sure you have access to at least one account/role in IAM Identity Center. If not, ask your admin to assign you.
`InvalidClientTokenId` from `aws sts get-caller-identity`	Re-run `aws sso login --profile X` (SSO sessions expire) or re-run `aws configure --profile X` (access keys may have been rotated).
Escher's Re-check still fails after the CLI command succeeds	Confirm the profile name in Escher matches the one you used (`aws configure list-profiles`). Re-open the wizard if needed.

What's next

Connect Azure — Subscription-picker flow
Switching Profiles — Manage profiles after onboarding
Quickstart — Full onboarding walkthrough

Connect AWS ​

What Escher needs ​

Default method: SSO (recommended) ​

Alternate method: access keys ​

Minimum IAM policy (read-only) ​

Multiple AWS accounts ​

Troubleshooting ​

What's next ​