Cloud firewall automation: AWS

Reach keeps an ingress rule in one of your security groups pointed at your team's gateway IP. You don't hand over access keys: you create an IAM role that trusts Reach's relay identity, protected by an external ID that Reach generates for your organisation.

What Reach manages

Ingress permissions on the security group you choose, one per gateway IP:

  • source GATEWAY_IP/32, description TYO Reach gateway
  • the protocol and port from the target (tcp/udp with a single port, or all)

Adding the target calls AuthorizeSecurityGroupIngress; removing it calls RevokeSecurityGroupIngress. Both are idempotent — Reach ignores "already exists" and "not found" so re-syncs are safe. Other rules in the group are never touched.

1. Create the IAM role

In the dashboard, Cloud connections → Add connection → AWS shows two values you need: Reach's relay principal ARN and your organisation's external ID. In your AWS account, create a role with this trust policy:

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

The external ID is the standard confused-deputy guard: even if someone learns Reach's principal ARN, they can't assume your role without the ID that only your dashboard shows.

Attach an inline permissions policy scoped to the security group(s) Reach should manage:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "ec2:AuthorizeSecurityGroupIngress",
      "ec2:RevokeSecurityGroupIngress"
    ],
    "Resource": "arn:aws:ec2:REGION:ACCOUNT_ID:security-group/sg-0abc123456"
  }]
}

Reach doesn't need DescribeSecurityGroups — it verifies the connection with sts:GetCallerIdentity on the assumed role, which needs no extra permission.

2. Connect the role

  1. Cloud connections → Add connection → AWS.
  2. Paste the IAM Role ARN and your default region (e.g. ap-southeast-2). The external ID is filled in for you.
  3. Reach assumes the role for 15 minutes and checks its identity. A failure here is almost always a trust-policy typo — re-check the principal ARN and external ID.

3. Add a security-group target

  1. Add target on the connection.
  2. Security group ID (sg-…) and region (defaults to the connection's).
  3. Port and protocol — 3389/tcp for RDP, 22/tcp for SSH, all for everything.
  4. Save. Reach authorises the ingress immediately.

Verify with the AWS CLI

aws ec2 describe-security-groups --group-ids sg-0abc123456 --region ap-southeast-2 \
  --query "SecurityGroups[0].IpPermissions[?contains(to_string(IpRanges), 'TYO Reach')]"

You should see one entry per gateway IP with the description TYO Reach gateway.

Revoke

Delete the target (Reach revokes its ingress entries), then delete the IAM role or remove Reach's principal from its trust policy.

Common questions

How does Reach authenticate without keys?

Reach's own backend obtains short-lived credentials for its relay identity and then assumes your role with sts:AssumeRole + your external ID, for 15-minute sessions. No long-lived key for your account exists on either side.

Can one connection manage security groups in several regions?

Yes — the region is per target. The connection's region is just the default for new targets.

What if the security group already allows 0.0.0.0/0?

Reach adds its /32 entries alongside. Remove the open rule yourself once you've confirmed access via Reach works — Reach deliberately never deletes rules it didn't create.