AWS Session Manager
New Feature
2022.10.31.0
With AWS (Systems Manager) Session Manager, you can connect to and manage an EC2 instance without opening inbound ports, running a bastion host, or managing SSH keys. Here you can find more information about AWS Systems Manager and the documentation for AWS Systems Manager Session Manager.
This feature allows you to use the aws ssm start-session --target <INSTANCE_ID>
command with tabs. You can create profiles for your instances or synchronize them from AWS EC2 to connect to them directly.
Prerequisites
The following prerequisites must be met to use AWS Systems Manager Session Manager.
- Setup AWS CLI & Session Manager plugin
- Setup AWS Systems Manager Session Manager
- Setup AWS IAM user to sync and connect
- Verify the connection
Setup AWS CLI & Session Manager plugin
The AWS CLI and AWS Session Manager plugin is required on your computer to run the aws ssm start-session
command. You can download them here:
- AWS CLI (direct link Windows installer)
- AWS Session Manager plugin (direct link Windows installer)
See the AWS documentation for installation instructions.
Setup AWS Systems Manager Session Manager
To connect to the instances, the AWS Systems Manager Session Manager must be configured in AWS. See their documentation for instructions on how to set up the Session Manager.
Below you will find an example configuration:
Example SSM-SessionManagerRunShell
document
This is an example of the AWS Systems Manager Session Manager configuration and may not be suitable for a production environment.
Create a JOSN file with the name SessionManagerRunShell.json
and the following content:
{
"schemaVersion": "1.0",
"description": "Document to hold regional settings for Session Manager",
"sessionType": "Standard_Stream",
"inputs": {
"s3BucketName": "<S3_BUCKET>",
"s3KeyPrefix": "<S3_BUCKET_PREFIX>",
"s3EncryptionEnabled": true,
"cloudWatchLogGroupName": "<CLOUDWATCH_GROUPNAME>",
"cloudWatchEncryptionEnabled": true,
"cloudWatchStreamingEnabled": false,
"kmsKeyId": "<KMS_KEY_ARN>",
"runAsEnabled": true,
"runAsDefaultUser": "<SSM_RUNASUSER>",
"idleSessionTimeout": "20",
"maxSessionDuration": "60",
"shellProfile": {
"windows": "<LINUX_COMMANDS>",
"linux": "<WINDOWS_COMMANDS>"
}
}
}
Create the document in AWS SSM via AWS CLI:
aws ssm create-document \
--name SSM-SessionManagerRunShell \
--content "file://SessionManagerRunShell.json" \
--document-type "Session" \
--document-format JSON
Example IAM role / instance profile
This is an example of an IAM role/instance profile that allows access from AWS Systems Manager Session Manager to the instance and may not be suitable for a production environment.
Create a new IAM role/instance profile with the following content:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "ec2.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
Add an (inline) policy to the role with the following content:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ssmmessages:CreateControlChannel",
"ssmmessages:CreateDataChannel",
"ssmmessages:OpenControlChannel",
"ssmmessages:OpenDataChannel",
"ssm:UpdateInstanceInformation"
],
"Resource": "*"
} /*,
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::<S3_BUCKET>/<S3_BUCKET_PREFIX>/*"
},
{
"Effect": "Allow",
"Action": [
"s3:GetEncryptionConfiguration"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": "<KMS_KEY_ARN>"
},
{
"Effect": "Allow",
"Action": "kms:GenerateDataKey",
"Resource": "*"
}*/
]
}
Setup AWS IAM user to sync and connect
For the snychronization of the EC2 instances and to connect to them via AWS Systems Manager Session Manager, a separate user with minimal privileges should be set up. For the synchronization from AWS EC2 the permissions ec2:DescribeInstances
and ec2:DescribeInstanceStatus
are required. Additionally, the user must be able to connect to the instances via AWS Systems Manager Session Manager. Below are examples of both policies:
Example sync policy
This is an example of an IAM user policy to synchronize instances of AWS EC2 for NETworkManager.
Add an (inline) policy to the user with the following content:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowNETworkManagerSync",
"Effect": "Allow",
"Action": ["ec2:DescribeInstances", "ec2:DescribeInstanceStatus"],
"Resource": "*"
}
]
}
Example connect policy
This is an example of an IAM user policy that allows access to EC2 instances through AWS Systems Manager Session Manager and may not be suitable for a production environment.
Add an (inline) policy to the user with the following content:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["ssm:StartSession"],
"Resource": [
"arn:aws:ec2:<AWS_REGION>:<ACCOUNT_ID>:instance/*",
"arn:aws:ssm:<AWS_REGION>:<ACCOUNT_ID>:document/SSM-SessionManagerRunShell"
]
},
{
"Effect": "Allow",
"Action": [
"ssm:DescribeSessions",
"ssm:GetConnectionStatus",
"ssm:DescribeInstanceProperties",
"ec2:DescribeInstances"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": ["ssm:TerminateSession", "ssm:ResumeSession"],
"Resource": ["arn:aws:ssm:*:*:session/${aws:username}-*"]
} /*,
{
"Effect": "Allow",
"Action": ["kms:GenerateDataKey"],
"Resource": "<KMS_KEY_ARN>"
}*/
]
}
API keys must be generated for the user and the AWS CLI must be configured (See aws configure
and ~\.aws\credentials
file for more details).
Sensitive data like the API keys are stored in plain text in the file ~\.aws\credentials
!
Verify the connection
You can verify the connection to the EC2 instance through AWS Systems Manager Session Manager by opening a PowerShell and connecting to the instance through AWS CLI:
aws ssm start-session --target instance-id <INSTANCE_ID>
Connect
Instance ID
ID of the AWS EC2 instance.
Type: String
Profile
AWS CLI profile which will be used to connect.
Type: String
If not set, the AWS CLI default settings are used!
Region
AWS region where the instance is located.
Type: String
If not set, the AWS CLI default settings are used!
Profile
Instance ID
ID of the AWS EC2 instance.
Type: String
Profile
AWS CLI profile which will be used to connect.
Type: String
If not set, the Default profile
from the settings is used!
Region
AWS region where the instance is located.
Type: String
If not set, the Default region
from the settings is used!
Settings
Synchronize EC2 instances from AWS
If enabled, EC2 instances are synced from AWS. In addition, the profiles and regions to be synchronized must be configured.
Type: Boolean
Default: Disabled
Profiles and regions to synchronize
Here you can specify a combination of AWS CLI profile and AWS region from where the EC2 instances should be synchronized. Multiple AWS accounts and regions are supported.
Type: List<NETworkManager.Models.AWS.AWSProfileInfo>
Property | Type |
---|---|
Enabled | Boolean |
Profile | String |
Region | String |
Default:
Enabled | Profile | Region |
---|---|---|
Disabled | default | eu-central-1 |
Disabled | default | us-east-1 |
Example:
Enabled | Profile | Region |
---|---|---|
Disabled | dev | eu-central-1 |
Disabled | dev | us-east-1 |
Disabled | prod | eu-central-1 |
Disabled | prod | us-east-1 |
Only enabled profiles are synchronized and Synchronize EC2 instances from AWS
must be enabled!
Synchronize only running EC2 instances from AWS
If enabled, only EC2 instances are synchronized where the instance state
is running
.
Type: Boolean
Default: Enabled
Default profile
Type: String
AWS CLI profile which will be used to connect.
Type: String
If not set, the AWS CLI default settings are used!
Default region
AWS region where the instance is located.
Type: String
If not set, the AWS CLI default settings are used!
PowerShell
Path to the PowerShell console where the AWS CLI is available and which should be embedded in the program.
Type: String
Default: C:\Program Files\PowerShell\7\pwsh.exe
, C:\Program Files (x86)\PowerShell\7\pwsh.exe
or C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
Possible values:
path\to\PowerShell.exe
path\to\pwsh.exe