How to set up AWS Session Manager

Last update 10.2022

#CONNECT-TO-EC2

How does AWS Session Manager work

AWS Session Manager is a one of three dedicated AWS services enabling command line access to an EC2 instance without the required ssh key (others are: EC2 instance connect and EC2 serial console). Session Manager doesn't use SSH port for communication. Internally Session Manager uses its own communication channel to send back (EC2) and forth (Session Manager) encrypted (by TLS 1.2) streams of commands and the session alone is signed by Signature Version 4 signing process (Sigv4). 

The communication from the user perspective looks and feels exactly the same as if SSH connection were used. The service is free of charge.

Supported instances

AWS Session Manager can establish access to Linux, macOS (Bash) and Windows (PowerShell) instances alike. There are no limitations to what OS images (Amazon Machine Image) type you can connect to (apart from Windows Server 2016 Nano which is not supported yet).

AWS Session Manager from the AWS console

AWS Session Manager is part of AWS Systems Manager. It's useful to know when you are using Session Manager through the AWS console for the first time. Actually there are two ways to use Session Manager in the AWS console which differs in functionality and required permissions for the connecting user:

• Connect to instance menu
• Systems Manager menu

Connect to instance menu

It's for users that just want to connect to the EC2 instance and don't care at the moment or shouldn't be able to configure Session Manager or use its other features. It requires less privileges to use, it's easier to find but finally you can only connect to the EC2 and do nothing more. You will find the connect menu on the EC2 lists, just select the desired instance and use the connect button.

Systems Manager menu

By using Systems Manager menu you will gain a full insight into Session Manager features like:

• current active sessions
• historical sessions
• configuration

You will find the above features by going to the Systems Manager and choosing Session Manager from the left side menu. 

AWS Session Manager initiation time

No matter what way you choose to use Session Manager, it will take a few long minutes (commonly for other services it's just a few seconds) before you will be able to access an EC2 instance after meeting all the requirements for the first time. Sandly AWS will even display the same set of information as if you haven't done anything. The following information may be still visible for you:  

We weren't able to connect to your instance. Common reasons for this include:

1. SSM Agent isn't installed on the instance. You can install the agent on both Windows instances and Linux instances.
2. The required IAM instance profile isn't attached to the instance. You can attach a profile using AWS Systems Manager Quick Setup.
3. Session Manager setup is incomplete. For more information, see Session Manager Prerequisites.

There are no instances which are associated with the required IAM role.

Learn how to create and attach the required IAM role to your instances.

It will take few minutes to show the instances here after attaching the required IAM role.

If you are sure that requirements are met don't be fooled by AWS and just wait a little bit longer then refresh the page as it's the only solution then.

Session Manager basic requirements and setup

Setting up Session Manager is fairly easy. Most of the following requirements should be met already for the recently created EC2 with default security group setup (apart from the following permissions requirements).

Permissions requirements

There are two separate permissions requirements than need to be fulfilled in order to use AWS Session Manager:

• the connecting user permissions
   
• the EC2 permissions (instance profile)

The connecting user permissions

If only the root or a sysadmin user will be using Session Manager then this requirement can be skipped. Otherwise the following permissions have to be added in order to make a successful connection to the EC2 through Connect to instance menu:

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Sid": "1",
           "Effect": "Allow",
           "Action": [
               "ec2:DescribeInstances",
               "ssm:DescribeInstanceInformation",
               "ssm:GetConnectionStatus",
               "ssm:StartSession"
           ],
           "Resource": "*"
       }
   ]
}

The above permissions are enough to list EC2 instances and connect to any of them. If you want to use Session Manager also from Systems Manager menu but without possibility to configure the service itself then use the following permissions (notice that the user will be able to see the current and historical sessions):

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Sid": "2",
           "Effect": "Allow",
           "Action": [
               "ec2:describeInstances",
               "ssm:DescribeInstanceInformation",
               "ssm:GetConnectionStatus",
               "ssm:StartSession",
               "ssm:ListAssociations",
               "ssm:DescribeSessions",
               "ssm:DescribeInstanceProperties"
           ],
           "Resource": "*"
       }
   ]
}

Finally if you want to also allow the user to configure Session Manager then attach to him the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "1",
            "Effect": "Allow",
            "Action": [
                "ec2:describeInstances",
                "ssm:DescribeInstanceInformation",
                "ssm:GetConnectionStatus",
                "ssm:StartSession",
                "ssm:ListAssociations",
                "ssm:DescribeSessions",
                "ssm:DescribeInstanceProperties",
                "ssm:CreateDocument",
                "ssm:GetDocument",
                "ssm:UpdateDocument",
                "ssm:DeleteDocument"
            ],
            "Resource": "*"
        }
    ]
}

No matter which permission set you choose it's still not enough to connect to the EC2. You will have to explicitly allow EC2 to use Systems Manager by creating an instance profile and attach it to EC2 as an IAM role.

The EC2 permissions (instance profile)

In order to use Session Manager for accessing an EC2 instance it's necessary to create and attach an instance profile with proper permissions to the EC2 instance. The easiest way to do that is to create a new role in the AWS console. When creating the role, select EC2 as the trusted entity.

Next choose AmazonSSMManagedInstanceCore managed policy and name your role. After creating the role, attach it to the EC2. Notice that you can only have one role attached to an EC2 at a time. If you already have other role attached then skip creating the new role and update the existing policy with the following permissions:

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "ssm:DescribeAssociation",
               "ssm:GetDeployablePatchSnapshotForInstance",
               "ssm:GetDocument",
               "ssm:DescribeDocument",
               "ssm:GetManifest",
               "ssm:GetParameter",
               "ssm:GetParameters",
               "ssm:ListAssociations",
               "ssm:ListInstanceAssociations",
               "ssm:PutInventory",
               "ssm:PutComplianceItems",
               "ssm:PutConfigurePackageResult",
               "ssm:UpdateAssociationStatus",
               "ssm:UpdateInstanceAssociationStatus",
               "ssm:UpdateInstanceInformation"
           ],
           "Resource": "*"
       },
       {
           "Effect": "Allow",
           "Action": [
               "ssmmessages:CreateControlChannel",
               "ssmmessages:CreateDataChannel",
               "ssmmessages:OpenControlChannel",
               "ssmmessages:OpenDataChannel"
           ],
           "Resource": "*"
       },
       {
           "Effect": "Allow",
           "Action": [
               "ec2messages:AcknowledgeMessage",
               "ec2messages:DeleteMessage",
               "ec2messages:FailMessage",
               "ec2messages:GetEndpoint",
               "ec2messages:GetMessages",
               "ec2messages:SendReply"
           ],
           "Resource": "*"
       }
   ]
}

Attaching the role to an EC2 instance can be done from the EC2 instance detail by choosing Modiify IAM role option from the Actions context menu.

EC2 security group

Because the service uses the built-in communication channel instead of SSH protocol, there is no need to open any inbound ports in the EC2's security groups. Things look differently for outbound ports. If you went with the default security group setup when creating an EC2 then you are fine because all outbound ports should be open then. Otherwise open 433 port for the following sources (change region placeholder for the EC2 region):

• ec2messages.region.amazonaws.com
• ssm.region.amazonaws.com
• ssmmessages.region.amazonaws.com

SSM Agent

As mentioned earlier the agent should be already installed on your instance. At least 2.3.68.0 versions have to be installed in order to connect through Session Manager. The higher version the better but 3.0.284.0 is enough to use all the Session Manager features. You can check the agent version on a Linux by typing:

yum info amazon-ssm-agent
# or
sudo systemctl status amazon-ssm-agent

The installation itself is super easy but differs depending on the Operating System and region. That's why I strongly recommend referring to the AWS docs about manual installing the agent if your EC2 has an older ssm version.

How secure is AWS Session Manager

AWS Session Manager is the most secure way to access your EC2 instances. The authentication and authorization is only processed by AWS itself. No need to use ssh keys or open any inbound ports in security groups. Each session is individually signed by Sigv4 and uses encryption in transport (TLS 1.2) by default. Moreover you can easily monitor current and historical sessions from the Systems Manager menu in the console or through CLI.

There are a few things that can harden up Session Manager security though:

• use MFA for all users
   
• create the least privileged users in EC2 instance 
  and use them for Session Manager instead of default ssm-user
   
• specify what instances an IAM user can connect to 
  (refer to the previous paragraph - The connecting user permissions)
   
• enable KMS encryption
   
• enable CloudWatch or S3 logging
   
• shorten up idle session timeout

How to change default ssm-user in Session Manager

Because Session Manager by default uses ssm-user with sudo privileges it's worth considering if it's not too much elevated privilege for users connecting to EC2 instances.

Create a new user

Log into an EC2 instance and type the following in order to create a new user:

sudo useradd new_user

By default a newly created new user won't be attached to sudoers (/etc/sudoers.d/cloud-init) and thus won't have sudo privileges.

Define what OS user will use IAM user

There are two ways to specify what EC2 user have to be used when connecting through Session Manager:

• using Session Manager Preferences (global)
• using IAM Tags (individual)

Session manager preferences

By using Session Manager preferences you will be able to define the default user for any IAM connecting user. This option is available from the System Manager menu.

IAM Tags

By using IAM Tags you are able to override or define a new default Session Manager user for any IAM user individually. Notice that I AM Tags will also override Session Manager Preferences and Enable Run As support for Linux instances options in the Preference has to be enabled (user name can be empty though). In order to define Session Manager user (OS user) for IAM user go to IAM Tags of the user.

Next add a new tag with the name SSMSessionRunAs as the Key and the newly created user name as the Value.

Possible error

If you didn't created correctly a new user or it has been deleted then the following error will appear:

Your session has been terminated for the following reasons:  ----------ERROR------- Unable to start command: failed to start pty since RunAs user new_user does not exist.

The only solution will be to create a new user or attach a different OS user to IAM user as Session Manager won't fall back on the default ssm-user.

Summary

AWS Session Manager is an excellent service providing secure access to your EC2 instances with Bash or PowerShell interactive console without need to use SSH protocol. It's available from Connect to instance menu, Systems Manger menu and CLI. It's well thought over and apart from connecting to EC2 feature also provides nice insight into current and historical sessions. On top of that it's totally free but some limited usage may appear. By using a specific set of permissions it's easy to give and manage IAM user access to different Session Manager options.