Docs

Elastic Compute Service

Instance configuration

Console embedding - Using ECS Terminal to log in to instances in external systems

For ECS instances, console embedding is available, which supports embedding the instance login page into custom web pages of external systems. This allows you to use ECS Terminal to log in to ECS instances for operations in external systems. This topic describes how to embed the instance login page into external systems.

Background

Console embedding enables custom identity proxy via the Security Token Service (STS). Specifically, you can grant IAM users permissions to access relevant data and pages. Then, with this authorized IAM user identity, you can obtain an access credential and a login Token temporarily via the STS service. When you access the embedded ECS console page, authentication is performed via the temporary login Token encapsulated in the URL. Therefore, in the access process, you can log in without entering an IAM user account or a password.

Procedure

Step 1: Obtain a temporary security token

Create an IAM role and grant permissions.

Create an IAM role.

Grant permissions of ECS services to the IAM role. Below are business-based permission policies that are granted to the IAM role: Procedure of creating and granting permissions to permission policies.

{
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecs:DescribeInstanceECSTerminalUrl",
"ecs:DescribeInstanceVncUrl",
"ecs:DescribeInstancesIamRoles",
"ecs:CheckPermissionForKeepLogin"
],
"Resource": [
"*"
]
}
]
}

Create an IAM user and grant permissions.

Create an IAM user to assume the IAM role and to obtain a temporary security token for operations afterwards.

Grant the following permissions to the IAM user:

Permission to assume the IAM role: By default, the target that can be trusted by an IAM role is a cloud platform account. This means that you need to modify the trust policy of the IAM role by specifying the account in the Principal (trusted identity) as the IAM account ID you created in the previous step. This allows the specified IAM user to assume the created role.

{
"Statement": [
{
"Effect": "Allow",
"Action": [
"sts:AssumeRole"
],
"Principal": {
"IAM": [
"trn:iam::Account ID:user/Role name"
]
}
}
]
}

Permission to call AssumeRole: After attaching the STSAssumeRoleAccess system policy to the IAM role, you can use the access key of the IAM user to call the AssumeRole API and apply for a temporary security token.

Call the AssumeRole interface to obtain the temporary security token.

tip

You can configure the request parameter DurationSeconds of the AssumeRole interface to specify the validity period of the temporary security token. After the temporary security token expires, you need to call this interface again to obtain a new one and use it to request a login Token.

Step 2: Obtain the login Token

Call the getSigninTokenWithSTS interface of STS to obtain the login Token. During this process, configure accessKeyId, secretAccessKey, and sessionToken based on the temporary security token obtained in Step 1.

Login Token (SigninToken) is a temporary access Token provided by the STS service. The server of an external system uses this Token to build a password-free link to access ECS.

tip

The default validity period of a login Token is 15 minutes and cannot be changed. Therefore, build the access link, and then complete an authenticated login before the Token expires. After expiration, you need to call getSigninTokenWithSTS again to obtain a new Token.

The login Token becomes invalid as soon as it is used for one login. If you refresh the page, call the API again to obtain a new login Token.

Request example:

Step 3: Build a password-free access link

The format of the password-free link to access the ECS console is as follows.

Parameter	Description
signinToken	Indicates the login Token obtained in Step 2.
redirectURI	Indicates the URL supporting the embedded login page of ECS instances, with details as follows: https://iaas-api.console.volc-embed.com/ecs/connect/xterm/?Id=${Instance ID}&Region=${Region}&Name=${Instance name}&Ip=${Instance private IP}&Env=volc&lang=zh Parameter descriptions: xterm: Only used for non-Windows instances. For Windows instances, replace xterm with guac. Id, Region, Name, and IP: Indicate instance ID, ID of the region where the instance is located, instance name, and instance private IP address, respectively. To learn related information, refer to Viewing instance information and Regions and availability zones. warning Before using the above redirectURI link, you need to encode the link via encodeURL first. Specifically, replace values of parameters such as xterm, Id, Region, Name, and IP in the link with actual values, and then encode the link via encodeURL. Sample link after transcoding: https://iaas-api.console.volc-embed.com/ecs/connect/xterm/?Id=i-xxxxxxxxxxx&Region=cn-beijing&Name=terminal%E6%B5%8B%E8%AF%95&Ip=192.168..&Env=volc&lang=zh

Step 4: Embed the page into external systems

You can embed the ECS service console into a third-party custom web page via iFrame or direct URL redirection. For embedding operations, the following examples are for your reference. Replace values of src and href with the password-free access link (target_url) built in Step 3.

warning

To avoid access failures caused by browser incompatibility, we recommend that you use Chrome to access the page.

Via iFrame:

<body>
<iframe src="target_url" width="1200" height="800" id="tlsIframePage"></iframe>
</body>

Via URL:

<body>
<a href="target_url" target="_blank">remote connection</a>
</body>

FAQ

How to configure login session duration of embedded pages?

After you log in to the ECS service console password-free in the web page of a third-party system, the login session remains valid for a period. Once the session expires, the server obtains a new Token, which allows you to log in again.

The session duration of an embedded page is specified by the optional parameter sessionDuration of the getSigninTokenWithSTS interface. Unit: seconds. Value range: 900 - 43200. If this parameter is not passed in, the duration defaults to the value set for DurationSeconds in the AssumeRole interface. Default value of DurationSeconds: 1 hour. Specifically, by default, the returned ExpiredTime value after the AssumeRole interface is called indicates the expiration time of both the validity period for the temporary security token and the login session.

Sample codes (Node.js)

Last updated: 2026.06.25 15:25:02