Skip to main content

Accessing EC2s

Overview

To connect to EC2s on the Modernisation Platform, we use AWS Systems Manager Session Manager. This enables us to connect to EC2s securely, via AWS SSO, without the need to open ports to the public.

Required configuration to connect via Session Manager

1) Ensure AWS CLI v2 and Session Manager plugin are installed locally. For example, if you’re using macOS, you can install the following brew packages:

  • awscli - Official Amazon AWS command-line interface
  • session-manager-plugin - Session Manager Plugin for the AWS CLI

2) Add the following to your ~/.aws/config configuration file. Give the profile name a relevant name for example [profile glados-test-developer] and add the corresponding AWS account number:

[profile glados-test-developer]
sso_start_url = https://moj.awsapps.com/start
sso_region = eu-west-2
sso_account_id = 123456789
sso_role_name = modernisation-platform-developer
region = eu-west-2
output = json

Note: If the development account has sandbox access, then use the modernisation-platform-sandbox for sso_role_name above.

3) Log in to SSO using the following command:

 aws sso login --profile glados-test-developer

Connecting to AMI images with the SSM Agent installed

Most modern AMIs will already have the SSM Agent installed. You can connect to these instances directly with Session Manager.

4) Start a basic Session Manager session

aws ssm start-session --target i-12345bc --profile glados-test-developer

Using a bastion for older AMI images

Older operating systems may not support installation of the SSM Agent, in this case a bastion can be used to forward connections on to the EC2. Bastions can also be used for port forwarding to connect to databases or private configuration consoles.

Member accounts can use the Modernisation Platform bastion module to build a bastion configured with user and user SSH keys. Once the bastion has been built in the environemnt, these steps outline the additional AWS and SSH configurations required for users to connect to the bastion and on to their desired EC2 within their environment.

5) Add the example in this step to your ~/.ssh/config file. Give the host a relevant name, for example glados-test-bastion. Replace the User and the IdentityFile path - it is the local path to the corresponding private key of the public key added to the bastion_linux.json file set up as part of the Modernisation Platform bastion module build. Replace the target with the bastion instance ID in the corresponding AWS account and include the AWS profile created in the previous step:

Host glados-test-bastion
     StrictHostKeyChecking no
     UserKnownHostsFile /dev/null
     LogLevel QUIET
     IdentityFile ~/.ssh/id_rsa
     User jane
     ProxyCommand sh -c "aws ssm start-session --target $(aws ec2 describe-instances --no-cli-pager --filter "Name=tag:Name,Values=bastion_linux" --filter "Name=instance-state-code,Values=16" --query 'Reservations[0].Instances[0].InstanceId' --profile glados-test-developer | tr -d '"') --document-name AWS-StartSSHSession --parameters 'portNumber=%p' --profile glados-test-developer --region eu-west-2"

Note: The bastion server is re-created on daily basis which causes the host identification to change. When the user connects to the bastion using SSH, the SSH client warns about the host identification change. In the above, the configuration StrictHostKeyChecking no, UserKnownHostsFile /dev/null and LogLevel QUIET is added to prevent the WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! by the SSH client. If we didn’t add the above, the user would have to manually remove the old host key from ~/.ssh/known_hosts on daily basis, which could be annoying.

Note: If you’re unable to connect, remove LogLevel QUIET from the above to see additional logs. If the aws ssm command reports the error An error occurred (ForbiddenException) when calling the GetRoleCredentials operation: No access, make sure the sso_role_name in the AWS SSO profile is correct (see the note for the AWS SSO profile glados-test-developer above).

6) SSH to the bastion using the following command:

ssh glados-test-bastion

Note: If you get the error Permission denied (publickey,gssapi-keyex,gssapi-with-mic), check the bastion_linux.json file inside the modernisation-platform-environments repository includes your public SSH key. On the other hand, if you re-generate your public SSH key, then you will also need to update it in the bastion_linux.json. Moreover, in order to SSH using your newly generated key you will need to restart your ssh-agent.

Using the Bastion as a jump server to access Linux EC2s

In addition to the configuration added to the ~/.ssh/config file in the step above, add the following to use the bastion as a jump server. Replace the Host instanceip with the ip address of the EC2 you need to connect to. The IdentityFile is the local path to the private key assigned to the EC2 instance you are connecting to.

Host instanceip
    IdentityFile glados-test.pem
    User ec2-user
    ProxyCommand ssh -W %h:%p glados-test-bastion

After adding the configuration above, SSH to your EC2 with the command below:

ssh instanceip

Port forwarding to EC2 using the bastion

Replace ports, IP adddresses, and name of Host as appropriate.

ssh -L 8000:11.11.11.11:80 glados-test-bastion
This page was last reviewed on 13 September 2024. It needs to be reviewed again on 13 March 2025 by the page owner #modernisation-platform .
This page was set to be reviewed before 13 March 2025 by the page owner #modernisation-platform. This might mean the content is out of date.