AWS EC2 Instance Connect

AWS EC2 Instance Connect allows AWS clients to push ephemeral SSH credentials (keys) to EC2 instances on-the-fly. The Border0 connector can act as an SSH proxy and forward request to the EC2 instance (the upstream target) and use EC2 Instance connect to authenticate.
The big advantage of using this method,:is that by default most EC2 instances support EC2 instance connect, meaning you can quikcly make available many EC2 upstream target using Border0, without having to make any changes to the upstream EC2 machines!

Border0 integrates natively with AWS EC2 Instance Connect, allowing Border0 administrators to expose EC2 instances as Border0 Services without needing to manage shared credentials or network ACLs.

🚧

Heads-up!

The following documentation assumes that you already have an AWS EC2 instance accessible via EC2 Instance Connect.

Note: it's important the connector has network reachability to the traget instances either (a) reachable via a public IP address, (b) running within the same VPC as the Border0 Connector, or (c) reachable via a VPC endpoint tunnel available to the Border0 Connector.

If you need help setting up your EC2 instance for access via EC2 Instance Connect, see the additional resources at the bottom of this page.

Creating a new Border0 SSH socket

To make an EC2 Instance available over SSH EC2 instance-connect do the following:

• In the Sockets page, click on new SSH socket
• Set a name and, optionally, a description
• From Upstream connection type select AWS EC2 Instance Connect
• For the example we will leave AWS Authentication Strategy as default, this means we'll assume the connector has the right IAM role. Alternatively AWS Static credentials or AWS Profile can be supplied.
• For hostname and port, we'll use 10.10.10.10. This assumes we run connector in the same VPC and subnet
• The default port is 22, update according to your environment.
• The instance ID is our example AWS EC2 instance i-06335d997221f33d4
• We need to specify the region for our target EC2 instance, the example is using us-east-1
• As for SSH Username we leave Prompt Client but we can specify a username to use for this service
• Lastly, we select our target connector
• Final step is to click create socket at the bottom of the page

AWS Credentials

🚧

Heads-up!

The Border0 Connector will use your local system's AWS Standardized Credential Providers Chain to determine how to authenticate against AWS in order to connect to the EC2 instance.

The machine that runs the Border0 connector must have the appropriate AWS IAM permissions in order to push ephemeral SSH keys for any required OS users on your target EC2 instance in order to expose access to the EC2 instance over the Border0 Service.

The AWS permission for the Connector will require at a minimum the following AWS policy:

Replace AWS_REGION, AWS_ACCOUNT_ID, EC2_INSTANCE_ID, and OS_USER with the AWS region where your EC2 instance instance is running, AWS account ID, EC2 instance ID and OS user of the instance respectively. All of these can also be replaced with a wildcard *.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ec2-instance-connect:SendSSHPublicKey",
      "Resource": [
        "arn:aws:ec2:${AWS_REGION}:${AWS_ACCOUNT_ID}:instance/${EC2_INSTANCE_ID}"
      ],
      "Condition": {
        "StringEquals": {
          "ec2:osuser": "${OS_USER}"
        }
      }
    }
  ]
}

Click below to see a fully populated example. This policy allows access to SendSSHPublicKey for any OS user in any EC2 instance in any region and account.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ec2-instance-connect:SendSSHPublicKey",
      "Resource": [
        "arn:aws:ec2:*:*:instance/*"
      ]
    }
  ]
}

Help Getting EC2 + Instance Connect Set Up

Below we briefly go over the requirements for an EC2 instance to be accessible via EC2 Instance Connect. For comprehensive instructions, you may refer to the official AWS documentation here: "Getting Started with EC2 Instance Connect".

We recommend watching the video below, for a step by step walkthrough.

There are two independent requirements for an EC2 instance to be accessible via EC2 Instance Connect.

1) EC2 Instance Connect must be installed on the instance

Some EC2 Amazon Machine Images (AMIs) come out-of-the-box with EC2 Instance Connect pre-installed. You may want to choose one of those AMIs if you wish to skip the installation process. These AMIs include those for the most recent versions of Amazon Linux and Ubuntu.

Otherwise to install EC2 Instance Connect yourself, you may want to refer to the official AWS documentation here: "EC2 Instance Connect Set-Up".

2) The Border0 connector must have network access to connect to the the instance

There must not be any network ACLs e.g. firewall or security group rules preventing SSH traffic from the Border0 connector to the instance.

Troubleshooting
Should you see any issues with your new socket, it's typically because it can't connect to the upstream SSH server. Common use-cases are, connector not being able to communicate with the provided hostname and port number, or, invalid credentials. To troubleshoot that take a look at the connector logs as described here