Connect to an instance by using Session Manager - Elastic Compute Service

Session Manager is a free-of-charge tool provided by Alibaba Cloud to allow you to connect to Elastic Compute Service (ECS) instances. Developed based on technologies, such as Cloud Assistant and WebSocket, Session Manager supports password-free and jump server-free logons to instances, without the need for Internet connection. This topic describes the usage scenarios and usage notes of Session Manager.

What is Session Manager?

Important

Session Manager is free of charge. If you want to store Session Manager operation records, you must enable the Session Operation Record Delivery feature. For more information, see Use the Session Record Delivery feature.

Session Manager provides the following features:

Password-free connection: You do not need to enter a password when you connect to an instance.
Connection to instances without Internet access: Session Manager allows you to connect to instances without the need to connect to the Internet or configure a jump server.
When you use Session Manager to connect to an instance, related commands are sent to the ECS instance by the Session Manager server of Alibaba Cloud.
Support for multiple client types:
- Alibaba Cloud Management Console: For information about how to use Session Manager Client in the browser to connect to an instance, see Connect to an instance by using Session Manager.
- Command lines that require the installation of ali-instance-cli: For information about how to use Session Manager to connect to an instance on your computer, see Connect to an instance by using ali-instance-cli.

Logon user description

By default, you use Session Manager to connect a Linux instance as the ecs-assist-user user and to a Windows instance as the system user.

ecs-assist-user: a regular user in Linux. The ecs-assist-user user does not have system-level permissions and can perform only authorized operations. You can run sudo commands to grant temporary root permissions to the ecs-assist-user user.
system: an on-premises system account in Windows that has the highest system permissions.

Limitations and Prerequisites

The instance to which you want to connect is in the Running state.
Cloud Assistant Agent is installed on the instance. Session Manager is implemented based on Cloud Assistant Agent.
Cloud Assistant Agent is pre-installed on ECS instances that are created from Alibaba Cloud public images on or after December 1, 2017. For ECS instances created before December 1, 2017, you must manually install Cloud Assistant Agent. For more information, see Install Cloud Assistant Agent.
Network connectivity is available. Make sure that the instance is connected to the Cloud Assistant server. This allows Cloud Assistant Agent to communicate with the Cloud Assistant server over WebSocket. For more information, see the Security group settings section of this topic.
Up to 1,000 sessions can be created and remain available per region. Each ECS instance can have up to 20 sessions in the connected state. The bandwidth is limited to 200 kbit/s for each session.

Other features and scenarios

Access services without Internet connection by using the port forwarding feature
You can use the port forwarding feature of Session Manager Client to map a service port of an ECS instance to a port on your on-premises machine. Then, you can send requests to the on-premises port to access the services on the ECS instance. For example, you can access a web backend service deployed over an internal network or connect to an instance over an internal network by using SSH. Session Manager establishes WebSocket connections over TCP. Therefore, The port forwarding feature only supports TCP port forwarding and does not support UDP port forwarding. For more information, see Connect to an instance without Internet connection by using the port forwarding feature of Session Manager CLI.
Add a temporary SSH public key to an instance
When you use SSH to connect to an instance, you can use Session Manager to add a temporary public key that is valid for 60 seconds to the instance. Then, you can connect to the instance by using the key pair that contains the temporary public key and a private key. For more information, see Use the Session Manager CLI to register a temporary public key for password-free logon to an instance.
Use the Session Record Delivery feature
If you want to establish sessions with multiple users, you can use the Session Record Delivery feature to view the operation records of a specific user for subsequent operation auditing. For information about how to enable the Session Record Delivery feature, see Use the Session Record Delivery feature.

How Session Manager works

As shown in the following figure, when you connect to an ECS instance by using Session Manager, Session Manager Client and the ECS instance establish WebSocket connections to the Cloud Assistant server. After the connections are established, each command that you enter is forwarded to the instance by the Cloud Assistant server and run by Cloud Assistant Agent on the instance.

Modules involved in the figure

Cloud Assistant client: the client tool that you use, such as Session Manager in the ECS console, ali-instance-cli on your on-premises machine, or Cloud Assistant Agent.
Cloud Assistant server: Session Manager is implemented based on Cloud Assistant to manage permissions and the session status.
Cloud Assistant Agent installed on an instance: runs commands that you enter.

Connection description

When Session Manager Client establishes a WebSocket connection to the Cloud Assistant server (Steps 2 to 4), the Cloud Assistant server authenticates Session Manager Client to determine whether you have the permissions to connect to the instance by using Session Manager. For information about the relevant permissions, see the Permission management section of this topic.
When Cloud Assistant Agent in ECS establishes a WebSocket connection to the Cloud Assistant server (Steps 5 and 6), the Cloud Assistant server notifies Cloud Assistant Agent to establish a connection. Then, Cloud Assistant Agent actively establishes a connection to the Cloud Assistant server.
Take note that the outbound WebSocket port must be open for the ECS instance to access the Cloud Assistant server. The connection process is irrelevant to the inbound rules of the security group to which the ECS instance belongs. For more information, see the Security group settings section of this topic.

Security

Encryption: The Web Socket Secure (WSS) protocol is used to establish persistent WebSocket connections between the Session Manager Client and the Cloud Assistant server and between the Cloud Assistant server and Cloud Assistant Agent. To improve data security, the WSS protocol encrypts persistent WebSocket connections by using the Secure Socket Layer (SSL) protocol.
Authentication: When you use Session Manager to connect to instances, you do not need to manage instance passwords, and the instances have no risks of password leaks. Compared with SSH and Virtual Network Computing (VNC) that use username/password-based authentication, Session Manager uses Resource Access Management (RAM)-based authentication. For information about the relevant permissions, see the Permission management section of this topic.
Network: After a WebSocket connection is established between Cloud Assistant Agent installed on an instance and the Cloud Assistant server, you can use Session Manager instead of SSH or VNC to connect to the instance, without the need to open ports for inbound traffic on the instance. This improves the security of the instance.

Connection process

Connect to an instance by using Session Manager in the ECS console (in a browser).
Log on to the Alibaba Cloud Management Console in a browser and use Session Manager to connect to the instance. For more information, see Connect to an instance by using Session Manager. The following figure shows the process.
Connect to an instance by using Session Manager on your on-premises computer (on the on-premises CLI).
You can install ali-instance-cli on your on-premises computer and use the on-premises CLI to connect to the instance by using Session Manager.
For more information, see Connect to an instance by using ali-instance-cli. The following figure shows the process.

Permission management

If you want to use a RAM user to connect to an instance by using Session Manager, you must have the required permissions. The following table describes the required permissions.

The Action column corresponds to the action in a RAM policy.

Action	Description
`ecs:StartTerminalSession`	Connect to an ECS instance by using Session Manager. (Required)
`ecs:DescribeCloudAssistantStatus`	Query whether Cloud Assistant Agent is installed on an ECS instance. The system checks this permission before you connect to an instance in the ECS console.
`ecs:DescribeUserBusinessBehavior`	Query whether Session Manager is enabled. The system checks this permission before you connect to an instance in the ECS console.
`ecs:ModifyCloudAssistantSettings`	Enable or disable Session Manager. If Session Manager is enabled for the current Alibaba Cloud account, you do not need to grant this permission.

Examples of permission policies

Example 1: Use Session Manager in the ECS console

If a RAM user wants to use Session Manager to connect to an instance in the ECS console, the RAM user must be granted the following permissions based on the principle of least privilege:

ecs:StartTerminalSession: The permission to connect to an instance by using Session Manager. You can configure the Resource parameter to specify the ECS instances to which a RAM user can connect by using Session Manager.
ecs:DescribeCloudAssistantStatus: The permission to query whether Cloud Assistant Agent needs to be installed on an ECS instance. The system checks this permission before you connect to an instance in the ECS console.
ecs:DescribeUserBusinessBehavior: The permission to query whether Session Manager is enabled. The system checks this permission before you connect to an instance in the ECS console.
(Optional) ecs:ModifyCloudAssistantSettings: The permission to enable or disable Session Manager. If Session Manager is enabled for the current Alibaba Cloud account, you do not need to grant this permission.

Sample custom policy:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ecs:StartTerminalSession",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:DescribeUserBusinessBehavior",
        "ecs:DescribeCloudAssistantStatus",
        "ecs:ModifyCloudAssistantSettings"
      ],
      "Resource": "*"
    }
  ]
}

For information about how to grant permissions to a RAM user, see Grant permissions to a RAM user.

Example 2: Connect to an instance by using ali-instance-cli

When you use ali-instance-cli, you must specify the AccessKey pair and Security Token Service (STS) token of the RAM user. When you connect to an instance by using Session Manager, the system verifies whether the RAM user who has the credentials also has the ecs:StartTerminalSession permission.

When you configure a custom policy, you can configure the Resource parameter to specify the ECS instances to which a RAM user can connect by using Session Manager. Sample policy:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ecs:StartTerminalSession",
      "Resource": "*"
    }
  ]
}

For information about the CredentialsURI and STS Token parameters, see Create an AccessKey pair and What is STS?

For information about how to grant permissions to a RAM user, see Grant permissions to a RAM user.

Security group settings

When you use Session Manager to connect to an ECS instance, make sure that Cloud Assistant Agent running on the ECS instance is connected to the Cloud Assistant server by adding the following rules to an outbound security group:

Compared with connection methods, such as SSH and Remote Desktop Protocol (RDP), Cloud Assistant Agent actively establishes a WebSocket connection to the Session Manager server. You need to only open the outbound WebSocket port of the Cloud Assistant server in a security rule. For information about how Session Manager works, see the How Session Manager works section of this topic.

Important

If you use basic security groups including the default security group, all outbound traffic is allowed. No additional configuration is required.
If you use an advanced security group, all outbound traffic is denied. You must configure the relevant rules. The following table describes the rules. For information about security groups, see Basic security groups and advanced security groups.

For information about how to add rules to a security group, see Add a security group rule.

Action	Priority	Protocol type	Port range	Authorization object	Description
Allow	1	Custom TCP	443	`100.100.0.0/16`	This port is used to access the Cloud Assistant server.
Allow	1	Custom TCP	443	`100.0.0.0/8`	This port is used to access the server on which the Cloud Assistant Agent installation package is stored when you want to install or update Cloud Assistant Agent.
Allow	1	Custom UDP	53	`0.0.0.0/0`	This port is used to resolve domain names.

If you want to connect to an instance by using only Session Manager, delete the inbound rules that allow the SSH port (default 22) and RDP port (default 3389) from a security group to improve the security of the ECS instance.

Integrate the Session Manager feature in your applications for logon to instances

For the complete code used to connect to an ECS instance or a managed instance by using Session Manager, see cloud-assistant-starter. The AxtSession.tsx file in this project contains the sample code for calling the StartTerminalSession operation to obtain WebSocketURL and establish a connection. After you port the code to your enterprise application, you can use Session Manager to connect to instances.