云服务器ECS提供控制台内嵌功能，支持将实例登录页面嵌入到外部系统的自建Web页面中，您可以在外部系统中通过ECS Terminal登录云服务器实例并进行相关操作。本文介绍如何将实例登录页面嵌入到外部系统。 ## 背景信息控制台内嵌功能通过安全令牌服务STS实现用户的自定义身份代理，您可以授予IAM用户相关数据和页面的访问权限，以此身份通过STS服务创建临时访问凭证，并获取临时登录Token。您访问内嵌的云服务器控制台页面时，通过URL中封装的临时登录Token进行鉴权，访问过程无需使用IAM用户账密，且登录无感知。涉及的鉴权流程如下： ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_f34456e49fe89d31329d7eacf6448f6f.png) ## 操作步骤 ### 步骤一：获取临时安全令牌 1. 创建IAM角色并授权。 1. [创建IAM角色](https://www.volcengine.com/docs/6257/64979)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_4b21ed775151a12b053a74e9a58cce49.png) 2. 为IAM角色授予ECS服务权限。根据业务需求，为IAM角色授予的权限策略如下所示。[如何新建权限策略并授权](https://www.volcengine.com/docs/6257/1158323)。 ```JSON { "Statement": [ { "Effect": "Allow", "Action": [ "ecs:DescribeInstanceECSTerminalUrl", "ecs:DescribeInstanceVncUrl", "ecs:DescribeInstancesIamRoles", "ecs:CheckPermissionForKeepLogin" ], "Resource": [ "*" ] } ] } ``` 2. 创建IAM用户并授权。 1. [创建IAM用户](https://www.volcengine.com/docs/6257/64977)，用于扮演IAM角色，便于后续获取临时安全令牌。 2. 为IAM用户添加以下权限： * 扮演IAM角色的权限：创建IAM角色时，默认的可信实体为云平台账号，您需要修改IAM角色的信任策略，将Principal（信任身份）中的账号配置修改为您在上一步中创建的IAM账号ID，表示该角色可以被指定的IAM用户扮演。 ```JSON { "Statement": [ { "Effect": "Allow", "Action": [ "sts:AssumeRole" ], "Principal": { "IAM": [ "trn:iam::Account ID:user/Role name" ] } } ] } ``` ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d04631438f5f176c4762d7b4f28d6267.png) * 调用AssumeRole的权限：为IAM角色授予STSAssumeRoleAccess系统策略后，您才能使用IAM用户的访问密钥调用AssumeRole接口申请临时安全令牌。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_81dad3035d1b5cb431de52cfddd242fb.png) 3. 调用[AssumeRole](https://www.volcengine.com/docs/6257/86374)接口获取临时安全令牌。

说明

AssumeRole接口的请求参数DurationSeconds用于指定临时安全令牌的有效期，过期之后需要重新调用此接口获取新的临时安全令牌，并以此请求获取登录Token。

### 步骤二：获取登录Token 调用STS（临时安全凭证）的[getSigninTokenWithSTS](https://www.volcengine.com/docs/6257/160363)接口获取登录Token，调用时需要指定`accessKeyId`、`secretAccessKey` 和`sessionToken`，均为[步骤一](https://www.volcengine.com/docs/6396/1462013#tNEywsDk)中获取的临时安全令牌。登录Token（SigninToken）是STS服务提供的临时访问Token，外部系统的服务端需要通过登录Token构建ECS服务免密访问链接。

说明

登录Token的有效期默认为15分钟且不可更改，请在Token到期前完成访问链接的构建与鉴权登录，到期后需要重新请求getSigninTokenWithSTS获取新的登录Token。

通过登录Token完成一次登录后，登录Token随即失效，如果您刷新页面，则需要重新请求获取登录Token。

请求示例： ```Plain Text https://console.volc-embed.com/api/passport/login/getSigninTokenWithSTS &accessKeyId= &secretAccessKey= &sessionToken= &sessionDuration= ``` ### 步骤三：构建免密访问链接 ECS云服务器控制台的免密访问链接格式如下所示。 ```TypeScript const target_url = https://console.volc-embed.com/api/passport/login/loginWithSigninToken?signinToken=${signinToken}&redirectURI=${target_console_url} ``` |参数 |说明 | |---|---| |signinToken |[步骤二](https://www.volcengine.com/docs/6396/1462013#MoXMsB6f)中获取的登录Token。 | |redirectURI |支持内嵌的ECS实例登录页面的URL，如下所示：

```XML```
```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```

> 参数介绍：

> * `xterm`：仅支持非Windows实例使用。如果是Windows实例，请将`xterm`替换为`guac`。

> * `Id`、`Region`、`Name`、`IP`：分别为实例ID、实例所属地域ID、实例名称、以及实例的私网IP地址。相关信息的获取方式，请参考[查看实例信息](https://www.volcengine.com/docs/6396/70548#%E5%9C%A8%E5%AE%9E%E4%BE%8B%E5%88%97%E8%A1%A8%E9%A1%B5%E6%9F%A5%E7%9C%8B)、[地域和可用区介绍](https://www.volcengine.com/docs/6396/67719)。

注意

在使用如上redirectURI链接前，需先使用encodeURL转码链接。即您需要先根据实际值替换链接中的xterm、Id、Region、Name、IP等参数，再通过encodeURL转码链接。

转码后的链接示例如下：

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

| ### 步骤四：在外部系统中嵌套页面以iFrame方式或者直接跳转URL的方式将ECS服务控制台嵌入到第三方自建Web页面中。您可以参考以下示例，在外部系统中嵌入ECS服务控制台页面。其中src或者href的值应指定为[步骤三](https://www.volcengine.com/docs/6396/1462013#ndf2SUSy)中构建的免密访问链接(target_url)。

注意

为避免因浏览器兼容性导致访问失败，推荐使用Chrome浏览器访问该页面。

* iFrame方式： ```XML ``` * URL方式： ```HTML remote connection ``` ## 常见问题 **如何设置内嵌页面的登录态时长？** 通过第三方系统的Web页面免密登录ECS服务控制台页面之后，登录状态会维持一段时间，超期之后应用服务端需要重新获取并刷新Token，以便用户侧重新登录。内嵌页面的登录态时长由[getSigninTokenWithSTS](https://www.volcengine.com/docs/6257/160363)接口的可选参数`sessionDuration` 指定，单位为秒，取值范围为900 ~ 43200。不传入该参数时，将默认维持[AssumeRole](https://www.volcengine.com/docs/6257/86374)接口的`DurationSeconds`参数设置，而`DurationSeconds`默认为1 小时。即默认情况下，AssumeRole接口返回的`ExpiredTime`既是临时安全令牌的有效期截止时间，也是登录状态的结束时间。 ## 示例代码（Node.js） ```JavaScript const {Service} = require('@volcengine/openapi'); const axios= require("axios"); class StsService extends Service { constructor(props) { super({ ...props, defaultVersion: "2018-01-01", serviceName: "sts", }); } } async function main() { const stsService = new StsService() stsService.setAccessKeyId('xxx'); stsService.setSecretKey('yy') stsService.setHost('sts.volcengineapi.com') // 调用 assumeRole 获取临时安全令牌。const assumeRole = stsService.createAPI('AssumeRole', { method: 'GET', }); const token = await assumeRole({ RoleTrn: 'trn:iam::${accountId}:role/${Role name}', RoleSessionName: 'test' }) const { AccessKeyId, SecretAccessKey, SessionToken } = token.Result.Credentials; // 根据临时安全令牌获取登录 token。const signinResp = await axios.post('https://console.volc-embed.com/api/passport/login/getSigninTokenWithSTS', { "accessKeyId": AccessKeyId, "secretAccessKey": SecretAccessKey, "sessionToken": SessionToken }) const signinToken = signinResp.data.Result.SigninToken; // 根据登录 signinToken 生成免登录连接。const url = `https://console.volc-embed.com/api/passport/login/loginWithSigninToken?signinToken=${signinToken}&redirectURI=${encodeURIComponent(`https://iaas-api.console.volc-embed.com/ecs/connect/xterm/?Id=${实例ID}&Region=${Region}&Name=${实例名称}&Ip=${实例私网 IP}&Env=volc&lang=zh`)}` console.log(url) } main(); ```