RDP to an EC2 instance with SSM port forwarding

Session Manager can redirect any port on the instance to a local port on your machine. Forward 3389 and your normal RDP client connects to localhost — the Windows instance needs no public IP, no inbound security-group rule and no bastion. The same command forwards SQL, HTTP or anything else.

1. Prerequisites

  • The instance is set up for Session Manager with SSM Agent 3.0.222.0 or later (3.1.1374.0 for forwarding to a remote host).
  • Your IAM identity has ssm:StartSession on the instance and on the document arn:aws:ssm:REGION::document/AWS-StartPortForwardingSession.
  • AWS CLI plus the Session Manager plugin installed locally.

2. Forward the port

Linux and macOS:

aws ssm start-session \
    --target i-0123456789abcdef0 \
    --document-name AWS-StartPortForwardingSession \
    --parameters '{"portNumber":["3389"], "localPortNumber":["56789"]}'

Windows (Command Prompt):

aws ssm start-session ^
    --target i-0123456789abcdef0 ^
    --document-name AWS-StartPortForwardingSession ^
    --parameters portNumber="3389",localPortNumber="56789"
  • portNumber — the port on the instance (defaults to 80 if omitted).
  • localPortNumber — the port on your machine; anything free, e.g. 56789.

AWS notes that quoting differs by shell — if the parameters are rejected, that's usually the cause. Leave the command running; it holds the tunnel open.

3. Connect with RDP

Open your RDP client and connect to:

localhost:56789
  • Windows: mstsc, computer localhost:56789.
  • macOS: Windows App (formerly Microsoft Remote Desktop), PC name localhost:56789.
  • Linux: Remmina or xfreerdp /v:localhost:56789.

Sign in with the instance's Windows credentials. Close the RDP session, then Ctrl+C the start-session command to tear the tunnel down.

Getting the Windows password

For a freshly launched instance: EC2 → Instances → Connect → RDP client → Get password → Upload private key file → Decrypt password. It takes a few minutes after launch before the password is available, and your IAM identity needs ec2:GetPasswordData. The username is Administrator on an English OS (localised on others). Change it after first login.

4. Forward to a host behind the instance

To reach a database or another server that the instance can see but you can't — an RDS endpoint, a domain controller, a private web app — use the remote-host variant:

aws ssm start-session \
    --target i-0123456789abcdef0 \
    --document-name AWS-StartPortForwardingSessionToRemoteHost \
    --parameters '{"host":["mydb.example.ap-southeast-2.rds.amazonaws.com"],"portNumber":["3306"], "localPortNumber":["3306"]}'

The remote host doesn't have to be managed by Systems Manager; the instance just needs network access and name resolution to it. Grant ssm:StartSession on AWS-StartPortForwardingSessionToRemoteHost as well.

5. Troubleshooting

SymptomLikely cause
TargetNotConnectedInstance not fully set up (agent, profile, endpoints) — or it's in a different account/Region than your CLI profile.
AccessDeniedException on StartSessionMissing ssm:StartSession on the instance ARN or on the AWS-StartPortForwardingSession document.
Command hangs, then RDP can't connectWrong portNumber, or Windows Firewall on the instance blocks 3389 from localhost-originated traffic (it's the SSM Agent that connects, so allow RDP for the local/private profile).
Traffic stops mid-sessionLocal antivirus interfering with the plugin — AWS suggests excluding session-manager-plugin.
SessionManagerPlugin is not foundInstall the plugin; on Windows, check PATH.

More in Session Manager troubleshooting.

6. The one-click version

TYO Reach's Remote Targets for AWS run exactly this port-forwarding session under the hood: a team member clicks the instance in the tray, signs in via IAM Identity Center, and RDP opens on a local port automatically — no CLI or plugin on their machine.

Common questions

Can I forward a port other than 3389?

Yes — portNumber can be any port the instance listens on (5432 for PostgreSQL, 8080 for a web app, 22 for SSH). RDP is just the most common case.

Does the instance need a public IP or a security-group rule?

No. The SSM Agent opens an outbound connection to the Systems Manager service; nothing inbound is required, so you can remove the public IP and the 3389 rule entirely.

Can two people forward to the same instance at once?

Yes — each person opens their own session and picks their own localPortNumber.

Sources