Connect to AWS SSO and SSH into EC2 Instance

Mon, 17 Mar 2025 00:00:00 +0000

This how-to article explains steps required to configure AWS account with and without need of AWS SSO and then SSH into an EC2 instance. The steps are generic in nature and can be customized to apply to any environment or any project.

Prerequisites

AWS CLI v2
AWS SSO access
Terminal
AWS IAM user credentials (Access Key ID and Secret Access Key)

Directory structure

~/
├── .aws/
│   ├── config
│   └── credentials
└── .ssh/
    ├── ec2-key.pem
    └── config

Setup .aws config without SSO

Create .aws folder if it doesn’t exist.

mkdir -p ~/.aws

Create credentials file.

# ~/.aws/credentials
[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

Create config file.

# ~/.aws/config
[default]
region = ap-southeast-2
output = json

Test your config.

aws sts get-caller-identity

Setup .aws config with SSO

This is more applicable for enterprise setup rather than individual setup. Prerequisite is have a valid and working AWS SSO Start URL (e.g. https://company.awsapps.com/start) which allows to complete authentication in the browser. Add AWS config entry (~/.aws/config) in your OS user root location. Add section per required spec e.g. new profiles each for aws-dev, aws-prod.

Sample .aws folder structure is below. Ignore ‘amplify’ and ‘cli’ folders to start with.

[profile aws-prod]
sso_session = aws-prod
sso_account_id = 123456789123
sso_role_name = aws-prod-SystemAdmin
region = ap-southeast-4
output = json
credential_process = aws configure export-credentials --profile aws-prod

Connect by SSO by running following command.

aws sso login --profile aws-prod

Setup .ssh config

The .pem files are keypairs created while launching ec2 instance ec2-prod.

Create .ssh folder if it doesn’t exist.

mkdir -p ~/.ssh

Move downloaded .pem file to .ssh folder.

mv ~/Downloads/ec2-prod.pem ~/.ssh/ec2-prod.pem

Provide necessary permissions to key pair.

chmod 400 ~/.ssh/ec2-prod.pem

Add an entry to SSH config.

nano ~/.ssh/config

Add following to the conf file.

Host ec2-prod
    HostName 1.2.3.4             # Replace with your EC2's public IP
    User ec2-user                # Use 'ubuntu' for Ubuntu instances
    IdentityFile ~/.ssh/ec2-prod.pem

Sample .ssh folder structure is below.

Alternatively, add SSH config entry (~/.ssh/.sshd_config.d/profile.conf) in your OS user root location. Add conf files per required profile e.g. new conf files each for aws-dev, aws-prod.

Add following to aws-prod.conf file.

Host ec2-prod
  User ec2-user
  IdentityFile ~/.ssh/ec2-prod.pem
  ProxyCommand aws ssm start-session --target i-01xyz7659824a123q --profile aws-prod --document-name AWS-StartSSHSession --parameters portNumber=22

This creates separate config files for each profile. It’s more applicable if you’re using AWS profile with SSO.

Connect to ec2 instance

SSH into ec2 instance.

ssh ec2-prod

Sample output indicating you’re connected to the ec2 instance.