Use port forwarding in AWS Systems Manager Session Manager to connect to remote hosts

We recently announced a new capability within AWS Systems Manager Session Manager that allows forwarding connections from client machines to ports on remote hosts. This enables users to securely access and manage remote servers (databases, web servers, etc.) in the private networks without needing to setup bastion hosts or open additional ports to the outside networks. In this post, I’ll walk you through an example of setting up port forwarding to remote hosts using this new capability of Session Manager.

About AWS Systems Manager Session Manager

AWS Systems Manager Session Manager is a fully-managed Systems Manager capability. Session Manager lets you connect to and manage your instances, edge devices, as well as on-premises servers and virtual machines (VMs). You can use either an interactive one-click browser-based shell or the or the AWS Command Line Interface (AWS CLI).

Scenario

Let’s say you are trying to use a graphical tool on your local machine (e.g. SQL Workbench/J) to manage a (MySQL) instance that is inside a subnet within an Amazon Virtual Private Cloud (Amazon VPC) (Figure 1). Typically, this would require you to open up TCP port 3306 to allow connection to this database over the Internet, however this is not a best practice from the security standpoint. Alternatively, you could also try to setup a bastion host (jump server) and install all the tools on it but that would require lot of extra work to setup and maintain. In the next section, I will show how “port forwarding” in Session Manager can be used to connect to remote MySQL database from local client without the hassle of setting up a jump host.

Figure 1: Overall solution for connecting to remote hosts in private networks

Prerequisites

Note that Systems Manager Session Manager sessions can be launched from or AWS CLI. For this post I will use the CLI method

• AWS CLI is setup and configured on the local system with the correct set of permissions to allow access to Systems Manager. Refer to Installing or updating the latest version of the AWS CLI for detailed instructions.
• A Systems Manager managed instance (Amazon EC2 or on-premises) that is either in the same subnet or has network connectivity to your remote database host.
• Make sure that your database instance is remotely manageable, i.e., the associated security group or firewall isn’t blocking remote connections.
• Session Manager plugin for the AWS CLI for your specific operating system is installed
• SQL Workbench/J (or another preferred tool) is installed and configured on local system

Step 1: Instance setup and verification

Verify that you can connect to the Systems Manager managed instance from your local machine. Open your favorite terminal program (putty, or Mac Terminal etc.) and enter the following command. Replace ssm-managed-instance-id with the EC2 instance id of your SSM managed instance.

aws ssm start-session --target <ssm-managed-instance-id>

If the connection is successful, setup is verified. You can close the connection and proceed to the next step.

Step 2: Open a connection forwarding session to a remote port on MySQL server

In this step, you will relaunch the Session Manager session, but this time we’ll execute a Systems Manager Document that will initiate a connection forwarding session to the remote database server. Enter the following command in the terminal replacing ssm-managed-instance-id and remote-database-host-name with their corresponding values based on your setup.

Note: In this example, we are using local port 1053, but you can choose a different local port if you prefer

aws ssm start-session --target <ssm-managed-instance-id> --document-name AWS-StartPortForwardingSessionToRemoteHost --parameters '{"portNumber":["3306"],"localPortNumber":["1053"],"host":[" remote-database-host-name"]}'

Please leave this running until the end of this exercise.

Step 3: (Optional) Verify that connection forwarding is working

You can verify that the connection forwarding is working by running the following command in a new terminal window. This will allow you connect to the database over CLI session.

mysql -h 127.0.0.1 --port 1053 -u admin -p

Step 4: Connect using SQL Workbench/J

Launch SQL Workbench/J on your local machine. If you already have a connection profile for this database, you can use it, otherwise you can create a new one based on the connection parameters (Username, password etc.) specific to your database. Please note that instead of using the remote IP or hostname of your database, you will be using local host IP address in the URL field.

Jdbc:mysql://127.0.0.1:1053/<database-name>

Figure 2: SQL Workbench – Connection Profile

Hit “OK”, and you will now be connected to your remote database.

Figure 3: SQL Workbench showing query results

Conclusion

In this post I showed you how to connect to remote servers inside of private networks using Systems Manager Session Manager via the “port forwarding to remote host” feature. I used RDS mySQL server as an example. However, this same method can be used to remotely manage any type of hosts using your favorite management software from local client.

About the author: