Open an SSH connection to your AWS SSM connected instances without the need to open any ssh port in you security groups.
Tip
If you only need to connect to AWS EC2 instances you could use the ec2-instance-connect
variant of this proxy command.
This variant allows you to manage wich IAM identity can connect to which OS user on the target instance.
See EC2 Only Variant
-
Local Setup
- Install AWS CLI
- AWS Docs
- MacOS
brew install awscli
- Install AWS CLI Session Manager Plugin
- AWS Docs
- MacOS
brew install session-manager-plugin
- Install the SSM SSH Proxy Command Script
- Linux & MacOS
- Copy aws-ssm-ssh-proxy-command.sh into
~/.ssh/aws-ssm-ssh-proxy-command.sh
- Ensure it is executable (
chmod +x ~/.ssh/aws-ssm-ssh-proxy-command.sh
)
- Copy aws-ssm-ssh-proxy-command.sh into
- Windows
- Copy aws-ssm-ssh-proxy-command.ps1 into
~/.ssh/aws-ssm-ssh-proxy-command.ps1
- Ensure you are allowed to execute powershell scripts (see Set-ExecutionPolicy command)
- Copy aws-ssm-ssh-proxy-command.ps1 into
- Linux & MacOS
recommended
Setup SSH Config- Add ssh config entry AWS instances to your
~/.ssh/config
.- Linux & MacOS
host i-* mi-* IdentityFile ~/.ssh/id_ed25519 ProxyCommand ~/.ssh/aws-ssm-ssh-proxy-command.sh %h %r %p ~/.ssh/id_ed25519.pub StrictHostKeyChecking no
- Windows
host i-* mi-* IdentityFile ~/.ssh/id_ed25519 ProxyCommand powershell.exe ~/.ssh/aws-ssm-ssh-proxy-command.ps1 %h %r %p ~/.ssh/id_ed25519.pub StrictHostKeyChecking no
- Linux & MacOS
- Adjust
IdentityFile
and corresponding publickey (last argument ofProxyCommand
) if needed.
- Add ssh config entry AWS instances to your
- Install AWS CLI
-
AWS IAM Setup
- Ensure IAM Permissions for Your IAM Identity
- IAM Policy Template
ssm:StartSession
for DocumentName:AWS-StartSSHSession
and Target Instancessm:SendCommand
for DocumentName:AWS-RunShellScript
and Target Instance
- IAM Policy Template
- Ensure IAM Permissions for Your IAM Identity
-
Target Instance Setup
- Ensure IAM Permissions for SSM Agent
- AWS Docs
- For EC2 Instances use Instance Profiles
- Install SSM Agent on Linux Instances
- Already preinstalled on all AWS Linux AMIs
- AWS Docs - Linux
- AWS Docs - Windows
- Ensure IAM Permissions for SSM Agent
- Ensure AWS CLI environemnt variables are set properly
- Linux & MacOS
export AWS_PROFILE=...
orAWS_PROFILE=... ssh...
- Windows
$env:AWS_PROFILE = ...
or$env:AWS_PROFILE = ...; ssh.exe...
- Linux & MacOS
- Open SSH Connection to AWS SSM connected instance
- Linux & MacOS
ssh <INSTACEC_USER>@<INSTANCE_ID>
e.g.ssh ec2-user@i-1234567890
- Windows
ssh.exe <INSTACEC_USER>@<INSTANCE_ID>
e.g.ssh.exe ec2-user@i-1234567890
⚠️ Unfortunately on Windows is not possible to show output while running ProxyCommand, script output is interpreted as SSH banner which is available with SSH verbose options.
- Linux & MacOS
- [EC2 Intances Only] If default region does not match instance region you need to provide it as part of hostname
<INSTACEC_USER>@<INSTANCE_ID>--<INSTANCE_REGION>
- e.g.
ec2-user@i-1234567890--eu-central-1
If you have not setup an SSH Config you can use the following ssh command options to use this proxy command.
- Linux & MacOS
ssh -i "~/.ssh/id_ed25519" -o ProxyCommand="~/.ssh/aws-ssm-ssh-proxy-command.sh %h %r %p ~/.ssh/id_ed25519.pub" ...
- Windows
ssh.exe -i "~/.ssh/id_ed25519" -o ProxyCommand="powershell.exe ~/.ssh/aws-ssm-ssh-proxy-command.ps1 %h %r %p ~/.ssh/id_ed25519.pub" ...
If you only want to connect to EC2 instances you can make use of EC2 Instance Connect SendSSHPublicKey
command as a drop in replacement for the SSM SendCommand
to temporary add your public key to the target instance.
The advantage from this variant is that you don't need to grant ssm:SendCommand
to users and there by the permission to execute everything as ssm-user
or root
.
Instead you grant ec2-instance-connect:SendSSHPublicKey
permission and optionaly restrict it to a specific OS user e.g. ec2-user
.
To do so just use Proxy Command Script and IAM Policy Template from the ec2-instance-connect folder instead.
- Proxy Command Script
- Linux & MacOS aws-ssm-ssh-proxy-command.sh
- Windows aws-ssm-ssh-proxy-command.ps1
- IAM Policy Template
ssm:StartSession
for DocumentName:AWS-StartSSHSession
and Target Instanceec2-instance-connect:SendSSHPublicKey
- AWS Documentation
- You may need to adjust
ec2:osuser
to match your needs. Default isec2-user